@wular/coder 0.3.17 → 0.4.0

package/migrations/meta/_journal.json

@@ -0,0 +1,13 @@
+{
+  "version": "7",
+  "dialect": "postgresql",
+  "entries": [
+    {
+      "idx": 0,
+      "version": "7",
+      "when": 1791302072514,
+      "tag": "0000_initial",
+      "breakpoints": true
+    }
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wular/coder",
-  "version": "0.3.17",
+  "version": "0.4.0",
   "description": "Delegating coding-agent runtime",
   "type": "module",
   "main": "./dist/sdk.js",
@@ -19,21 +19,32 @@
     "coder": "bin/coder.mjs"
   },
   "scripts": {
-    "build": "tsdown && bunx prettier --write 'dist/**/*.d.ts' --log-level warn",
-    "dev": "bun run build --watch",
-    "typecheck": "tsc -p tsconfig.json --noEmit",
-    "validate-plugin:cursor": "node scripts/validate-template.mjs",
+    "build": "bun scripts/build.ts",
+    "build:dash": "bun scripts/build.ts dash",
+    "dev:dash": "pnext dev src/server/dash",
+    "dev": "tsdown --watch",
+    "typecheck": "tsc -p tsconfig.json --noEmit && pnext typegen src/server/dash && tsc -p src/server/dash/tsconfig.json --noEmit",
+    "validate-plugin:cursor": "node scripts/validate-cursor-plugin.mjs",
     "version-bump:patch": "node scripts/bump.mjs patch",
     "version-bump:minor": "node scripts/bump.mjs minor",
-    "version-bump:major": "node scripts/bump.mjs major"
+    "version-bump:major": "node scripts/bump.mjs major",
+    "format": "prettier --write \"src/**/*.{ts,tsx}\" \"scripts/**/*.ts\" \"*.md\" \"docs/**/*.md\""
   },
   "files": [
     "bin",
     "dist",
+    "src/server/dash",
+    "!src/server/dash/serve.ts",
+    "src/server/auth/sign-in.ts",
+    "src/client/index.ts",
+    "src/client/types.ts",
+    "src/core/errors.ts",
+    "src/core/task/log-view.ts",
     "plugins",
     ".claude-plugin",
     "README.md",
-    "docs"
+    "docs",
+    "migrations"
   ],
   "publishConfig": {
     "access": "public"
@@ -42,10 +53,29 @@
     "node": ">=18"
   },
   "dependencies": {
+    "@chat-adapter/github": "4.41.1",
+    "@chat-adapter/gmail": "4.41.1",
+    "@chat-adapter/linear": "4.41.1",
+    "@chat-adapter/slack": "4.41.1",
+    "@chat-adapter/teams": "4.41.1",
+    "@octokit/auth-app": "8.3.1",
+    "@tanstack/virtual-core": "3.17.1",
+    "@wular/pnext": "0.1.5",
+    "chat": "4.41.1",
+    "drizzle-orm": "0.45.2",
+    "jose": "6.2.12",
+    "openid-client": "6.8.8",
+    "postgres": "3.4.9",
+    "preact": "10.29.2",
+    "preact-render-to-string": "6.7.0",
+    "simple-icons": "15.0.0",
     "zod": "^4.4.3"
   },
   "devDependencies": {
+    "@electric-sql/pglite": "0.5.8",
     "@types/node": "^26.1.2",
+    "drizzle-kit": "0.31.10",
+    "prettier": "^3.6.2",
     "tsdown": "^0.22.13",
     "typescript": "^5.9.3"
   }

package/plugins/agents/skills/coder/SKILL.md

@@ -1,84 +1,38 @@
 ---
 name: coder
-description: Use Coder to dispatch any coding, implementation, or investigation task - features, fixes, refactors, debugging, tests, code questions - one coder per focused goal, fanned out in parallel. Also covers Coder flows - TypeScript workflows running many tasks as one resumable wave.
+description: Use Coder for coding, implementation, or investigation tasks - features, fixes, refactors, debugging, tests, code questions - one coder per focused goal, fanned out in parallel, waiting on each task. Use it when asked, when a task needs another engine (Claude, Codex, custom), or when a subagent is sufficient or required for the task.
 ---
 
 # Coder dispatch
 
-(If `CODER_WORKER` is set in your environment, you _are_ a coder worker: stop reading, skip this skill, and do your assigned work directly - nested dispatch is disabled.)
+If `CODER_WORKER` is set in your environment, you are a coder worker. Skip this skill and do your assigned work directly; nested dispatch is disabled.
 
 You dispatch coding tasks through the `coder` runtime instead of implementing them yourself.
 
 ## Overview
 
-Coder delegates coding to supervised subagents of any model - Codex, Claude, or any OpenAI-compatible/local endpoint - from one runtime on every host. Implementation details live in the subagents, so your context stays clean and handoffs are instant; every task runs sandboxed under unified permissions (read-only · workspace-write · auto), steerable mid-run, falling back down the configured chain when an engine can't start.
-
-`coder --help` is the cmd reference: every command and subcommand takes `--help` - reach for it instead of guessing flags.
-
-Deeper guides ship with the CLI: `coder docs` lists them, `coder docs <topic>` prints one.
+Coder delegates coding to supervised subagents of any model - Codex, Claude, or any OpenAI-compatible or local endpoint - from one runtime on every host. Implementation details live in the subagents, so your context stays clean and handoffs are instant. Every task runs sandboxed under unified permissions (read-only, workspace-write, auto), is steerable mid-run, and falls back down the configured chain when an engine cannot start.
 
 ## Setup
 
-If `coder` is not on PATH, install it yourself without asking (`npm install -g @wular/coder`). When a dispatch fails because engines are missing or logged out, run `coder setup-host` and follow its output - it checks engines and auth, fixes what it can, and prints the exact fix for the rest (safe to re-run anytime). Ask the user before installing an engine CLI or changing auth; if it updated codex, tell the user to restart their codex session.
-
-## Dispatching a task
-
-- `coder` commands are safe to run in the terminal - the runtime is a supervisor and enforces its own OS sandbox and approval policy on the task. If your harness sandboxes terminal commands or asks approval for them (Codex does both), run every `coder` command with escalated/approved permissions; never retry a blocked `coder` call inside a (stricter) sandbox or with env workarounds.
-- One coder per focused goal. When the work splits into independent parts, decompose it and dispatch each part as its own `coder task run` call - fan out a wide web of coders running in parallel, not one giant dispatch. Give each coder a self-contained goal with all context - overview, file paths, constraints (read-only, git rules). Run independent tasks concurrently; use `steer` to continue a single coder's thread.
-- Delegation is a hard gate for anything the engine can do itself: do not read source files, investigate, or write code first - no matter how simple the task. Fold into the task text whatever only you have - conversation context, results from tools the engine lacks. The coder worker runs with plugins disabled (no skills, MCP, or connectors), so include any context only a plugin or MCP tool of yours produced.
-- Compose one self-contained task text (goal, relevant paths, constraints) and dispatch it - it backgrounds by default and prints a task id:
+If `coder` is not on PATH, install it yourself without asking: `npm install -g @wular/coder`. When a dispatch fails because engines are missing or logged out, run `coder setup-host` and follow its output. It checks engines and auth, fixes what it can, prints the exact fix for the rest, and is safe to re-run. Ask the user before installing an engine CLI or changing auth; if it updated codex, tell the user to restart their codex session.
 
-  ```bash
-  coder task run --system "<standing instructions>" "<task text>"
-  ```
+## Using the CLI
 
-  Fetch the answer with `coder task result <task-id> --wait` - blocks until done, prints only the final result. Run it in a background shell so it does not block you. For a fan-out, start one such background waiter per dispatched task (see Supervision loop).
+- The CLI is the reference. `coder --help` and every subcommand's `--help` list the flags and exit codes, and each command prints the recommended next step when it returns. Follow it.
+- `coder docs` lists the deeper guides; `coder docs <topic>` prints one.
+- If your harness sandboxes or gates terminal commands (Codex does both), run every `coder` command with escalated permissions; the runtime is a supervisor with its own sandbox and approval policy.
 
-- A `--wait` (on `run` or `result`) exits **4** when the task is waiting on a permission approval: relay the approval to the user, apply their decision with `coder approve <task-id> <approval-id> [--deny]`, then re-fetch with `coder task result <task-id> --wait`. (Unanswered approvals auto-deny after 120s and the task moves on.)
+## Running tasks
 
-- `coder task run` exits after its startup check. Exit 0: the task started - relay the task id and fetch its result (above). Exit 1: it failed to start or the turn failed - report it, do not retry or fall back yourself. Exit 3: no engine in the chain could start and stdout carries a `run-native-subagent` payload - see below.
-- When the first engine can't start (auth, quota, rate limit), the runtime automatically falls back to the next engine in the chain, runs the same task on it, and still exits 0 - so just fetch the result. If the failure mentions a usage-limit reset time, relay that to the user.
-- Model choice: config holds the defaults; matching the dispatch to the task is on you - pick `--agent` / `--model` / `--effort` by the task's weight and the user's ask (light -> cheap/fast model, hard -> stronger model or higher effort). `coder task run --help` lists agents, models, and efforts; `coder model list` shows custom models.
-- Permissions default to auto mode (workspace-write + policy-answered escalations). Pass `--permissions read-only` when the task is read-only; `--permissions workspace-write` to forbid any escalation beyond the project.
-- Network access escalates by default in auto mode; hosts in `approvals.allowedNetworkHosts` (coder config, subdomains included) need no approval. If a trusted host keeps escalating, suggest allowlisting it: `coder config set approvals.allowedNetworkHosts '["registry.npmjs.org"]'`.
-
-## Flows (multi-task workflows)
-
-When the user asks for a workflow - a repeatable multi-task wave with verification gates and crash/resume - author a Coder flow instead of hand-fanning tasks: a TypeScript file the runtime executes, written to `.coder/flows/<name>.ts` for the user to review. Before writing or editing one, always read the full reference first:
+Start with `coder task run --help`. It says how to write a good task and what happens after dispatch. `coder task --help` lists the rest, result, steer, stop, list and approvals. Then run it:
 
 ```bash
-coder docs flows    # authoring conventions, primitives, resume rules
-coder flow --help   # command reference
+coder task run "Add a /health endpoint in src/server.ts that returns 200 with the git sha. Do not touch routes outside that file."
 ```
 
-Preview with `--dry-run` before spending tokens - and note flow tasks are normal coder tasks, so steer/stop/list work on them.
-
-Once a run is going, tell the user to run `coder flow watch <run-id>` to see live progress and overview of its tasks as the wave goes. Give them the actual run id, not a placeholder.
-
-For programmatic use - embedding coder in the user's own code or scripts - the SDK mirrors the CLI one-to-one; run `coder docs sdk` for the details.
-
-## Last resort: run-native-subagent payload (exit 3)
-
-When no coder engine can start (missing binaries, auth, quota across the whole chain), the runtime exits 3 with a JSON payload (`fallback.action: "run-native-subagent"`). Mention the failure to the user (including any limit-reset time). If your harness has a subagent facility, spawn one subagent whose prompt is the payload's `task` verbatim, prefixed with: "NEVER run git write operations (commit, checkout, stash, reset, push, etc.); leave changes uncommitted." If the payload's `permissions` is not `auto`, append it: `read-only` means investigate and report without modifying anything; `workspace-write` means never touch anything outside the workspace. Relay its output when it completes. If your harness has no subagent facility, report the failure and stop - never implement the task yourself.
-
-## Supervision loop
-
-With coders running in the background, don't fire-and-forget: hold one background `coder task result <task-id> --wait` shell per task - each returns when its task finishes (relay the answer, dispatch newly unblocked coders) or escalates an approval (exit 4, see above; restart the waiter after answering). Only without background shells, fall back to recurring check-ins (whatever scheduling facility your harness has; interval by the work's pace, 10m default; bump `approvals.escalationTimeoutMs` above it so escalations survive between ticks): each tick `coder task list`, fetch finished results, surface pending approvals.
-
-## Controlling tasks
-
-- Continue prior work ("keep going", "apply the top fix"): `coder task steer <task-id> "<follow-up>"`.
-- Question a task without interrupting it (status, decisions, "why did it do X"): `coder task ask <task-id> "<question>"` - a read-only sidecar answers from the task's log and workspace; the task never sees it.
-- Inspect: `coder task result <task-id>` (status + answer; add `--wait` to block until done) and `coder task list`. (`coder task watch <task-id>` streams the live progress log - to watch/debug in special cases, generally not for you to consume.)
-- Interrupt: `coder task stop <task-id>`.
-- If status shows `pendingApprovals`, surface them to the user; apply their decision with `coder task approve <task-id> <approval-id> [--deny]`.
-
-## Model notes
-
-`spark` has its own usage limits, is fast and suited to mechanical work, and is available only on Pro plans during research preview.
+Follow what it prints.
 
-## Hard rules
+## Flows
 
-- Forward task text verbatim in `steer` follow-ups - never rewrite or summarize what the user asked for.
-- Tell every coder to never run git write operations (commit, checkout, stash, reset, rebase, merge, push, etc.) and to leave changes uncommitted.
-- Pass the user's constraints (read-only, scoped paths) into each coder's task text, and honor them over your own preferences.
+When the user asks for a repeatable multi-task workflow with verification gates and resume, author a Coder flow instead of hand-fanning tasks. Read `coder docs flows` before writing or editing one, preview with `--dry-run`, and once it runs give the user the real `coder flow watch <run-id>` command.

package/plugins/claude/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "coder",
-  "version": "0.3.17",
+  "version": "0.4.0",
   "description": "Delegate coding tasks to supervised Coder subagents running on Codex, Claude, or any OpenAI-compatible model. Your main context stays clean.",
   "author": {
     "name": "muzam1l"

package/plugins/claude/commands/setup.md

@@ -13,10 +13,10 @@ needs the user's decision. Use AskUserQuestion for the decision points.
    (codex/claude availability and auth are in the JSON).
 2. Codex is the recommended primary engine; Claude (opus subagents in Claude Code) is the fallback. Choose the default from what is installed. Do NOT ask about chain ordering:
    - **Codex installed** (logged in, or logged out; installed still counts): keep the default `codex → claude` chain.
-     - **Auto-update if stale**: the default codex model is a GPT-5.6 tier, which needs codex `>= 0.144`. Parse the version from the JSON's `codex.detail` (e.g. `codex-cli 0.143.0`); if it is below `0.144.0`, update it automatically without asking with `codex update` (codex's own updater - it detects the install method and refetches the binary; fall back to `npm install -g @openai/codex@latest` if that fails), then re-run `coder setup-host --json` to confirm.
+     - **Auto-update if stale**: the default codex model is a GPT-6 tier, which needs codex `>= 0.144`. Parse the version from the JSON's `codex.detail` (e.g. `codex-cli 0.143.0`); if it is below `0.144.0`, update it automatically without asking with `codex update` (codex's own updater - it detects the install method and refetches the binary; fall back to `npm install -g @openai/codex@latest` if that fails), then re-run `coder setup-host --json` to confirm.
      - If it is logged out, tell the user to run `codex login` themselves, then re-run `coder setup-host` to confirm.
    - **Codex not installed**: run `coder config set chain claude,codex` so tasks run on Claude opus subagents immediately, tell the user that is the default for now, then ask (AskUserQuestion) whether to install Codex since it is the recommended primary. On yes: `npm install -g @openai/codex`, have them run `codex login`, then `coder config set chain codex,claude`.
-3. Show the final config (`coder config`) and mention overrides live in `~/.coder/config.json` (machine) and `coder.config.json` (per repo).
+3. Show the final config (`coder config list`) and mention overrides live in `~/.coder/config.json` (machine) and `coder.config.json` (per repo).
 4. Suggest trying it: "Use Coder to <some small task>".
 
 $ARGUMENTS

package/plugins/claude/skills/dispatch/SKILL.md

@@ -1,82 +1,38 @@
 ---
 name: dispatch
-description: Use Coder to dispatch any coding, implementation, or investigation task - features, fixes, refactors, debugging, tests, code questions - one coder per focused goal, fanned out in parallel. Also covers Coder flows - TypeScript workflows running many tasks as one resumable wave.
+description: Use Coder for coding, implementation, or investigation tasks - features, fixes, refactors, debugging, tests, code questions - one coder per focused goal, fanned out in parallel, waiting on each task. Use it when asked, when a task needs another engine (Claude, Codex, custom), or when a subagent is sufficient or required for the task.
 ---
 
 # Coder dispatch (Claude host)
 
-(If `CODER_WORKER` is set in your environment, you _are_ a coder worker: stop reading, skip this skill, and do your assigned work directly - nested dispatch is disabled.)
+If `CODER_WORKER` is set in your environment, you are a coder worker. Skip this skill and do your assigned work directly; nested dispatch is disabled.
 
 You dispatch coding tasks through the `coder` runtime instead of implementing them yourself.
 
 ## Overview
 
-Coder delegates coding to supervised subagents of any model - Codex, Claude, or any OpenAI-compatible/local endpoint - from one runtime on every host. Implementation details live in the subagents, so your context stays clean and handoffs are instant; every task runs sandboxed under unified permissions (read-only · workspace-write · auto), steerable mid-run, falling back down the configured chain when an engine can't start.
-
-`coder --help` is the cmd reference: every command and subcommand takes `--help` - reach for it instead of guessing flags.
-Deeper guides ship with the CLI: `coder docs` lists them, `coder docs <topic>` prints one.
+Coder delegates coding to supervised subagents of any model - Codex, Claude, or any OpenAI-compatible or local endpoint - from one runtime on every host. Implementation details live in the subagents, so your context stays clean and handoffs are instant. Every task runs sandboxed under unified permissions (read-only, workspace-write, auto), is steerable mid-run, and falls back down the configured chain when an engine cannot start.
 
 ## Setup
 
-If `coder` is not on PATH, install it yourself without asking (`npm install -g @wular/coder`). When a dispatch fails because engines are missing or logged out, run `coder setup-host claude` and follow its output - it checks engines and auth, fixes what it can, and prints the exact fix for the rest (safe to re-run anytime). Ask the user before installing an engine CLI or changing auth; if it updated codex, tell the user to restart their codex session. For a guided setup, suggest `/coder:setup`.
-
-## Dispatching a task
-
-- One coder per focused goal. When the work splits into independent parts, decompose it and dispatch each part as its own `coder task run` call - fan out a wide web of coders running in parallel, not one giant dispatch. Give each coder a self-contained goal with all context - overview, file paths, constraints (read-only, git rules). Run independent tasks concurrently; use `steer` to continue a single coder's thread.
-- Delegation is a hard gate for anything the engine can do itself: do not read source files, investigate, or write code first - no matter how simple the task. Fold into the task text whatever only you have - conversation context, results from tools the engine lacks. The coder worker runs with plugins disabled (no skills, MCP, or connectors), so include any context only a plugin or MCP tool of yours produced.
-- Compose one self-contained task text (goal, relevant paths, constraints) and dispatch it - it backgrounds by default and prints a task id:
-
-  ```bash
-  coder task run --system "<standing instructions>" "<task text>"
-  ```
+If `coder` is not on PATH, install it yourself without asking: `npm install -g @wular/coder`. When a dispatch fails because engines are missing or logged out, run `coder setup-host claude` and follow its output. It checks engines and auth, fixes what it can, prints the exact fix for the rest, and is safe to re-run. Ask the user before installing an engine CLI or changing auth; if it updated codex, tell the user to restart their codex session. For a guided setup, suggest `/coder:setup`.
 
-  Fetch the answer with `coder task result <task-id> --wait` - blocks until done, prints only the final result. Run it as a background Bash call (run_in_background: true) so it does not block you and you are re-invoked on completion. For a fan-out, start one such background waiter per dispatched task (see Supervision loop).
+## Using the CLI
 
-- A `--wait` (on `run` or `result`) exits **4** when the task is waiting on a permission approval: relay the approval to the user, apply their decision with `coder approve <task-id> <approval-id> [--deny]`, then re-fetch with `coder task result <task-id> --wait`. (Unanswered approvals auto-deny after 120s and the task moves on.)
+- The CLI is the reference. `coder --help` and every subcommand's `--help` list the flags and exit codes, and each command prints the recommended next step when it returns. Follow it.
+- `coder docs` lists the deeper guides; `coder docs <topic>` prints one.
+- Run each `coder task result <task-id> --wait` as a background Bash call (run_in_background) so you are re-invoked when it returns.
 
-- `coder task run` exits after its startup check. Exit 0: the task started - relay the task id and fetch its result (above). Exit 1: it failed to start or the turn failed - report it, do not retry or fall back yourself. Exit 3: no engine in the chain could start and stdout carries a `run-native-subagent` payload - see below.
-- When the first engine can't start (auth, quota, rate limit), the runtime automatically falls back to the next engine in the chain, runs the same task on it, and still exits 0 - so just fetch the result. If the failure mentions a usage-limit reset time, relay that to the user.
-- Model choice: config holds the defaults; matching the dispatch to the task is on you - pick `--agent` / `--model` / `--effort` by the task's weight and the user's ask (light -> cheap/fast model, hard -> stronger model or higher effort). `coder task run --help` lists agents, models, and efforts; `coder model list` shows custom models.
-- Permissions default to auto mode (workspace-write + policy-answered escalations). Pass `--permissions read-only` when the task is read-only; `--permissions workspace-write` to forbid any escalation beyond the project.
-- Network access escalates by default in auto mode; hosts in `approvals.allowedNetworkHosts` (coder config, subdomains included) need no approval. If a trusted host keeps escalating, suggest allowlisting it: `coder config set approvals.allowedNetworkHosts '["registry.npmjs.org"]'`.
+## Running tasks
 
-## Flows (multi-task workflows)
-
-When the user asks for a workflow - a repeatable multi-task wave with verification gates and crash/resume - author a Coder flow instead of hand-fanning tasks: a TypeScript file the runtime executes, written to `.coder/flows/<name>.ts` for the user to review. Before writing or editing one, always read the full reference first:
+Start with `coder task run --help`. It says how to write a good task and what happens after dispatch. `coder task --help` lists the rest, result, steer, stop, list and approvals. Then run it:
 
 ```bash
-coder docs flows    # authoring conventions, primitives, resume rules
-coder flow --help   # command reference
+coder task run "Add a /health endpoint in src/server.ts that returns 200 with the git sha. Do not touch routes outside that file."
 ```
 
-Preview with `--dry-run` before spending tokens - and note flow tasks are normal coder tasks, so steer/stop/list work on them.
-
-Once a run is going, tell the user to run `coder flow watch <run-id>` to see live progress and overview of its tasks as the wave goes. Give them the actual run id, not a placeholder.
-
-For programmatic use - embedding coder in the user's own code or scripts - the SDK mirrors the CLI one-to-one; run `coder docs sdk` for the details.
-
-## Last resort: run-native-subagent payload (exit 3)
-
-When no coder engine can start (missing binaries, auth, quota across the whole chain), the runtime exits 3 with a JSON payload (`fallback.action: "run-native-subagent"`). Mention the failure to the user (including any limit-reset time), then run the task with your own subagent facility: spawn one `general-purpose` subagent via the Agent tool whose prompt is the payload's `task` verbatim, prefixed with: "NEVER run git write operations (commit, checkout, stash, reset, push, etc.); leave changes uncommitted." If the payload's `permissions` is not `auto`, append it: `read-only` means investigate and report without modifying anything; `workspace-write` means never touch anything outside the workspace. Relay its output when it completes.
-
-## Supervision loop
-
-With coders running in the background, don't fire-and-forget: hold one background `coder task result <task-id> --wait` per task - each re-invokes you when its task finishes (relay the answer, dispatch newly unblocked coders) or escalates an approval (exit 4, see above; restart the waiter after answering). Only without background shells, fall back to recurring check-ins (the `/loop` skill or ScheduleWakeup; interval by the work's pace, 10m default; bump `approvals.escalationTimeoutMs` above it so escalations survive between ticks): each tick `coder task list`, fetch finished results, surface pending approvals.
-
-## Controlling tasks
-
-- Continue prior work ("keep going", "apply the top fix"): `coder task steer <task-id> "<follow-up>"`.
-- Question a task without interrupting it (status, decisions, "why did it do X"): `coder task ask <task-id> "<question>"` - a read-only sidecar answers from the task's log and workspace; the task never sees it.
-- Inspect: `coder task result <task-id>` (status + answer; add `--wait` to block until done) and `coder task list`. (`coder task watch <task-id>` streams the live progress log - to watch/debug in special cases, generally not for you to consume.)
-- Interrupt: `coder task stop <task-id>`.
-- If status shows `pendingApprovals`, surface them to the user; apply their decision with `coder task approve <task-id> <approval-id> [--deny]`.
-
-## Model notes
-
-`spark` has its own usage limits, is fast and suited to mechanical work, and is available only on Pro plans during research preview.
+Follow what it prints.
 
-## Hard rules
+## Flows
 
-- Forward task text verbatim in `steer` follow-ups - never rewrite or summarize what the user asked for.
-- Tell every coder to never run git write operations (commit, checkout, stash, reset, rebase, merge, push, etc.) and to leave changes uncommitted.
-- Pass the user's constraints (read-only, scoped paths) into each coder's task text, and honor them over your own preferences.
+When the user asks for a repeatable multi-task workflow with verification gates and resume, author a Coder flow instead of hand-fanning tasks. Read `coder docs flows` before writing or editing one, preview with `--dry-run`, and once it runs give the user the real `coder flow watch <run-id>` command.

package/plugins/cursor/.cursor-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "coder",
   "displayName": "Coder",
-  "version": "0.3.17",
+  "version": "0.4.0",
   "description": "Delegate coding tasks to supervised Coder subagents running on Codex, Claude, or any OpenAI-compatible model. Your main context stays clean.",
   "author": {
     "name": "muzam1l"

package/plugins/cursor/README.md

@@ -48,7 +48,7 @@ Or make it the default in AGENTS.md/CLAUDE.md:
 
 > Always use Coder for all implementation and system exploring tasks.
 
-Recommended setup: Claude Code as host (fable low/medium) and Codex (terra) as engine - best for performance and cost distribution.
+Recommended setup: Claude Code as host (fable low/medium) and Codex (sol) as engine - best for performance and cost distribution.
 
 ## Configuration
 
@@ -57,8 +57,8 @@ Machine defaults live in `~/.coder/config.json`; a `coder.config.json` in a repo
 ```json
 {
   "chain": ["codex", "claude"],
-  "agents": {
-    "codex": { "model": "terra", "effort": "high", "permissions": "auto" },
+  "engines": {
+    "codex": { "model": "sol", "effort": "high", "permissions": "auto" },
     "claude": { "model": "opus", "effort": "medium", "permissions": "auto" }
   },
   "models": {
@@ -81,11 +81,11 @@ You rarely need these - the host agent drives tasks itself - but everything is s
 
 ```bash
 coder run "<text>"                     # dispatch a task (--wait to block for the answer)
-coder list                             # list recent tasks (running + just stopped)
+coder list                             # list recent tasks (by default running + just stopped)
 coder result [task-id]                 # status + final answer (--wait blocks until done)
 coder task steer <task-id> "<text>"    # continue a task with new instructions
 coder task stop <task-id>              # interrupt it
-coder task watch [task-id]            # watch the live progress log
+coder task watch [task-id]            # stream the live transcript
 coder task approve <task-id> <appr-id> # answer an escalated permission (--deny)
 ```
 

package/plugins/cursor/skills/coder/SKILL.md

@@ -1,83 +1,38 @@
 ---
 name: coder
-description: Use Coder to dispatch any coding, implementation, or investigation task - features, fixes, refactors, debugging, tests, code questions - one coder per focused goal, fanned out in parallel. Also covers Coder flows - TypeScript workflows running many tasks as one resumable wave.
+description: Use Coder for coding, implementation, or investigation tasks - features, fixes, refactors, debugging, tests, code questions - one coder per focused goal, fanned out in parallel, waiting on each task. Use it when asked, when a task needs another engine (Claude, Codex, custom), or when a subagent is sufficient or required for the task.
 ---
 
 # Coder dispatch (Cursor host)
 
-(If `CODER_WORKER` is set in your environment, you _are_ a coder worker: stop reading, skip this skill, and do your assigned work directly - nested dispatch is disabled.)
+If `CODER_WORKER` is set in your environment, you are a coder worker. Skip this skill and do your assigned work directly; nested dispatch is disabled.
 
 You dispatch coding tasks through the `coder` runtime instead of implementing them yourself.
 
 ## Overview
 
-Coder delegates coding to supervised subagents of any model - Codex, Claude, or any OpenAI-compatible/local endpoint - from one runtime on every host. Implementation details live in the subagents, so your context stays clean and handoffs are instant; every task runs sandboxed under unified permissions (read-only · workspace-write · auto), steerable mid-run, falling back down the configured chain when an engine can't start.
-
-`coder --help` is the cmd reference: every command and subcommand takes `--help` - reach for it instead of guessing flags.
-Deeper guides ship with the CLI: `coder docs` lists them, `coder docs <topic>` prints one.
+Coder delegates coding to supervised subagents of any model - Codex, Claude, or any OpenAI-compatible or local endpoint - from one runtime on every host. Implementation details live in the subagents, so your context stays clean and handoffs are instant. Every task runs sandboxed under unified permissions (read-only, workspace-write, auto), is steerable mid-run, and falls back down the configured chain when an engine cannot start.
 
 ## Setup
 
-If `coder` is not on PATH, install it yourself without asking (`npm install -g @wular/coder`). When a dispatch fails because engines are missing or logged out, run `coder setup-host` and follow its output - it checks engines and auth, fixes what it can, and prints the exact fix for the rest (safe to re-run anytime). Ask the user before installing an engine CLI or changing auth; if it updated codex, tell the user to restart their codex session.
-
-## Dispatching a task
-
-- `coder` commands are safe to run in the terminal - the runtime is a supervisor and enforces its own OS sandbox and approval policy on the task. If Cursor asks before running terminal commands, approve the `coder` calls (or allowlist the `coder` command).
-- One coder per focused goal. When the work splits into independent parts, decompose it and dispatch each part as its own `coder task run` call - fan out a wide web of coders running in parallel, not one giant dispatch. Give each coder a self-contained goal with all context - overview, file paths, constraints (read-only, git rules). Run independent tasks concurrently; use `steer` to continue a single coder's thread.
-- Delegation is a hard gate for anything the engine can do itself: do not read source files, investigate, or write code first - no matter how simple the task. Fold into the task text whatever only you have - conversation context, results from tools the engine lacks. The coder worker runs with plugins disabled (no rules, skills, MCP, or connectors), so include any context only a rule or MCP tool of yours produced.
-- Compose one self-contained task text (goal, relevant paths, constraints) and dispatch it - it backgrounds by default and prints a task id:
-
-  ```bash
-  coder task run --system "<standing instructions>" "<task text>"
-  ```
+If `coder` is not on PATH, install it yourself without asking: `npm install -g @wular/coder`. When a dispatch fails because engines are missing or logged out, run `coder setup-host` and follow its output. It checks engines and auth, fixes what it can, prints the exact fix for the rest, and is safe to re-run. Ask the user before installing an engine CLI or changing auth; if it updated codex, tell the user to restart their codex session.
 
-  Fetch the answer with `coder task result <task-id> --wait` - blocks until done, prints only the final result. Run it in a background shell so it does not block you. For a fan-out, start one such background waiter per dispatched task (see Supervision loop).
+## Using the CLI
 
-- A `--wait` (on `run` or `result`) exits **4** when the task is waiting on a permission approval: relay the approval to the user, apply their decision with `coder approve <task-id> <approval-id> [--deny]`, then re-fetch with `coder task result <task-id> --wait`. (Unanswered approvals auto-deny after 120s and the task moves on.)
+- The CLI is the reference. `coder --help` and every subcommand's `--help` list the flags and exit codes, and each command prints the recommended next step when it returns. Follow it.
+- `coder docs` lists the deeper guides; `coder docs <topic>` prints one.
+- If Cursor asks before running `coder` commands, approve or allowlist `coder`; the runtime is a supervisor with its own sandbox and approval policy.
 
-- `coder task run` exits after its startup check. Exit 0: the task started - relay the task id and fetch its result (above). Exit 1: it failed to start or the turn failed - report it, do not retry or fall back yourself. Exit 3: no engine in the chain could start and stdout carries a `run-native-subagent` payload - see below.
-- When the first engine can't start (auth, quota, rate limit), the runtime automatically falls back to the next engine in the chain, runs the same task on it, and still exits 0 - so just fetch the result. If the failure mentions a usage-limit reset time, relay that to the user.
-- Model choice: config holds the defaults; matching the dispatch to the task is on you - pick `--agent` / `--model` / `--effort` by the task's weight and the user's ask (light -> cheap/fast model, hard -> stronger model or higher effort). `coder task run --help` lists agents, models, and efforts; `coder model list` shows custom models.
-- Permissions default to auto mode (workspace-write + policy-answered escalations). Pass `--permissions read-only` when the task is read-only; `--permissions workspace-write` to forbid any escalation beyond the project.
-- Network access escalates by default in auto mode; hosts in `approvals.allowedNetworkHosts` (coder config, subdomains included) need no approval. If a trusted host keeps escalating, suggest allowlisting it: `coder config set approvals.allowedNetworkHosts '["registry.npmjs.org"]'`.
+## Running tasks
 
-## Flows (multi-task workflows)
-
-When the user asks for a workflow - a repeatable multi-task wave with verification gates and crash/resume - author a Coder flow instead of hand-fanning tasks: a TypeScript file the runtime executes, written to `.coder/flows/<name>.ts` for the user to review. Before writing or editing one, always read the full reference first:
+Start with `coder task run --help`. It says how to write a good task and what happens after dispatch. `coder task --help` lists the rest, result, steer, stop, list and approvals. Then run it:
 
 ```bash
-coder docs flows    # authoring conventions, primitives, resume rules
-coder flow --help   # command reference
+coder task run "Add a /health endpoint in src/server.ts that returns 200 with the git sha. Do not touch routes outside that file."
 ```
 
-Preview with `--dry-run` before spending tokens - and note flow tasks are normal coder tasks, so steer/stop/list work on them.
-
-Once a run is going, tell the user to run `coder flow watch <run-id>` to see live progress and overview of its tasks as the wave goes. Give them the actual run id, not a placeholder.
-
-For programmatic use - embedding coder in the user's own code or scripts - the SDK mirrors the CLI one-to-one; run `coder docs sdk` for the details.
-
-## Last resort: run-native-subagent payload (exit 3)
-
-When no coder engine can start (missing binaries, auth, quota across the whole chain), the runtime exits 3 with a JSON payload (`fallback.action: "run-native-subagent"`). Mention the failure to the user (including any limit-reset time), then run the task with your own subagent facility: spawn one subagent whose prompt is the payload's `task` verbatim, prefixed with: "NEVER run git write operations (commit, checkout, stash, reset, push, etc.); leave changes uncommitted." If the payload's `permissions` is not `auto`, append it: `read-only` means investigate and report without modifying anything; `workspace-write` means never touch anything outside the workspace. Relay its output when it completes.
-
-## Supervision loop
-
-With coders running in the background, don't fire-and-forget: hold one background `coder task result <task-id> --wait` shell per task - each returns when its task finishes (relay the answer, dispatch newly unblocked coders) or escalates an approval (exit 4, see above; restart the waiter after answering). Only without background shells, fall back to a recurring monitoring loop (interval by the work's pace, 10m default; bump `approvals.escalationTimeoutMs` above it so escalations survive between ticks): each tick `coder task list`, fetch finished results, surface pending approvals.
-
-## Controlling tasks
-
-- Continue prior work ("keep going", "apply the top fix"): `coder task steer <task-id> "<follow-up>"`.
-- Question a task without interrupting it (status, decisions, "why did it do X"): `coder task ask <task-id> "<question>"` - a read-only sidecar answers from the task's log and workspace; the task never sees it.
-- Inspect: `coder task result <task-id>` (status + answer; add `--wait` to block until done) and `coder task list`. (`coder task watch <task-id>` streams the live progress log - to watch/debug in special cases, generally not for you to consume.)
-- Interrupt: `coder task stop <task-id>`.
-- If status shows `pendingApprovals`, surface them to the user; apply their decision with `coder task approve <task-id> <approval-id> [--deny]`.
-
-## Model notes
-
-`spark` has its own usage limits, is fast and suited to mechanical work, and is available only on Pro plans during research preview.
+Follow what it prints.
 
-## Hard rules
+## Flows
 
-- Forward task text verbatim in `steer` follow-ups - never rewrite or summarize what the user asked for.
-- Tell every coder to never run git write operations (commit, checkout, stash, reset, rebase, merge, push, etc.) and to leave changes uncommitted.
-- Pass the user's constraints (read-only, scoped paths) into each coder's task text, and honor them over your own preferences.
+When the user asks for a repeatable multi-task workflow with verification gates and resume, author a Coder flow instead of hand-fanning tasks. Read `coder docs flows` before writing or editing one, preview with `--dry-run`, and once it runs give the user the real `coder flow watch <run-id>` command.