dodo-mcp 1.0.0

package/docs/adr/017-installation-identity-local-config.md

@@ -0,0 +1,44 @@
+# 017 — Installation identity, workspace ACL and private config (baseline)
+
+Owner-requested change supersedes the original per-workspace OAuth grant-only
+contract. One running process still serves one canonical CWD/root and epoch.
+
+New consent records are marked `identity-grant:<id> = 2` in durable metadata.
+Tokens carry `dodo_auth: 2`. Verification requires both markers, issuer,
+audience, expiry, live grant and matching client. Resource scopes never exceed
+the token/grant intersection. Personal mode applies that ceiling to registered
+projects; managed mode also intersects the current workspace/client ACL.
+No remote tool can register a path or grant itself access. Refresh preserves
+grant version.
+
+OAuth consent is installation-scoped and does not follow the active workspace
+or the CLI process CWD. Completing login never creates a workspace ACL. An
+authenticated client may scan the bounded tool catalog before a project is
+selected. Operations require a real owner-registered project; only managed
+mode requires an additional explicit client ACL there. Pending/approve/deny and
+grant revocation locate the authenticated live HTTP installation process from
+private per-instance IPC metadata, so owner commands work from any directory.
+
+Migration 3 creates workspace_clients and copies active legacy grant scopes to
+their original paths only. Legacy tokens remain bound to their original root.
+Users log in once to receive the new identity grant. Revocation still checks
+the live grant on every request. Root inode/device replacement resets saved
+trust and client ACLs. Changing mode does not cancel already launched jobs.
+
+Bare dodo now starts HTTP regardless of stdin. MCP subprocess clients must
+explicitly use stdio. CLI HTTP starts local config at 127.0.0.1:21731, separate
+from MCP 21730. Library callers opt in with configPort (0 supported for tests).
+Admin API requires an 8-hour, random 256-bit per-process bearer capability,
+passed in the terminal URL fragment, never query strings. The page moves it to
+sessionStorage and strips the fragment. It rejects nonlocal hosts, foreign
+origins, cross-site fetches and proxy/Cloudflare headers. No CORS or public
+admin route. Same-UID adversaries and intentionally rewritten owner proxies
+are not an isolation boundary. No remote config opt-in in this release.
+
+--allow --all: run-only trusted actions and fetch_url; configured job sandbox.
+--bypass: same plus default commandSandbox off. Neither changes durable trust,
+OAuth, target authority, file guard, hashes or epoch checks. Flags do not alter
+client application's own confirmations. They are local owner capabilities.
+
+Recovery journal reconciliation, recovery status and interrupted-job updates
+are scoped to the selected workspace, to avoid modifying another root's state.

package/docs/adr/018-access-scope-encoding.md

@@ -0,0 +1,11 @@
+# 018 — ACL scope encoding contract
+
+OAuth grants store a space-separated scope list while `workspace_clients`
+stores JSON arrays. Schema migration must normalize the two representations
+without widening permissions.
+
+A transactional schema step normalizes recognized space-delimited scope lists
+and existing JSON ACLs. Invalid or unknown entries become empty ACLs, never new
+permissions. Empty ACLs remain empty, existing grants are not recopied on
+reopen, and runtime JSON decoding fails closed. Tests cover each supported
+schema transition and already-normalized state.

package/docs/adr/019-runtime-workspace-switch.md

@@ -0,0 +1,59 @@
+# 019 — Runtime workspace switch from Local Config (workspace lifecycle)
+
+Supersedes the "no runtime root change" statement of ADR-001 for the HTTP
+entry. One `dodo start` process still serves exactly one ACTIVE workspace at
+any moment, but the owner can move it to another directory from the Local
+Config page without restarting, re-authorizing OAuth clients, or losing state.
+
+## Decision
+
+- A `WorkspaceHost` (`src/server/workspaceHost.ts`) owns the active
+  `BootstrappedWorkspace`. The MCP server factory, the token verifier, the
+  consent router, the IPC dispatcher and the config plane resolve the active
+  workspace **per request** instead of capturing it in a closure.
+- OAuth and consent state use an installation-scoped store connection that
+  outlives any workspace; a workspace's own connection is closed when it is
+  switched out.
+- The switch is **owner-only**: `POST /api/workspace/switch` on the loopback
+  config plane, behind the private capability. There is no MCP tool that can
+  change the root, and the boot-time `--allow-unsafe-root` never applies to a
+  switch (the strict root policy always does).
+- Order of operations: validate (absolute path → realpath → shared root
+  policy) → refuse if jobs run → mark `switching` (new MCP calls get 503 +
+  Retry-After) → drain in-flight calls (bounded) → re-check jobs → refuse if
+  another live process serves the target (its IPC socket answers) → bootstrap
+  the new workspace (new workspaceId + fresh epoch, its own trust and ACL rows,
+  journal reconcile scoped to it) → readiness check → start its IPC socket →
+  **commit** → shut down the old IPC socket and services → deny orphaned
+  pending approvals of the old workspace/epoch → audit.
+- Any failure before commit discards the half-built workspace and leaves the
+  old one serving; failures after commit are logged and never roll back.
+- Nothing is copied between workspaces. Managed mode uses the new root's saved
+  trust mode and client ACL rows; personal mode derives trusted policy and
+  target scopes from the owner-approved installation grant. In both modes,
+  context captured from the old workspace fails
+  `WORKSPACE_MISMATCH` / `STALE_WORKSPACE`; plans expire; the run mode
+  (`--allow --all` / `--bypass`) is a per-process owner capability and
+  carries over.
+- The IPC socket path follows the workspace id, so `dodo status/stop/approve`
+  run from the new directory find the server; the old socket is removed.
+
+## Consequences
+
+- Clients must call `project_overview` again after a switch (the page says so).
+- `STALE_WORKSPACE` / `PLAN_EXPIRED` wording now mentions a switch.
+- Two `BootstrappedWorkspace` instances coexist briefly (WAL SQLite); the old
+  one is only torn down after the swap, so no request sees a closed store.
+- Refusals are explicit and typed (409 CONFLICT for jobs/in-flight/other
+  process, 400 for invalid targets, 501 for entries without switching).
+- Tests: `tests/security/workspaceSwitch.test.ts` (WS-01..06) and the Local
+  Config suite; manual browser checks are listed in MANUAL_ACCEPTANCE.md.
+
+
+## workspace lifecycle corrections
+
+Local admin mutations are bound to the reviewed workspace and epoch, not just
+the current root at arrival. Independent tool leases survive client disconnects.
+The switch gate stays closed through old-resource teardown. Shutdown closes
+old HTTP connections before OAuth stores, and retains handler resources until
+completion. Regression evidence: WS-07, WS-08 and WS-09.

package/docs/adr/020-desktop-access.md

@@ -0,0 +1,50 @@
+# ADR-020 — Local, app-scoped macOS desktop access
+
+Date: 2026-09-09. Status: accepted for desktop integration. The owner's explicit desktop
+feature request supersedes v1's prohibition on desktop automation; it does not
+remove OAuth, workspace identity, local authorization or the file guards.
+
+The owner later requested one-time saved desktop configuration. The optional
+persistent-grant behavior in [ADR-021](021-persistent-desktop-consent.md)
+supersedes only the mandatory expiration/boot reset described below for
+explicitly remembered grants; temporary grants retain this original behavior.
+
+Use a bundled Swift helper, explicitly compiled by `dodo desktop setup` with
+Apple Command Line Tools. No install lifecycle hooks, external relay, downloaded
+executables, arbitrary AppleScript, clipboard or autonomous LLM loop. This
+keeps one npm package and uses Apple's native permission checks:
+
+- [ScreenCaptureKit / SCScreenshotManager](https://developer.apple.com/documentation/screencapturekit/scscreenshotmanager): bounded single-window capture on macOS 14+.
+- [CGEvent](https://developer.apple.com/documentation/coregraphics/cgevent): explicit mouse/keyboard input; CGPreflightScreenCaptureAccess and AXIsProcessTrusted gate native operations.
+- [Vision text recognition](https://developer.apple.com/documentation/vision/vnrecognizetextrequest): optional local OCR. UI text is data, never authorization.
+
+APIs were verified by compiling against the installed Apple SDK and testing a
+native fixture on macOS 26.3.1 arm64. The SDK's CGEvent.h notes that application
+frameworks may ignore an event's Unicode string; callers must verify the result.
+The [Desktop Commander project](https://github.com/wonderwhy-er/DesktopCommanderMCP)
+and available connector catalog informed the comparison only; no assertion
+about its hosted internals or complete parity is made.
+
+Desktop authorization is off by default and a separate, expiring, exact-app
+allowlist stored per workspace/boot epoch. Only private owner IPC enables it;
+private Local Config can revoke. All image/UI tools beyond non-content status
+require dodo:exec and the current client/path ACL, including over OAuth. View
+permission enables reading; control additionally uses the existing exec trust
+and exact local action approval gate. Run overrides do not enable desktop.
+
+Snapshot IDs bind principal, workspace service/epoch, grant, window PID/id/app,
+geometry and image-coordinate mapping for at most 30 seconds. Actions use a
+single service mutex; all snapshots are invalidated before dispatch. A durable
+started receipt precedes input, and uncertain outcomes are never automatically
+repeated. Native checks require a frontmost matching window for input and check
+point occlusion; they do not freeze the UI or form a same-UID security boundary.
+
+Image bytes and typed text are not persisted in the state/audit; file-image
+reads still use WorkspaceFS. Native helper input/output, OCR, AX traversal,
+action size, process time and receipt count are bounded. Stop prevents future
+dispatch, not rollback of OS events already posted.
+
+Native compile/capture/OCR and refusal without Accessibility passed. Positive
+Accessibility/input acceptance remains MANUAL_NOT_RUN because the machine did
+not grant that OS permission. Default tests use a fake OS adapter so they never
+click a user's screen; HTTP/OAuth/IPC/SQLite policy tests remain real.

package/docs/adr/021-persistent-desktop-consent.md

@@ -0,0 +1,39 @@
+# ADR-021 — Remember desktop consent for an installation
+
+Date: 2026-09-09. Status: accepted for persistent desktop consent at the owner's explicit request.
+
+`dodo desktop allow --app <exact-bundle-ids> --mode view|control --persist --yes`
+saves standing consent until disabled. It works before a server is started.
+Without `--persist`, consent retains the 60-minute default (1–480 configurable)
+and expires on boot/root switch. Mixing `--persist` and `--minutes` is rejected.
+Every persistent allow replaces the installation app/mode grant.
+
+Use the existing private SQLite meta store keyed by installation. No project
+file, public endpoint or MCP tool can set this policy. Saved consent applies to
+all registered project runtimes but does not grant OAuth scopes, register roots,
+change exec trust or relax snapshot checks. Temporary grants remain keyed by
+workspace and epoch. The local CLI and owner IPC/UI
+share one validated writer. CLI save/disable use local SQLite directly, like
+the existing trust command, so neither needs a running server. There is no
+automatic listener, native helper setup or OS permission prompt.
+
+The stored policy adds `persistent` (legacy default false), `revision` (UUID),
+and nullable `expiresAt` (null only for explicitly persistent grants). On read,
+persistent consent binds the current service epoch. Every replacement receives
+a new revision; running services re-read it before work, so old snapshots and
+action approvals cannot survive a CLI change even with identical apps/mode.
+Snapshots remain principal-bound and at most 30 seconds. Uncertain action
+receipts remain durable and never auto-replay after restart.
+
+`dodo desktop disable` and the private config stop button revoke AND forget the
+installation grant. They prevent future dispatch; neither can retract an already
+posted OS event. Exact named-app allowlisting remains mandatory. Same-UID
+processes remain outside the security boundary.
+
+Evidence: existing Zod 4 and better-sqlite3 13.0.3 APIs, no new dependencies or
+native code. Unit cases cover old records, malformed records, expiry versus
+persistence, roots/epochs, revision invalidation and cross-connection revocation.
+Real CLI tests save offline, start/restart a nested Thai/space path, reuse the
+grant from its parent, then revoke while stopped. HTTP/OAuth tests retain scope,
+workspace snapshot and action boundaries with a fake OS adapter. Final outcomes are recorded
+in TEST_REPORT; this change does not claim new native click/type acceptance.

package/docs/adr/022-owner-kill-preserves-login.md

@@ -0,0 +1,30 @@
+# ADR-022 — CWD-independent owner shutdown preserves OAuth identity
+
+Date: 2026-09-09. Status: accepted for owner shutdown, requested by the owner.
+
+Implement `dodo kill` as a lifecycle command over private IPC, not process-name
+matching or a signal to whatever owns 21730. Resolve the owner's installation
+config independently of CWD and read the SQLite workspace registry without
+writing/migrating auth data. Old versions are discoverable through their root
+sockets. New versions also maintain a unique per-instance control socket and
+ephemeral metadata so multiple stdio clients of the same root stay discoverable.
+
+Validate private same-user sockets, live status/root/workspace and endpoint
+identity. Stop requests include expected PID/epoch; new servers reject stale
+values. Probe first and deduplicate processes before dispatching stops. Bound
+concurrency to eight, response bytes and wait durations. Report failures rather
+than silently force-killing a hung or unregistered process. Another
+DODO_CONFIG_DIR is a separate installation; never scan other users/configs.
+
+Cancel owned jobs before draining handlers that may wait for their completion.
+Prevent new jobs once shutdown starts and share the close promise with repeated
+callers. Library shutdown closes resources; the CLI exits after completion.
+Keep OAuth keys, clients, tokens, grants, config and ACLs. Restore neither
+expired/revoked credentials nor missing client access to another root.
+
+Tests cover real child HTTP/stdio processes, duplicate stdio roots, unrelated
+process/config preservation, owned job cancellation, and real OAuth access plus
+refresh credentials after restart. Negative cases cover spoofed status,
+symlink/non-private sockets, stale stop identity, oversized IPC and timeout.
+Actual ChatGPT automatic reconnect is a manual gate; local token continuity
+does not prove client retry behavior. See TEST_REPORT for commands/outcomes.

package/docs/adr/023-large-coding-inputs.md

@@ -0,0 +1,49 @@
+# ADR-023: Large coding inputs with owner-controlled budgets
+
+Date: 2026-09-09. Status: accepted in large-input policy (source/local).
+
+## Problem
+
+The original 8,192-character shell field and 4,096-character argv elements
+blocked ordinary generated web source. Raising only the schema cap would
+still hit native execve limits. Unlimited requests would make memory use
+unbounded, and old persisted configs would retain their small limits.
+
+## Decision
+
+Use owner-selected `dodo limits --profile standard|large`; merge only input
+budgets into trusted global config and require restart. Preserve saved values
+on upgrade. Expose active budgets via project_overview. Command source is
+checked in UTF-8 bytes (default 1 MiB, maximum 8 MiB); direct source schemas
+support up to 16 MiB with lower active file/plan/request limits enforced.
+Native argv remains independently bounded to 64 KiB per element, 128 KiB total.
+
+Shell source above 16 KiB runs as a mode-0600 private script under an owned
+mode-0700 job directory. No source in native argv, no stdin consumption, no
+workspace source artifact. Record job ownership before spawning. The normal
+job lifecycle removes scripts on exit/cancel/spawn failure. Crash residue is
+never rerun. Script semantics (`$0` points to the script) are documented.
+Scopes, trust, sandbox requests, idempotency and owned process cancellation
+still apply. Validate every batch command's size/NUL before launching any.
+
+Keep response/log caps. Bound echoed commands/argv. Skip diff construction for
+combined before/after content above 2 MiB; smaller diffs use abortable budgets.
+Preflight literal replacement expansion and incrementally bound patch/bulk
+result content. Full hashes, backups, immutable plans and rollback are kept.
+
+## Evidence and compatibility
+
+Installed official MCP server SDK 2.0.0 `stdio.d.mts` exposes
+`serveStdio({transport})` and `StdioServerTransport(...,{maxBufferSize})`.
+Use that API to align STDIO buffer size with HTTP request limits; no custom
+wire protocol. HTTP authenticates before parsing larger JSON bodies.
+Installed diff 9.0.0 `libesm/patch/create.d.ts` supports abortable
+`createTwoFilesPatch` with timeout/maxEditLength and undefined on exhaustion.
+No dependency or OAuth protocol changes.
+
+Actual tests include real modern/legacy HTTP, an 11 MiB STDIO file, an exact
+8 MiB shell command via STDIO, 3 MiB write/edit/rollback, UTF-8 limits,
+parallel commands, stdin, cancellation, sandbox, failed spawn and state writes,
+owner CLI profiles and pre-allocation expansion refusal. See TEST_REPORT for
+the executed gate, versions and results. External client/proxy input limits
+are independent and manual acceptance is not claimed.

package/docs/adr/024-usage-rounds-and-schedules.md

@@ -0,0 +1,72 @@
+# ADR-024: owner-confirmed usage rounds and separately approved schedules
+
+> Conversation/usage-round portions superseded by [ADR-026](026-remove-conversation-confirmation.md). Scheduled-command approval remains accepted. The original decision below is retained as design context.
+
+Date: 2026-09-10. Status: retained design decision. Supersedes any earlier assumption
+that OAuth/trust alone enables project tools, or that a missing workspace ACL
+is an invalid OAuth identity token.
+
+## Decision and limits
+
+Installed official MCP SDK server/client 2.0.0 provides the existing stateless
+HTTP and STDIO handlers; neither the request label nor a model-chosen ID is a
+trusted conversation identity. Do not invent a protocol session and claim chat
+isolation. Ship fail-closed owner-approved usage rounds with client/grant/root/
+epoch/expiry binding, and require cooperative clients to create a new round per
+conversation and end it on revocation/end. No verified chat adapter is claimed.
+An approved ID replayed by the same authenticated principal in another chat is
+indistinguishable in this fallback. Process restart/root switch requires a fresh
+round; a dropped network connection does not.
+
+All actual tools, including overview/read/job/desktop, share the gate before
+handler dispatch. Only usage_request/status/end are exempt control operations;
+these reveal no workspace context. No MCP approve operation exists. Owner CLI
+uses private IPC; UI approval keeps existing capability/origin/workspace epoch
+checks and requires typing the displayed phrase. Default TTL 60 min, max 8h;
+pending requests expire in 10 min. Internal bootstrap/recovery by the owner CLI
+and OAuth/protocol metadata are control-plane operations, not granted tool use.
+
+A valid identity token without active workspace permissions authenticates with
+zero effective scopes. Tools return WORKSPACE_ACCESS_REQUIRED with null workspace
+context, without WWW-Authenticate. Invalid/expired/wrong-audience/revoked tokens
+still fail at the resource server. No root access is added by this distinction.
+
+Schedules have immutable specs/digests and local owner approval distinct from
+usage consent. They run current project code, not a pinned revision. Baseline
+saved trust must be trusted and the captured root/policy must match. Defaults:
+require OS sandbox, network off, timeout 5 min, expiry explicitly supplied up to
+30 days, five-field cron. Local owner-created schedules do not depend on OAuth;
+remote proposals additionally depend on their client's live exec ACL/grant.
+
+SQLite migration 5 adds usage_consents, schedules and schedule_runs. Claim due
+slots and advance next_at in BEGIN IMMEDIATE before spawn. A crash may lose an
+execution, but never automatically replays an uncertain occurrence. Skip missed
+and overlapping ticks. Scheduler is internal to the active HTTP workspace only;
+no OS cron/launchd installation, no inactive-root traversal, no auto-start service.
+
+## Evidence
+
+- Registry verified cron-parser 5.10.0 (Node >=18), pinned exact with lockfile.
+  API read from installed declarations: CronExpressionParser.parse(...,
+  {tz,currentDate}).next().getTime(); use maintained parser for calendar/timezone
+  computation. Upstream: https://github.com/harrisiirak/cron-parser
+- Installed SDK declarations support McpServer options.instructions; both transports
+  advertise confirmation/revocation instructions without changing the MCP protocol.
+- tests/security/usageConsent.test.ts: actual HTTP/OAuth dispatch denied before
+  confirmation, local IPC/UI approval, replay/client/root/epoch/expiry/revoke cases.
+- tests/integration/schedules.test.ts: pending/approve/hash, real execution,
+  overlap, revoke, restart/missed/uncertain, policy/grant changes, shared claims.
+- Existing identity tests now assert zero effective scopes AND tool denial, rather
+  than only an OAuth exception. Old-schema migration fixtures remove later tables
+  when reconstructing the actual historical schema.
+- Exact totals and manual gates: TEST_REPORT and MANUAL_ACCEPTANCE.
+
+## Threat model
+
+Private same-UID IPC is the existing owner authority boundary, not a defense
+against hostile code already running as that OS user. Unsandboxed trusted exec
+or desktop control can act with user privileges, including interacting with
+owner controls. Prompt instructions forbid self-approval, but are not an OS
+security boundary. These limitations remain explicit; usage consent does not
+turn arbitrary code execution into isolation. No server-side guarantee of
+recognizing chat text or closing a chat is claimed.

package/docs/adr/025-owner-chat-whitelist.md

@@ -0,0 +1,53 @@
+# ADR-025: Owner-first chat references and reset
+
+> Superseded by [ADR-026](026-remove-conversation-confirmation.md). This record describes historical behavior, no longer active.
+
+Accepted: 2026-09-10. Retained as design context.
+
+Owners want to paste a ChatGPT /c/ URL without first asking an AI to create a
+pending usage request. The installed MCP SDK 2.0.0 contract supplies no trusted
+ChatGPT conversation identity. A caller-supplied UUID is not authentication.
+
+Decision: accept strictly parsed URLs/UUIDs only on the existing owner CLI/IPC
+and private Local Config plane. Migration 6 stores permission generations bound
+to workspace ID, directory device/inode and selected client. Owner permissions
+persist until reset or optional expiry; duplicate allow is idempotent and does
+not extend expiry. No new remote approval tool, public endpoint, OAuth scope or
+DCR behavior is introduced. Ambiguous client selection fails closed.
+
+Every operation accepts `chat` alternatively to an approved `usageId`. A valid
+reference derives an epoch/grant-bound round from the standing permission. The
+reference never falls back to a different or sole allowed chat. Round revocation
+also revokes its parent permission; automatic round expiry does not, so an
+unexpired standing permission can derive a fresh round. Reset invalidates all
+linked rounds, including old epochs; allowing again uses a new generation.
+Current live jobs belonging to those rounds are canceled. Schedules and OAuth
+remain independent. Root replacement invalidates old permissions.
+
+The private UI retains capability, Origin/forwarding rejection and workspace
+header checks for every mutation. Chat links are parsed as text, never fetched.
+`dodo reset` means current-workspace usage/chat reset, not factory reset. CLI
+controls require a running process for that CWD; no offline/global reset implied.
+
+Limitation: a cooperating client must supply the correct current-chat reference.
+Another conversation using the same authenticated client can replay a permitted
+reference. Whitelisting is owner consent with caller-supplied correlation, not
+attestation or a verified lifecycle. This limitation is explicit in UI, server
+instructions, tool descriptions, CLI output and docs. A trusted client adapter
+would be needed to guarantee actual conversation isolation.
+
+Evidence: chatConsent security fixtures cover raw MCP dispatch, no-root denial,
+private UI, CLI reset, client/workspace isolation, root replacement, expiry,
+revocation/cancellation and separate Cron execution; STDIO and packed-package
+fixtures exercise the installed commands. See TEST_REPORT for actual commands
+and results. No live ChatGPT conversation test is claimed.
+
+### client context policy compatibility amendment
+
+A user supplied a real-world `/c/WEB:UUID` URL rejected by the initial parser.
+Accept that explicit namespace (or bare WEB:UUID) across the shared parser.
+Preserve the prefix rather than stripping it: the server has no attestation that
+a namespaced identifier equals the same bare UUID. Case normalizes within each
+format; approval/reset do not cross namespaces. No arbitrary prefix, URL decode,
+network request or weaker host/path check is added. Regression cases exercise
+CLI, private UI API, MCP, namespace isolation/reset, STDIO and installed tarball.

package/docs/adr/026-remove-conversation-confirmation.md

@@ -0,0 +1,35 @@
+# ADR-026: remove conversation confirmation; retain existing access policy
+
+Status: accepted, 2026-09-10. Supersedes ADR-025 and the usage-round portion of
+ADR-024; scheduled commands retain their separate local approval.
+
+## Decision
+
+The owner explicitly requested removal after the chat-ID workflow proved cumbersome.
+Remove the gate entirely rather than infer a conversation from untrusted labels
+or silently approve a default chat. The MCP transport exposes no verified chat
+identity in our installed integration; an owner-pasted ID never proved one.
+
+HTTP authentication, effective workspace ACL/scopes, workspace ID/epoch, trust,
+action approval, Desktop policy, path/hash/journal checks remain. Both HTTP and
+STDIO start with direct project_overview. Shared connections share permission;
+DODO no longer claims conversation-level permission or revocation.
+
+Remove all three usage tools, chat/usageId wire fields, owner chat/usage/reset
+commands, private routes/UI and usage service/timer. Keep schedule_propose and
+owner schedule approval. Catalog: 52 -> 49. Job principal is the authenticated
+grant. This policy requires refreshing cached tool schemas and restarting DODO.
+
+Retain migrations 5/6 and their old tables as inert upgrade history, without
+runtime permission reads/writes. Do not reset OAuth, keys, ACLs, desktop consent,
+schedules, files or audit history. This avoids destructive rollback of state.
+
+## Evidence
+
+Dependencies unchanged: MCP SDK 2.0.0, oidc-provider 9.12.2 and better-sqlite3
+13.0.3. directAccess.test.ts covers immediate HTTP read/write/exec, removed
+schemas/interfaces, legacy rows across restart and unchanged auth/path/trust
+boundaries. STDIO, schedule, kill and package tests dispatch without any hidden
+consent fixture. Removed feature tests are replaced by direct-access regressions;
+existing auth, file safety, exec and Desktop security tests remain. Exact commands
+and outcomes are recorded in TEST_REPORT.md; external AI-client runs remain manual.

package/docs/adr/027-workspace-client-list.md

@@ -0,0 +1,20 @@
+# ADR-027: show current-root client access; keep OAuth registration shared
+
+Status: accepted, 2026-09-10.
+
+The owner wants Client access to show only the running folder's clients. The
+old UI listed all registrations, making unrelated ChatGPT entries look active.
+Filter the main state/list by nonempty current-workspace ACL. Preserve shared
+OAuth registration and other-root ACLs, rather than duplicate or delete clients.
+
+An owner can explicitly add an existing registration through an on-demand picker
+under the same private capability/Host/Origin boundary. Bind its read and write
+to the reviewed workspace/epoch; invalidate stale UI responses on switch. Add-only
+writes reject an existing ACL to avoid overwriting another tab's recent grant.
+Revocation removes only the local ACL/card; it leaves login and registration.
+
+No dependency/schema migration/MCP wire change. Evidence: localConfig security
+fixtures for filtering, secret exclusion, read-only enumeration, local-only
+addition/revocation and stale/foreign requests; workspaceSwitch verifies filtering
+and unchanged cross-root OAuth denial. Browser fixture checks the actual owner
+picker. Exact results are in TEST_REPORT; real ChatGPT remains MANUAL_NOT_RUN.

package/docs/adr/028-owner-client-deletion.md

@@ -0,0 +1,25 @@
+# ADR-028: explicit reviewed deletion of selected OAuth clients
+
+Status: accepted, 2026-09-10. The owner requested a clear-client button.
+
+Keep the current-folder access list. A separate collapsed manager loads safe
+installation-wide ID/name/count summaries on demand and deletes only explicitly
+selected registrations (up to 100). Confirm the global effect with exact IDs.
+The UI uses textContent; no client secret or callback is returned by review.
+
+Deletion is a single SQLite IMMEDIATE transaction after all review hashes match:
+deny related approvals, revoke grant rows, remove provider models and workspace
+ACLs, delete client registrations, audit. Roll back the entire batch on failure.
+Keep histories and unrelated registrations/keys/files. No wildcard future-client
+selection, reset of state or remote MCP tool is introduced. Existing work may
+finish; subsequent calls/refresh and grant-backed scheduled launches are denied.
+
+The existing oidc-provider 9.12.2 implementation (lib/models/client.js Client.find)
+consults the adapter before dynamic-cache reuse; clients:[] avoids static cached
+registrations. The verifier independently checks registration existence and
+interaction completion checks again after asynchronous grant persistence.
+
+Evidence: clientDeletion.test.ts real access/refresh, preserved second client,
+stale/hostile requests, race-safe selection and injected SQLite rollback tests;
+local browser cancel/select/delete/empty-state check. Exact outcomes in
+TEST_REPORT. Real owner clients were not deleted. No new dependencies/migrations.

package/docs/adr/029-compact-tool-surface.md

@@ -0,0 +1,121 @@
+# 029 — Compact MCP tool surface with capability gateways (tool surface policy)
+
+Status: accepted, 2026-09-10.
+
+## Problem
+
+The catalog contains 74 tools. The full `tools/list` serializes to roughly
+236 KB. Remote MCP clients ingest every tool definition at connection time,
+and clients differ in the catalog/schema volume they retain. HTTP+OAuth and
+STDIO fixtures prove the direct write/edit path independently. No hard
+per-client tool limit is claimed; compact mode reduces catalog/schema load and
+avoids requiring clients to ingest every detailed operation schema at
+connection time.
+
+## Decision
+
+Two tool surfaces over ONE unchanged capability set:
+
+- **full** — the existing 74-tool catalog, byte-for-byte the same names,
+  order, schemas and behavior. Default for STDIO (Codex, Claude Code, Cursor).
+- **compact** — 19 tools: `project_overview`, `dodo_discover`, and 17 domain
+  gateways (`dodo_read`, `dodo_write`, `dodo_exec`, `dodo_git_read`,
+  `dodo_git_write`, `dodo_desktop_view`, `dodo_desktop_control`,
+  `dodo_assist_read`, `dodo_assist_change`, `dodo_media`, `dodo_browser`,
+  `dodo_game`, `dodo_workflow_read`, `dodo_workflow_write`,
+  `dodo_workflow_run`, `dodo_schedule`, `dodo_web`). Default for HTTP.
+  A gateway call is `{ workspaceId, workspaceEpoch, operation, args }` where
+  `operation` is enum-bound to that gateway's fixed allowlist; every
+  full-catalog tool except `project_overview` is reachable through exactly one
+  gateway. `dodo_discover` searches operations and returns one operation's
+  args-only JSON Schema plus a deterministic `schemaHash`; workspace context
+  remains top-level gateway input and cannot be overridden inside `args`.
+
+Selection: `toolSurface` in the global config overrides the transport default;
+`--tools compact|full|hybrid` on `dodo start`/`dodo stdio` overrides both for one
+run. The setting changes tool exposure only — never permissions.
+
+## Security invariants (unchanged, now single-pathed)
+
+`registerTool` and the gateways route through one function,
+`invokeToolDefinition` (src/tools/context.ts): live principal →
+WORKSPACE_ACCESS_REQUIRED on empty workspace ACL → the TARGET tool's
+`requiredScope` → workspaceId/epoch context → request byte budget → the
+target's ORIGINAL strict Zod input schema → the target handler (which runs its
+own `policyGate`/local approvals, idempotency and journaling) → envelope →
+audit. Consequences, all covered by tests:
+
+- A read-only token calling `dodo_write(write_file)` fails `FORBIDDEN` with
+  the target's scope in `detail`, exactly like the direct call.
+- In `inspect` mode an effectful gateway call produces an approval bound to
+  the TARGET operation (`tool: write_file`), never a blanket gateway approval.
+- `args` may not carry `workspaceId`/`workspaceEpoch` (rejected
+  `INVALID_INPUT`); the gateway injects the top-level context itself.
+- Target error codes (`FILE_CHANGED`, `AMBIGUOUS_EDIT`, `SECRET_PATH_DENIED`,
+  `APPROVAL_REQUIRED`, …) pass through unchanged via `fromErrorInfo`.
+- Image/audio MCP content blocks pass through unchanged.
+- Gateways cannot target other gateways, `project_overview`, owner IPC
+  controls or anything outside the fixed allowlists (construction-time
+  invariant + tests). Each gateway's own `requiredScope` is computed as the
+  minimum of its targets, so it can never be broader than the catalog.
+- Both the gateway call and the target invocation are audited.
+
+## Evidence
+
+- Serialized tools/list-equivalent payload (name+title+description+annotations+
+  input+output schemas): 74 tools = 237 755 bytes; compact 19 = 46 834 (−80.3%);
+  measured live tools/list: 236 518 → 46 707 bytes. Recorded by the
+  `[dodo] mcp tool surface` startup diagnostic and `schemas/tools.compact.json`.
+- Suites: `tests/unit/compactSurface.test.ts`,
+  `tests/security/compactGateway.test.ts`,
+  `tests/integration/compactHttp.test.ts`,
+  `tests/integration/compactStdio.test.ts`,
+  `tests/integration/compactCapabilities.test.ts`, packaging PACK-12; the 24
+  direct-contract suites pin `toolSurface: 'full'` explicitly.
+- Live ChatGPT re-scan against the compact surface is a MANUAL gate
+  (MANUAL_ACCEPTANCE.md); no client-side limit figure is asserted.
+
+## Addendum (tool surface policy): hybrid surface
+
+The owner's live ChatGPT connector displayed exactly 49 tools against a
+74-tool catalog — the first 49 in catalog order — consistent with a
+client-side tool-count cap near ~50 (still not asserted as a universal
+constant). For clients in that range that prefer direct tools, the
+opt-in `hybrid` surface: 49 tools, compact coverage core first (truncation-
+safe), then 30 direct coding tools (`HYBRID_DIRECT_OPERATIONS`). Selection
+via config/CLI as before; defaults unchanged; every path keeps the shared
+invocation pipeline.
+
+## Addendum (Phase 04): resource operations
+
+ADR-034 adds six individual resource definitions to Full, so the Phase 04 surfaces
+became Full 89, Compact 19 and Hybrid 49. Compact/Hybrid route the new operations
+through the existing `dodo_media` gateway; no new gateway or direct Hybrid duplicate
+was added. The historical 74-tool measurements above remain the evidence captured
+when this ADR was first accepted. Generated schemas and `docs/TEST_REPORT.md` carry
+the current byte measurements.
+
+## Addendum (Phase 07): owner-reviewed memory operations
+
+ADR-037 added five individual memory definitions to Full, so the surfaces at that point were
+Full 121, Compact 19 and Hybrid 49. Compact/Hybrid route read operations through
+`dodo_assist_read` and proposal operations through `dodo_assist_change`. Owner approval,
+rejection, prune and learning review remain private IPC commands and are never added
+to any MCP surface.
+
+## Addendum: provider-backed sub-agents
+
+ADR-045 adds four individual Sub-agent definitions, so the current surfaces are Full 125,
+Compact 19 and Hybrid 49. Compact/Hybrid route them through the existing assistance
+gateways. Personal/managed access mode changes authorization decisions only; it does not
+change catalog size or let a gateway bypass the target definition.
+
+## Addendum: optional Sub-agent exposure
+
+The installed capability contract still contains all 125 definitions, but
+`exposeSubagentsToMcp` defaults to false. A live Full surface therefore registers 121
+tools by default. Compact and Hybrid keep their stable 19/49 gateway names while removing
+the four Sub-agent operation values from their schemas, discover index and instructions.
+The private web workbench remains able to create and manage runs. Enabling the setting
+requires a process restart and client catalog rescan; it changes exposure only and never
+authority.