dodo-mcp 1.0.0

package/docs/TUNNEL.md

@@ -0,0 +1,86 @@
+# DODO MCP — Tunnel Guide
+
+DODO เปิด MCP และ OAuth บน local loopback ผู้ใช้เป็นผู้สร้าง Cloudflare remotely-managed Tunnel, public hostname และ DNS เอง DODO supervise เฉพาะ process `cloudflared` ที่เริ่มในรอบปัจจุบันและไม่ติดตั้งเป็น system service
+
+## Local endpoints
+
+- MCP + OAuth: `http://127.0.0.1:21730`
+- MCP endpoint: `http://127.0.0.1:21730/mcp`
+- Local Config: `http://127.0.0.1:21731`
+- managed readiness/metrics: `http://127.0.0.1:21732` โดยค่าเริ่มต้น
+
+Tunnel ต้อง route health, discovery, OAuth และ MCP ทุก path ไปยัง listener `21730` เดียวกัน ห้าม route Local Config `21731`, metrics `21732`, private IPC หรือ debug endpoint ออก public
+
+## Public origin
+
+```bash
+dodo init --public-url https://mcp.example.com
+dodo start --root /path/to/project
+```
+
+## เปิดพร้อม DODO ด้วย token ชั่วคราว
+
+```bash
+dodo setup --check --components cloudflared
+dodo init --public-url https://mcp.example.com
+dodo start --root /path/to/project
+# Cloudflare Tunnel token (temporary; Enter = local only):
+```
+
+`dodo setup --yes` ใช้ component `all` เป็นค่าเริ่มต้นและรวม `cloudflared` บน macOS
+หรือเลือกจากเมนู `dodo --cli` ข้อ “ติดตั้ง/ตรวจ dependencies ทั้งหมด” ได้
+
+กรอก Tunnel token ที่ Cloudflare ออกให้สำหรับ remotely-managed Tunnel Token จะอยู่
+เฉพาะใน DODO process และ environment ของ child `cloudflared` ระหว่างรอบ เมื่อ DODO
+หยุด child จะหยุดตาม กด Enter โดยไม่กรอกหรือใช้คำสั่งต่อไปนี้เพื่อเปิด local MCP เท่านั้น:
+
+```bash
+dodo start --no-tunnel
+```
+
+หน้า Local Config มีช่อง **Temporary Tunnel token** สำหรับเริ่ม tunnel ใน process ที่
+เปิดอยู่ได้ทันที และมีปุ่มหยุดเฉพาะ child ที่ process นี้เป็นเจ้าของ ช่องถูกล้างหลังส่ง
+Backend ตอบ `tokenStored:false` และไม่เขียนค่าลง config หรือ credential store
+
+คำสั่งตรวจสถานะที่ไม่มี secret:
+
+```bash
+dodo tunnel status
+dodo tunnel doctor
+dodo tunnel logs --lines 100
+dodo tunnel stop
+```
+
+`status` ใช้ authenticated owner IPC และไม่อ่าน credential ส่วน `doctor` เป็นคำสั่งตรวจแบบ explicit: ตรวจ executable, credential availability, local `/healthz`, managed `/ready` และ public `/healthz` แยกกัน Public health ที่ผ่านไม่ได้แปลว่า AI client เชื่อมต่ออยู่
+
+## ขอบเขตของ token
+
+DODO ไม่รับ token เป็น CLI argument และไม่ใส่ token ใน `cloudflared` argv เส้นทาง
+มาตรฐานไม่ใช้ macOS Keychain, Windows Credential Manager, Linux Secret Service,
+token file หรือ shell environment Token จาก terminal และ Local Config ถูกส่งผ่าน
+environment ของ child ที่สร้างเองเท่านั้น Tunnel diagnostics ถูกจำกัดขนาดและ redact
+ก่อนเขียนลง private state MCP jobs จะไม่ได้รับ `TUNNEL_TOKEN` หรือ
+`TUNNEL_TOKEN_FILE` แม้ owner จะใส่ชื่อไว้ใน environment allowlist
+
+คำสั่ง `dodo tunnel configure/start` และ credential reference รุ่นเดิมยังคงอยู่เพื่อ
+advanced/headless compatibility แต่ไม่ถูกเรียกโดย `dodo start`, `dodo --cli` หรือ
+Local Config และต้องเกิดจากคำสั่ง owner โดยตรง
+
+runtime ใช้ bounded restart หลัง `cloudflared` จบ retry ของตัวเอง และ `stop` ส่งสัญญาณเฉพาะ live child handle ที่ supervisor เป็นผู้สร้าง ไม่มีการ kill saved PID หรือ process ชื่อเหมือนกัน
+
+## Client setup
+
+1. ใช้ `https://mcp.example.com/mcp` ใน MCP client
+2. เลือก OAuth
+3. คัดลอก exact callback จาก client
+4. ลงทะเบียนด้วย `dodo auth add-client --redirect-uri ...`
+5. ทำ browser authorization และ approve interaction จาก terminal
+6. scan tools และตรวจ surface ที่ client รายงาน
+
+## หลายโปรเจกต์
+
+หนึ่ง DODO process มี active workspace เดียว ถ้าต้องการทำงานพร้อมกันหลายโปรเจกต์ ให้เปิดหลาย DODO processes ด้วย port, public origin และ config directory ที่แยกกัน แต่ละ managed tunnel ต้องใช้ metrics port ที่ไม่ซ้ำ ระบบจะไม่ให้ process หนึ่ง takeover root ที่อีก process กำลัง serve
+
+## Security
+
+ห้ามปิด OAuth, ใช้ Tunnel token แทน MCP OAuth, ส่ง token ใน URL หรือเปิด CORS กว้าง Tunnel provider ไม่ได้แทน owner consent ของ DODO และ DODO ไม่เรียก Cloudflare API, ไม่จัดการ DNS, ไม่สร้าง/ลบ Tunnel และไม่เปิด firewall

package/docs/WEB_CLIENTS.md

@@ -0,0 +1,43 @@
+# DODO MCP — Web Clients
+
+## Connection checklist
+
+1. รัน DODO และตั้ง public HTTPS origin
+2. ตรวจว่า URL ลงท้ายด้วย `/mcp`
+3. เพิ่ม static OAuth client ด้วย exact callback URL
+4. เลือก OAuth ใน web client
+5. ทำ authorization ใน browser
+6. approve interaction ผ่าน `dodo auth pending` และ `dodo auth approve ID`
+7. scan tools
+8. เรียก `project_overview` และตรวจ `toolSurface`
+
+## Compact behavior
+
+HTTP default เป็น Compact surface 19 tools ประกอบด้วย overview, `dodo_discover` และ gateways client จะค้น operation ที่ต้องการจาก discover แล้วเรียก gateway พร้อม top-level workspace context
+
+Compact ไม่ลด security และไม่ได้รวมสิทธิ์หลาย operation เป็น approval เดียว target operation ยังคงมี scope, ACL, trust, approval, hash และ path policy ของตัวเอง
+
+## Client cache
+
+client บางตัว cache tool catalog หลังสร้าง connection หาก schema หรือ surface เปลี่ยน ให้ refresh ตาม client หรือ recreate connection เมื่อ refresh ไม่ได้ล้าง catalog เดิม
+
+## Manual evidence
+
+บันทึกจำนวน tools ที่ client แสดงจริง, response ของ overview, write/edit read-back และ error cases แยกจาก automated test อย่ารายงานว่า web client ผ่านจาก server log เพียงอย่างเดียว
+
+## Delegate งานด้วย AI profile ของเจ้าของ
+
+ค่าเริ่มต้นซ่อน Sub-agent operations จาก MCP เพื่อให้ catalog งานทั่วไปกระชับขึ้น ก่อน
+delegate จาก ChatGPT/remote MCP ให้เจ้าของเปิด **Settings → Sub-agent tools ใน MCP**
+แล้ว restart DODO และ rescan/recreate connection หน้าเว็บ Chat & Tasks ใช้ได้แม้สวิตช์ปิด
+
+เมื่อเปิดแล้ว ChatGPT/remote MCP ใช้ `project_overview(targetProjectId)`
+เพื่อรับ context และ `ai.profiles` เฉพาะที่อนุญาต แล้ว `dodo_discover` หา
+`subagent_spawn` ผ่าน `dodo_assist_change` ตรวจผลด้วย `subagent_result` ผ่าน
+`dodo_assist_read` รูปแบบ top-level target/context เหมือน read/write tools
+ไม่ใส่ key ในแชตหรือ tool args; เจ้าของตั้งผ่าน private Local Config เท่านั้น
+
+การมี MCP OAuth scopes ไม่ได้อนุญาต provider egress โดยอัตโนมัติ ต้องมี target ACL,
+profile/client allowlist และ trust/approval เดิม งานหลาย projects สร้างหนึ่ง run ต่อ
+project; ผลลัพธ์คืน run ID/receipts ไม่มี internal reasoning และ retry ด้วย key เดิม
+ไม่สร้างงานซ้ำ โปรด rescan/recreate connector หากยังไม่เห็น schema ใหม่

package/docs/WINDOWS.md

@@ -0,0 +1,79 @@
+# DODO Windows Candidate — Deferred
+
+DODO MCP 1.0.0 ยังไม่ประกาศ native Windows support โค้ดและ tests สำหรับ Windows
+บางส่วนมีอยู่เป็น candidate สำหรับ phase สุดท้าย แต่ยังไม่มีหลักฐานจาก Windows 11 จริง
+และ Linux Docker ไม่สามารถใช้แทนหลักฐาน Windows ได้
+
+## ตรวจเครื่อง
+
+```powershell
+dodo setup --check
+dodo doctor
+```
+
+คำสั่งตรวจจะรายงานสถานะ Git, ripgrep, LSP, media, speech, browser, desktop และ command sandbox แยกกัน ไม่เปิด permission หรือดาวน์โหลด model เอง
+
+## การทำงานหลัก
+
+- MCP HTTP ใช้ OAuth และ bind local loopback ก่อน owner จะนำไปวางหลัง HTTPS tunnel
+- STDIO ใช้ full tool surface เป็นค่าเริ่มต้น
+- Local Config ใช้ owner authentication และ named-pipe/loopback transport ตาม platform
+- workspace path ต้องเป็น absolute path และผ่าน canonicalization, ACL และ secret/path guards
+- jobs ใช้ Windows process tree และ environment allowlist
+- file changes ใช้ expected hash, journal, atomic replace และ rollback
+
+## Optional backends
+
+Desktop, speech, browser และ command sandbox ต้องผ่าน probe และ owner permission หาก backend ไม่พร้อมระบบตอบ `NOT_SUPPORTED` ตามจริง
+
+## งานที่ต้องผ่านก่อนประกาศรองรับ
+
+การแก้ candidate สำหรับ native CI:
+
+- directory identity ใช้ bigint เมื่ออ่าน NTFS; ค่าที่เกิน JavaScript safe integer
+  เก็บเป็น `u64:<decimal>` ใน JSON/SQLite เพื่อไม่ให้ file ID คนละค่าถูกปัดรวมกัน
+  ค่า integer เดิมยังอ่านได้ และการตรวจ replaced root/ACL/trust ยังคงมีผล
+- resource buffer เปิด staging file ด้วย writable handle ก่อน fsync ตามข้อกำหนด Windows
+- LSP เทียบ URI ที่ normalize drive letter และ percent encoding แล้ว โดยไม่เปลี่ยน case ของชื่อไฟล์
+- private fixture ตรวจ Windows ACL; fault injection แบบ filesystem error ตรวจ rollback
+  ได้ทุก platform เพิ่มจาก POSIX chmod test และจำกัด Windows file workers ที่สองตัว
+- `dodo kill` ตรวจและหยุด authenticated IPC endpoints ทีละรายการบน Windows
+  เพื่อไม่ให้ synchronous PowerShell ACL probes ขวางการรับ IPC response ของอีก
+  endpoint โดยยังตรวจ identity/epoch และรอ shutdown จริง ไม่ใช้ PID จาก state เพื่อส่ง signal
+- หาก endpoint ถูกปิดระหว่างตรวจ IPC identity จะตรวจยืนยันว่า descriptor และ
+  locator หายไปจริง ก่อนรายงานว่าไม่มี endpoint; ข้อมูลเสียหรือ ACL ที่ไม่ปลอดภัย
+  ของ endpoint ที่ยังอยู่ยังเป็น error ตามเดิม
+
+ระบบจะประกาศ native support ได้เมื่อผ่าน named-pipe identity, NTFS
+reparse/ADS/8.3 guards, ACL enforcement, PATHEXT resolution, shell strategy,
+process cancellation, read-only/antivirus file behavior, Windows argv limits,
+Chromium environment, LSP, full automated suite และ packaging บน Windows จริง
+
+## Manual acceptance
+
+ต้องทดสอบบน Windows 11 จริง: OAuth/HTTP, STDIO, workspace isolation, ACL, file
+conflict, rollback, jobs, setup และ package installation ผลปัจจุบันคือ
+`MANUAL_NOT_RUN` Dedicated `windows-ci 02` self-hosted runner ใช้เก็บ automated native
+candidate evidence บน Node 22/24 แต่ไม่เปลี่ยน manual status เอง Workflow เลือก
+label `windows-ci 02` โดยเฉพาะ และเลิกใช้ runner 01 แล้ว
+
+Workflow เตรียม Portable Git for Windows ใน temp ของ job หากไม่มี Git ใน PATH
+โดยตรึง official release และตรวจ SHA-256 ก่อนแตกไฟล์ เพื่อให้ checkout ได้ `.git`
+และตรวจ source revision จริง PowerShell ของ job ใช้ `RemoteSigned` แบบ process scope
+สำหรับสคริปต์ที่ runner สร้าง ไม่แก้ execution policy ถาวรของเครื่อง และยังบังคับ
+enabled Administrator token สำหรับชุดตรวจ ACL
+
+## เริ่ม self-hosted runner บนเครื่องที่พบปัญหา locale
+
+หาก runner ล้มก่อน step แรกด้วย `PowerShellPreAmpersandEscape` ให้หยุด runner แล้ว
+รันใน PowerShell ที่โฟลเดอร์ runner เดิม:
+
+```powershell
+$env:DOTNET_SYSTEM_GLOBALIZATION_INVARIANT = "1"
+$env:DOTNET_SYSTEM_GLOBALIZATION_PREDEFINEDCULTURESONLY = "false"
+.\run.cmd
+```
+
+ค่ามีผลเฉพาะหน้าต่างนี้; เมื่อเปิดใหม่ต้องตั้งอีกครั้ง Workflow คืน globalization
+ตามปกติให้ขั้นทดสอบ เพื่อไม่ใช้ workaround ของ runner มาบังปัญหา locale ใน DODO
+อาการและ workaround อ้างอิง [actions/runner#4686](https://github.com/actions/runner/issues/4686)

package/docs/adr/001-one-process-one-workspace.md

@@ -0,0 +1,22 @@
+# ADR-001 — One process = one CWD workspace = one endpoint profile
+
+**Status:** superseded in part by ADR-019 and ADR-044. The one-active-workspace
+invariant remains; CWD startup and restart-only switching do not.
+
+**Decision.** A DODO process serves exactly one workspace root — the realpath of
+`process.cwd()` captured at the CLI entrypoint — and one public issuer/profile.
+There is no remote tool to change root or lower policy. `workspaceId` is
+server-minted (derived from a per-install secret + canonical root) and every
+tool except `project_overview` must present a matching `workspaceId` +
+`workspaceEpoch`.
+
+**Trade-off.** Switching projects means restarting and re-consenting. In return,
+scope confusion is impossible and a stolen token cannot be pointed at another
+folder on the same host.
+
+**Evidence / validation.** Root-switch grant isolation and workspace-context
+enforcement are covered by `security/auth.test.ts` (AUTH-07/AUTH-18) and
+`integration/m0` (WORKSPACE_MISMATCH / STALE_WORKSPACE). CWD-not-install-dir is
+covered by `integration/cli.test.ts` (CLI-03). See
+[src/workspace/root.ts](../../src/workspace/root.ts),
+[src/workspace/identity.ts](../../src/workspace/identity.ts).

package/docs/adr/002-external-tunnel.md

@@ -0,0 +1,19 @@
+# ADR-002 — User-managed external named tunnel
+
+**Status:** superseded in part by ADR-031; external mode remains supported
+
+**Decision.** DODO binds `127.0.0.1:21730` and nothing else. The user runs their
+own Cloudflare named tunnel (or equivalent) and owns DNS/firewall. This remains
+the `external` mode. ADR-031 adds an explicit local-owner option to supervise
+only `cloudflared`; DODO still never creates/deletes tunnels, manages DNS or
+opens ports.
+
+**Trade-off.** The user does more setup and holds the tunnel credentials. In
+return DODO holds no cloud secrets and has no relay/SaaS to trust.
+
+**Evidence / validation.** A named tunnel + stable hostname is the recommended
+baseline because Quick Tunnels do not support SSE and lack hostname persistence
+for OAuth callbacks (spec §2.4/§17, source [S11]). A local reverse-proxy fixture
+([examples/reverse-proxy-fixture.mjs](../../examples/reverse-proxy-fixture.mjs))
+reproduces the full-path forwarding for automated OAuth testing; real-tunnel
+end-to-end is a manual gate (MAN-02). See [docs/TUNNEL.md](../TUNNEL.md).

package/docs/adr/003-sdk-v2-legacy-stateless.md

@@ -0,0 +1,20 @@
+# ADR-003 — Official MCP SDK v2 + legacy stateless fallback
+
+**Status:** accepted (implemented)
+
+**Decision.** Use the official MCP TypeScript SDK **v2** split packages
+(`@modelcontextprotocol/{server,express,node}` `2.0.0`, verified on the npm
+registry) and serve with `createMcpHandler(factory, { legacy: 'stateless' })`,
+which handles the modern 2026-07-28 per-request path and a stateless fallback
+for 2025-era clients on one endpoint. We do not hand-roll JSON-RPC, session
+handling, or era classification, and do not mix v1 imports.
+
+**Trade-off.** No support for the old sessionful GET-stream transport. The exact
+protocol revision a given ChatGPT build negotiates was not captured; both
+generations are tested locally instead.
+
+**Evidence / validation.** `integration/m0-transport-oauth.test.ts` connects a
+real SDK v2 `Client` (modern) AND drives a raw 2025 `initialize`+`tools/call`
+(legacy stateless), both listing 33 tools; `GET`/`DELETE` return `405`. Versions
+recorded in [COMPATIBILITY.md](../COMPATIBILITY.md). See
+[src/server/appServer.ts](../../src/server/appServer.ts).

package/docs/adr/004-embedded-oauth-provider.md

@@ -0,0 +1,19 @@
+# ADR-004 — Embedded `oidc-provider` authorization server
+
+**Status:** accepted (implemented)
+
+**Decision.** Co-host a maintained OAuth 2.1 / OIDC authorization server
+(`oidc-provider` `9.12.2`) with the MCP resource server on one public origin. We
+do not implement OAuth crypto, PKCE, token formats, or refresh rotation
+ourselves. Issuer = configured public origin; resource = issuer + `/mcp`. Tokens
+are ES256 JWTs bound to the workspace.
+
+**Trade-off.** Local owner-consent UX must be built, and the provider is a large
+dependency. In return there is no central SaaS and the protocol details are
+handled by an audited library.
+
+**Evidence / validation.** Full authorization-code + PKCE(S256) flow issues a
+usable, workspace-bound token in `integration/m0` and `security/auth.test.ts`
+(revocation, audience, PKCE failure, refresh). See
+[src/auth/provider.ts](../../src/auth/provider.ts),
+[src/auth/verifier.ts](../../src/auth/verifier.ts), [docs/AUTH.md](../AUTH.md).

package/docs/adr/005-static-client-baseline.md

@@ -0,0 +1,19 @@
+# ADR-005 — Static client registration baseline; DCR off, CIMD deferred
+
+**Status:** accepted (implemented)
+
+**Decision.** The v1 baseline is static OAuth client preregistration by the local
+owner (`dodo auth add-client --redirect-uri <exact>`), copying the exact
+callback the client UI shows. Wildcard redirect URIs are rejected. Dynamic
+Client Registration (DCR) is **off** by default (deprecated in favor of CIMD in
+the current spec). CIMD is **deferred** because the feature was experimental in
+the `oidc-provider` version examined; enabling it requires allowlisted metadata
+origins, SSRF/redirect/private-IP protection, and pinned deps first.
+
+**Trade-off.** The owner registers a client once. In return there is no
+anonymous public registration surface.
+
+**Evidence / validation.** Redirect-URI exact-match, wildcard rejection, and
+secret-shown-once are covered by `integration/cli.test.ts` and
+`security/auth.test.ts` (AUTH-10, AUTH-12). Real ChatGPT registration mode is a
+manual gate (MAN-03). See [src/auth/clients.ts](../../src/auth/clients.ts).

package/docs/adr/006-guarded-fs-explicit-exec.md

@@ -0,0 +1,16 @@
+# ADR-006 — Guarded file tools + explicit native execution (no OS sandbox)
+
+**Status:** accepted (implemented)
+
+**Decision.** File tools are confined by one shared `WorkspaceFS` path policy;
+execution is explicit and gated by trust mode + per-action approval. We do
+**not** claim an OS sandbox. Programs run with the user's real OS privileges;
+`shell:false` reduces wrapper injection only, not confinement.
+
+**Trade-off.** `trusted` mode is genuinely powerful and dangerous; the boundary
+is "I trust this code with my account", not isolation. Documented prominently.
+
+**Evidence / validation.** Path traversal/symlink/hardlink/secret denial via
+tools in `security/pathTraversal.test.ts`; the non-sandbox limit is stated in
+[SECURITY.md](../SECURITY.md). See [src/workspace/fs.ts](../../src/workspace/fs.ts),
+[src/security/policy.ts](../../src/security/policy.ts).

package/docs/adr/007-preview-hash-journal.md

@@ -0,0 +1,18 @@
+# ADR-007 — Preview / hash / idempotency / journal for changes
+
+**Status:** accepted (implemented)
+
+**Decision.** File changes flow through: read (raw-byte SHA-256) → immutable
+preview plan → approval → apply (expected-hash recheck + durable journal +
+per-file backups + atomic temp/fsync/rename) → audit → optional rollback. Retry
+is idempotent via durable keys. Multi-file apply is explicitly **not** one
+filesystem transaction; unrecoverable partial failures surface
+`PARTIAL_RECOVERY_REQUIRED`. No automatic `git reset/clean/stash`.
+
+**Trade-off.** Much more code than `writeFile`, in exchange for not destroying
+the owner's work and surviving crashes with an honest recovery story.
+
+**Evidence / validation.** `integration/changes.test.ts` (14 cases: immutability,
+AMBIGUOUS_EDIT, FILE_CHANGED, idempotency replay/conflict, rollback conflict
+refusal, dirty-tree preservation, concurrency). See
+[src/services/changes/applier.ts](../../src/services/changes/applier.ts).

package/docs/adr/008-ts-js-semantics-first.md

@@ -0,0 +1,17 @@
+# ADR-008 — TypeScript/JavaScript semantics first, in a guarded worker
+
+**Status:** accepted (implemented)
+
+**Decision.** `symbols` / `references` / `preview_rename` use the bundled
+TypeScript Language Service running in a worker thread with a custom
+`LanguageServiceHost` that routes every file access through the same
+`WorkspaceFS` policy (plus a read-only allowlist for TypeScript's own lib dir).
+Other languages return `UNSUPPORTED_LANGUAGE` — grep is never labeled semantic.
+tsconfig is parsed as data; repo TS plugins are never loaded.
+
+**Trade-off.** Only TS/JS get true semantics in v1. Honest capability reporting
+over pretend coverage.
+
+**Evidence / validation.** `integration/semantics.test.ts` (shadowing/import/
+re-export references, homonym-safe rename, Python → UNSUPPORTED_LANGUAGE). See
+[src/services/intelligence/tsWorker.ts](../../src/services/intelligence/tsWorker.ts).

package/docs/adr/009-jobs-polling.md

@@ -0,0 +1,18 @@
+# ADR-009 — Jobs + polling as the execution baseline
+
+**Status:** accepted (implemented)
+
+**Decision.** Long work returns a `jobId` immediately; clients poll
+`job_status` / `job_output`. Jobs live in a service layer, not in any MCP
+session, so a dropped HTTP connection never kills a job and a reconnect can
+resume reading. Output is a bounded segmented on-disk spool. Cancellation
+signals only the owned process group; jobs from a previous boot become
+`interrupted_on_restart` and are never auto-rerun.
+
+**Trade-off.** No reliance on long-lived streaming or experimental task
+transports; the client must poll.
+
+**Evidence / validation.** `integration/jobs.test.ts` (prompt jobId, output after
+reconnect, stdin pipe, cancel, no-shell argv, idempotent single job, concurrency
+limit, PATH safety). Spool rollover in `unit/spoolAndConfig.test.ts`. See
+[src/services/jobs/jobManager.ts](../../src/services/jobs/jobManager.ts).

package/docs/adr/010-sqlite-better-sqlite3.md

@@ -0,0 +1,18 @@
+# ADR-010 — `better-sqlite3` durable store, chosen in M0
+
+**Status:** accepted (implemented)
+
+**Decision.** Durable state uses `better-sqlite3` `13.0.3` in WAL mode. It
+installed from a **prebuilt** binary on macOS arm64 with no compiler required
+(verified in M0; `dodo doctor` reports `sqlite-native`). Migrations run under
+`BEGIN IMMEDIATE`, and read-only CLI paths open the DB read-only so `dodo status`
+never races the server's startup migration. We did not choose `node:sqlite`
+because its API status warranted caution on the target Node.
+
+**Trade-off.** A native dependency (prebuilt-binary reliance). If no prebuilt
+exists for a target, install fails loudly — no silent in-memory fallback.
+
+**Evidence / validation.** Concurrent open safety is covered by
+`integration/cli.test.ts` (status while start boots). Native load is checked by
+`dodo doctor` and `packaging/pack.test.ts`. See
+[src/store/db.ts](../../src/store/db.ts).

package/docs/adr/011-env-example-secure-default.md

@@ -0,0 +1,19 @@
+# ADR-011 — `.env.example` denied by default (secure default)
+
+**Status:** accepted (implemented)
+
+**Context.** Spec §10.2 flags `.env.example` ambiguously: the `.env*` hard deny
+covers it, yet the text says it should not be excluded "by guessing".
+
+**Decision.** Apply the pack's conflict rule — "when specs conflict, choose the
+path that does not reduce security" — and keep `.env.example` under the `.env*`
+secret deny **by default**. An owner who wants it readable can allow it via
+explicit local policy in future (not exposed as a repo-config toggle, since repo
+config cannot widen access).
+
+**Trade-off.** A genuinely-template `.env.example` is unreadable by default,
+which is mildly inconvenient but never leaks a misused one.
+
+**Evidence / validation.** `unit/ignores.test.ts` asserts the secure default and
+documents the rationale. See
+[src/workspace/ignores.ts](../../src/workspace/ignores.ts).

package/docs/adr/012-workspace-scope-grant.md

@@ -0,0 +1,24 @@
+# ADR-012 — Grants at both OIDC and resource scope; first-party auto-consent
+
+**Status:** accepted (implemented)
+
+**Context.** During M0 the authorization flow returned `access_denied`
+("no scope granted"). Root cause: `dodo:*` are RFC 8707 resource-indicator
+scopes, and the just-created grant was not being reused as the consent grant
+because it was not yet linked to the browser session.
+
+**Decision.** (1) Advertise `dodo:*` both as global OIDC scopes (so the
+authorization request's `scope` param is accepted) and as resource-server scopes
+(so the access token audience is the `/mcp` resource); grant at both levels.
+(2) Implement `loadExistingGrant` to reuse the DODO grant the owner approved for
+this client + this workspace — the standard first-party trusted-client pattern —
+so the owner consents once over local IPC and the browser does not re-prompt. A
+grant bound to a different workspace is filtered out (no cross-workspace reuse).
+
+**Trade-off.** Slightly more grant plumbing; in return single-owner consent is
+one approval, and audience binding is still enforced by the verifier.
+
+**Evidence / validation.** `integration/m0` issues a working token; AUTH-07
+cross-workspace isolation holds in `security/auth.test.ts`. See
+[src/auth/provider.ts](../../src/auth/provider.ts),
+[src/auth/interactions.ts](../../src/auth/interactions.ts).

package/docs/adr/013-loopback-proxy-trust.md

@@ -0,0 +1,18 @@
+# ADR-013 — `trust proxy = loopback`; issuer from explicit config only
+
+**Status:** accepted (implemented)
+
+**Decision.** Express `trust proxy` is set to `'loopback'` (not `true`). The only
+hop in front of DODO is the owner's tunnel daemon on loopback, so its
+`X-Forwarded-Proto` is trusted for HTTPS/secure-cookie handling — but the OAuth
+issuer and resource URLs are **always** the explicit configured `publicUrl`,
+never derived from `Host` or `X-Forwarded-Host`. Host and Origin are allowlisted
+before the provider sees a request; `Origin: null` is denied.
+
+**Trade-off.** The owner must configure `publicUrl` correctly; DODO will not
+guess it from headers (which would be spoofable).
+
+**Evidence / validation.** `security/auth.test.ts` (AUTH-14: evil Host 403,
+`Origin: null` 403, spoofed forwarded headers do not change issuer; AUTH-13:
+loopback traffic still needs a token). See
+[src/server/appServer.ts](../../src/server/appServer.ts).

package/docs/adr/014-direct-coding-tier.md

@@ -0,0 +1,48 @@
+# ADR-014 — Direct coding-agent tool tier (v1.1)
+
+**Status:** accepted (implemented)
+
+**Context.** v1 shipped the 24-tool review workflow (preview → approve → apply;
+argv-only exec + job polling). The owner's actual use is an MCP client that
+confirms **every** tool call itself (ChatGPT developer mode), and wants the AI
+to work like a local coding agent — run tests, install packages, edit and search
+in one step — "as capable as AI coding tools".
+
+**Decision.** Add a direct tier of 9 tools on top of the SAME policy and
+journal, taking the catalog to 33:
+
+- `write_file`, `edit_file`, `delete_path`, `move_path`, `make_directory` — one
+  call each, implemented by building a single-op plan through the existing
+  `Planner` and applying it through the journaled `Applier`, so every direct
+  write stays hash-verified, backed up, visible in `change_history` and
+  reversible with `rollback_changes`.
+- `glob_files` — pattern search over the policy-filtered walk (`picomatch`).
+- `run_command` — a shell command **string** executed as `bash -c` (fixed
+  system binary), which waits up to `waitMs` and returns exit code + bounded
+  stdout/stderr inline; a still-running command hands back its `jobId`. This is
+  the same capability a trusted caller already had via
+  `exec_command(program:'sh', args:['-c', …])`, exposed ergonomically and gated
+  by the identical exec policy — it adds convenience, not authority. DODO itself
+  still spawns with `shell:false` (argv), so the only shell parsing is the one
+  the caller explicitly asked for.
+- `git_log` (read tier) and `git_commit` (exec tier: hooks run and the user's
+  git identity is needed). `all: true` stages only paths from the scoped,
+  secret-filtered status — never `git add -A .`.
+
+Trust-mode semantics are unchanged; `trusted` is now documented as the
+recommended mode when the client confirms each call.
+
+**Trade-off.** Fewer DODO-side checkpoints in `trusted` mode — by the owner's
+explicit choice, since the client dialog is the gate. The safety floor that does
+not depend on mode (path policy, secret deny, hash verification, journal,
+reversibility, no token/secret in child env) is untouched.
+
+**Evidence / validation.** `tests/integration/directTools.test.ts` (13 cases:
+the fix-the-bug loop with `run_command npm test` → `edit_file` → green,
+AMBIGUOUS_EDIT/FILE_CHANGED refusals, create/move/delete round-trip with
+rollback, policy + secret denial through direct tools, running-job handoff and
+cancel, a real local `npm install`, inspect-mode approval gating, `git_commit`
+that never stages `.env`). Catalog/schema counts updated to 33 in m0/compat/pack
+suites. See [src/tools/directTools.ts](../../src/tools/directTools.ts),
+[src/tools/jobTools.ts](../../src/tools/jobTools.ts),
+[src/services/git/gitService.ts](../../src/services/git/gitService.ts).

package/docs/adr/015-coding-agent-parity.md

@@ -0,0 +1,56 @@
+# ADR-015 — Coding-agent parity (v1.2): parallel commands, sandbox, patch, LSP, stdio
+
+**Status:** accepted (implemented)
+
+**Context.** After v1.1 the owner asked for DODO to match the tool set of
+Claude Code / Codex CLI / Kiro / OpenCode "in one package", including running
+several commands at once so the AI works faster. The MCP client confirms every
+call, so DODO's own approvals stay for `inspect`/`edit` but must not add
+friction in `trusted` mode.
+
+**Decision.** Add, on the same policy + journal:
+
+- **Parallel & background execution** — `run_commands` (up to 8 commands at
+  once, one result each), `run_command background:true`, `job_wait`.
+- **OS sandbox for commands** (Codex-style) — `run_command{sandbox:true}` /
+  global `commandSandbox: off|prefer|require`: macOS `sandbox-exec` seatbelt
+  profile or Linux `bwrap`, restricting **writes** to the workspace + declared
+  caches and optionally denying network. Availability is detected; `require`
+  fails closed. It confines what the command may *write*, not what it may read.
+- **`apply_patch`** — unified-diff application with `fuzzFactor: 0` (no fuzzy
+  matching); a non-applying hunk fails the whole call.
+- **`replace_in_files`** — bulk literal replace, dry-run by default.
+- **Grep parity** — `search_code` gains context lines, `fileGlob`, output modes
+  `files`/`count`, and a time-capped worker-thread regex fallback when ripgrep
+  is absent (the worker is terminated on timeout).
+- **`read_image`**, `read_files{numbered}`, `glob_files{sortBy:'mtime'}`.
+- **Agent memory** — `todo_write`/`todo_read` (per-workspace, outside the repo),
+  `read_instructions` (AGENTS.md / CLAUDE.md / .cursor/rules / .kiro/steering…
+  as untrusted conventions), `environment_info`.
+- **`fetch_url`** — opt-in (`allowWebFetch`), https-only, SSRF-guarded
+  (private/loopback/link-local refused, re-checked on every redirect hop),
+  gated like a command.
+- **LSP adapter** — owner-registered language servers (`dodo lsp add`) behind
+  the same semantic tools; see docs/LSP.md.
+- **stdio transport** — `dodo stdio` for local clients (Claude Code, Cursor,
+  Codex CLI, Claude Desktop): no tunnel, no OAuth; the local client process is
+  the principal. Trust modes, approvals and path policy are unchanged.
+- **Ecosystem task discovery** — Makefile, pyproject/pytest, Cargo, Go,
+  composer, Gradle, Maven recipes in `project_overview`.
+- `dodo audit` to review what the AI did.
+
+**Trade-offs.** More surface (43 tools). The sandbox is best-effort OS
+isolation of writes/network for the command process tree — not a security
+boundary against a hostile same-user process; `sandbox-exec` is deprecated by
+Apple but functional. `fetch_url` is network egress from the owner's machine
+and stays off by default.
+
+**Evidence / validation.** `tests/integration/agentTools.test.ts` (parallel
+results, background + job_wait, macOS sandbox write denial, search modes +
+regex worker, multi-file apply_patch + CONFLICT on stale hunks, bulk replace
+dry-run/apply, image block, numbered reads, instructions, todos, env info,
+Makefile recipes, fetch_url disabled/SSRF refusals),
+`tests/integration/stdio.test.ts` (real `@modelcontextprotocol/client` stdio
+transport against `dodo stdio`), `tests/unit/sandbox.test.ts` (seatbelt profile
++ real enforcement on macOS), `tests/integration/lsp.test.ts` (pyright over
+stdio JSON-RPC), `tests/integration/faultInjection.test.ts` (CHG-08/09).

package/docs/adr/016-oidc-openid-consent.md

@@ -0,0 +1,15 @@
+# 016 — Preserve requested OpenID consent
+
+The ChatGPT authorization request observed on 2026-09-09 includes `openid`
+alongside DODO resource scopes. The interaction adapter filtered this out of
+its grant, so oidc-provider 9.12.2 resumed into another consent interaction
+instead of returning an authorization code.
+
+Grant `openid` at the OIDC level only when the authorization request includes
+it. Keep resource scopes and workspace grants restricted to DODO permissions.
+Local approval, PKCE, session binding and static registration remain required.
+
+Evidence: AUTH-22 reproduced the redirect to a second interaction before the
+fix; after the fix, one approval reaches the callback, exchanges the code and
+successfully calls authenticated MCP tools/list. All 20 auth tests passed.
+Live ChatGPT/tunnel reconnection remains a manual verification.