@toddzheng024/dscode-desktop 0.0.0-stage → 0.7.33

package/docs/computer-use.md

@@ -0,0 +1,81 @@
+# Computer Use
+
+Computer Use observes and operates local macOS application windows through
+Accessibility, with screenshot artifacts for visual evidence. Prefer a connector,
+API, CLI or browser tool when one can complete the task directly.
+
+## Experimental Desktop adapter
+
+The [combined Desktop package](browser-use.md#install-the-experimental-combined-desktop-package)
+includes an experimental native adapter. It requires macOS 14 or later; the
+packaged helper supports Apple Silicon and Intel. Other platforms keep the Host
+available and report Computer Use as unsupported, without exposing its tools.
+
+In a DSCODE session, load the `dscode-computer-use` skill before using native tools.
+Loading the exact bundled skill activates app discovery, observation, click,
+value entry, typing, keyboard, scrolling, dragging, advertised Accessibility
+actions, bounded waits and sensitive-action confirmation. Native Standard
+sessions do not receive this skill or its tools. A successful skill load is
+restored from persisted session history; unloading the plugin removes its tools
+from open agents, and reloading restores them where that history permits.
+
+`/computer` or `/computer status` checks helper health and reports Accessibility
+and Screen Recording permissions. A healthy helper can still report a missing
+OS permission. It does not change those permissions or application grants.
+
+The current qualification covers helper integrity and initialization, app
+discovery, progressive activation, native session resume, Standard isolation,
+denied unconfigured app access, and live-plugin unload/reload on Host versions
+`0.2.0-rc.2` and `0.2.1-alpha.1`. The tested helper reported Accessibility denied.
+**Reading application windows, screenshot capture and input actions have not yet
+been qualified in the Desktop adapter.** Their presence in the tool catalog does
+not establish that those operations work on your machine.
+
+## Application and OS permissions
+
+There are two independent permission layers:
+
+- macOS Accessibility and Screen Recording govern the native process. Grant them
+  through System Settings when you choose to permit these capabilities. Use
+  `/computer` to recheck after changing permissions or restarting Desktop.
+- DSCODE app read/control grants select which applications a session may use.
+  Missing grants follow the session's approval policy. A rejected request stays
+  rejected for that session and scope. With prompts disabled, missing grants are
+  denied without a user dialog; full filesystem access does not grant app access.
+
+The Desktop entry is `dscode-desktop-computer-use`. Its profile configuration can
+grant exact bundle IDs. For example, this grants read access only to TextEdit:
+
+```yaml
+- id: dscode-desktop-computer-use
+  config:
+    allowAllApps: false
+    observationTtlMs: 30000
+    grants:
+      - bundleId: com.apple.TextEdit
+        read: true
+        control: false
+```
+
+Restart Desktop after editing the profile configuration. `control: true` also
+permits reading that app. Wildcard bundle IDs are rejected. Defaults grant no
+applications and preserve the user's foreground app for both pointer and
+keyboard input. The adapter uses the Host's configuration directly and does not
+install the upstream plugin's retired Settings API or its old Web settings page.
+
+## Observation and image evidence
+
+Actions require a fresh observation ID. Element indices belong to that
+observation; opaque target handles permit only validated, unambiguous rebinding.
+Successful actions return fresh state. Sensitive actions require a one-use
+confirmation tied to the app, observation and exact action; a changed target
+requires fresh confirmation.
+
+Screenshots are stored as workspace image artifacts. Use the Host's `read_image`
+tool and an image-capable model to inspect the returned path. Missing model image
+support is a separate limitation from Screen Recording permission. The Desktop
+adapter does not require the separate upstream Vision Toolkit plugin.
+
+The terminal installation continues to use its existing `computer-use` skill and
+upstream bundle. Desktop-specific activation, configuration and qualification
+described here do not change that terminal integration.

package/docs/custom-providers.md

@@ -0,0 +1,88 @@
+# Custom model providers
+
+Use `/provider custom`, or choose **Custom** in `/provider`, to connect a self-hosted or private model API. DSCODE runs its tools in the current workspace; pointing inference at another computer does not move shell commands or file edits to that computer.
+
+Saved services appear by name in `/provider`. Choose a service and press Enter to switch to its current or first configured model; `/model` then selects among that service's models. **Custom · add / edit model services** opens configuration instead of switching. A service without a model context window opens its editor so the missing setting can be completed.
+
+## Add a service
+
+Choose **Add provider** and enter a name and API base URL. The URL is the API prefix, for example `http://studio:8000/v1`, not a complete chat endpoint. The editor displays the final request URL.
+
+Choose one API format:
+
+| Format | Path appended to the base URL | Default authentication |
+| --- | --- | --- |
+| Chat Completions | `/chat/completions` | Bearer token |
+| Responses | `/responses` | Bearer token |
+| Anthropic Messages | `/messages` | `x-api-key`, with the Anthropic version header |
+
+Authentication can be changed independently to **none**, **bearer** or **x-api-key**. For example, oMLX uses Bearer authentication even when serving Anthropic Messages. No-auth requests omit the key entirely. API keys are masked while editing; leaving the field blank preserves an existing key.
+
+Use Up/Down to navigate and Enter to edit or activate. For API format, authentication, thinking and input type, Enter opens a choice editor; use the arrow keys to choose, Enter to apply, or Escape to cancel that choice while keeping the provider form open. In text fields, Ctrl+U clears the field and Escape cancels the edit. Terminal paste markers and line breaks are removed from pasted field values. Enter applies a field to the draft; **Save** persists the provider. Outside a field editor, Escape goes back. **Save and switch to this model** also selects the model for the next step, using the existing context-compaction check when needed. Escape cancels discovery and test requests. Saving configuration is allowed while the server is offline.
+
+## Models and context
+
+**Discover models** requests `/models`, relative to the API prefix. Select models with Enter or Space, then choose **Use selected models**. Existing models are kept; remove one from its model editor when needed. If discovery is unavailable, choose **Add model manually** and enter the server's exact model ID.
+
+Each model has its own context window and output budget. The context window is required before the model appears in `/model` or can be tested. Discovery accepts positive `max_model_len`, `context_length` or `context_window` values; unknown values remain blank. It does not infer capacity from the model's name.
+
+For a listing identified as oMLX, DSCODE also reads `/models/status`. Valid positive integer `max_context_window` and `max_tokens` values take precedence over the model listing; the output budget must also be smaller than the context window. Missing or malformed optional metadata, and invalid optional limits, fall back to valid values in the base listing. Cancelling during this extra request cancels discovery instead of returning a partial success. These fields are **server-reported configuration**, not proof that a full-window request will fit in memory. The reported output setting is not treated as a hard architectural model limit.
+
+The editor labels values as `server` or `user`. Editing a number makes it a user override; discovery refreshes server values while preserving those overrides. Changing the endpoint or model ID clears the previous deployment's reported limits and keeps explicit user overrides. A blank output budget defaults to the smaller of 4,096 tokens or one quarter of the context window. The existing compaction path reserves the output budget inside the context window.
+
+Clearing the output budget explicitly selects that calculated default. Saving
+preserves this choice in both terminal and Desktop settings, so reopening the
+editor and discovering models again does not replace it with a server-reported
+output limit. Models whose output budget has never been edited can still adopt
+the server's reported value.
+
+In Desktop's **Settings → DSCODE models**, **Discover models** immediately merges the returned models into the draft. Existing models keep their order, thinking mode and image-input choice; new models are appended. Reported limits refresh unless you have edited that value, including an output budget you deliberately left blank. Models absent from the response remain in the draft. Choose **Save provider** to persist the changes.
+
+Thinking defaults to the server's behavior. Identified oMLX models also offer Off/On in the editor and Off/On in `/effort` (the stored effort IDs are `off` and `high`). Other custom APIs do not receive guessed reasoning parameters. Native Responses reasoning items and Anthropic thinking signatures are retained for replay to the same service, model and protocol.
+
+## Image input
+
+In the model editor, set **Input → Text and images** only when that model and endpoint support image input. Existing configurations and newly discovered models default to **Text only**; DSCODE does not infer vision support from a model name. Discovery preserves your explicit choice. Changing the base URL, API format or model ID resets the editor's image choice to **Text only**, so enable it again for the new deployment.
+
+In the [experimental Desktop package](browser-use.md#install-the-experimental-combined-desktop-package), open **Settings → DSCODE models**, select the saved provider, enable the model's **Accepts images** checkbox and choose **Save provider**. Select that saved model in the session's model picker. The same explicit capability setting and request-image limits apply in both interfaces. The settings test checks text, streaming and tools; it does not test image understanding.
+
+All three protocols can send user images, browser annotation screenshots and images returned by tools. DSCODE reads their durable attachments and sends image bytes to the configured API: Chat Completions uses `image_url` data URLs, Responses uses `input_image`, and Anthropic Messages uses base64 `image` blocks. Tool screenshots follow their tool result as user image content. Enabling this option does not add vision capability to a text-only server.
+
+Request images preserve aspect ratio within 4,194,304 pixels, with a 1 MiB encoded-byte target per image. The attachment encoder may exceed that per-image target when its smallest output is larger. A request has a 20 MiB aggregate base64 image budget; exceeding it asks the session's image-offload mechanism to omit older occurrences and retry. Original attachments remain in history. Previously offloaded occurrences stay omitted when changing models. A text-only route receives placeholders; enable image input before sending a new screenshot that the model needs to inspect.
+
+## Test and runtime behavior
+
+The model editor's **Test text, streaming and tools** makes three short streamed requests: a fixed text answer, a synthetic tool call, and an answer after a fixed tool result. It never executes a real shell command or other tool. Results name the tested model and distinguish text/streaming, streamed arguments and the tool-result round trip. Starting another test clears the previous report immediately, including when the new request later fails or is cancelled. Tests are local to the current editor and cleared on configuration changes; they do not certify thinking behavior, image input, model quality or long-context operation. The Desktop **Test model** buttons follow the same reporting rules. oMLX probes turn thinking off.
+
+Desktop discovery and model tests offer **Cancel request** while waiting. Cancelling preserves the provider draft and unsaved key, and discards any result that arrives afterward. Closing the settings page also cancels an active discovery or test. Saving and removing providers run to completion and do not offer cancellation.
+
+The default stream idle timeout is 180 seconds to allow cold model loading. Desktop model tests use the same configured idle timeout, without an additional total-duration cutoff; an active stream can run longer while continuing to deliver data. Discovery has a separate ten-second timeout. Each service permits one in-flight inference request per DSCODE Host; queued title and compaction calls yield to queued foreground calls. This is not a machine-wide limit across separate DSCODE processes. Cancellation releases the queue slot and aborts the HTTP request.
+
+Text, structured tool calls and explicitly enabled image input use the same configured service. The local session history is authoritative for all three protocols; Responses requests use stateless replay rather than relying on a remote response ID. Interrupted streams are errors, and invalid tool arguments are rejected before executing the tool. Requests do not redirect or fall back to another model service.
+
+Automatic review follows its configured model route. When that route is Custom, it skips the cloud Jev shortcut. The default web-search router does not fall back to a cloud search service for Custom sessions; configure a separate web search provider explicitly if needed. This does not disable other configured MCPs, browser tools or external integrations.
+
+## Persistence
+
+Service and model configuration lives in `~/.dscode/providers.yaml`; keys use the existing owner-only `~/.dscode/credentials.yaml` store. Provider records contain no key values. Each service receives a stable `custom-…` ID and a derived `DSCODE_CUSTOM_CUSTOM_…_API_KEY` credential reference. An environment variable with that exact reference takes precedence over the saved key, following the existing credential-store rules.
+
+Configuration is shared across projects and installed versions, written atomically, and reloaded by other running Hosts. Stale editors cannot overwrite newer configuration. Renaming a service preserves its ID, so persisted sessions continue to resolve it. Removing a provider removes its route and writable stored credential; it does not reroute existing sessions or delete their history. An environment-supplied key remains in the environment. If it masks a stored key, clear the environment override before removing the provider to remove that stored key too.
+
+## Development verification
+
+The fixture suites exercise all three stream formats, tool-result replay, credential storage, context budgeting, cancellation, native Harness registration, session route restoration and terminal input. Image fixtures run browser annotation admission through the native model registry and durable attachment store to a local HTTP server, checking actual image bytes in all three protocols, text-only projections, durable offloading and cancellation. They use synthetic pixels and scripted responses; they do not establish a live model's visual understanding or complete Desktop UI behavior. An explicit live probe can use an environment key without saving a provider:
+
+```bash
+DSCODE_CUSTOM_BASE_URL=http://studio:8000/v1 \
+DSCODE_CUSTOM_MODEL=your-model-id \
+DSCODE_CUSTOM_KEY_ENV=OMLX_API_KEY \
+node --env-file=.env scripts/verify-custom-provider.mjs
+```
+
+That probe tests all three protocols. It requires the endpoint to serve all three; a failed protocol stays failed in its output.
+
+For multi-step browser tasks with independent outcome checks, run
+`npm run eval:browser -- --provider custom-YOUR-ID --model your-model-id`.
+This uses the saved service, model settings and credential through the same adapter.
+See [Browser use](browser-use.md#measure-multi-step-task-performance) for budgets,
+credential overrides, reports and the distinction between scripted checks and model quality.

package/docs/demo.md

@@ -0,0 +1,76 @@
+# The 90-second demo
+
+Most coding agents work alone. This script shows the three things DSCODE does
+instead — sessions that can see each other, an independent reviewer for code and
+for approvals, and side questions that never disturb the main conversation — in
+an order a stranger can follow.
+
+The recording lands in `assets/demo.gif`; put that image directly under the
+README tagline. Every command below is real, so the demo is reproducible: the
+only unpredictable part is the model's own wording.
+
+## Record it
+
+```sh
+brew install asciinema agg
+cd /path/to/dscode                 # the repo, so the cast can be saved next to it
+asciinema rec demo.cast -i 2       # then run the shot list below; -i trims pauses
+agg demo.cast assets/demo.gif      # renders the cast into the gif the README shows
+```
+
+Checked against **asciinema 3.2.1 + agg 1.9.0**: `rec` writes asciicast v3 by
+default and `agg` reads it, as it does v2 — pass `-f asciicast-v2` if you use an
+older `agg`. `-i 2` (idle time limit) caps every pause at two seconds, which
+keeps the gif close to the 90 seconds you actually plan; recording has to happen
+in a real terminal window, since the command needs the child's pty.
+
+Before you hit record:
+
+- Window at least **120 columns** and a font around 14pt: the footer, the panels
+  and `/btw` all want width. Dark theme (the default).
+- A scratch repository so nothing personal shows up:
+  ```sh
+  mkdir -p ~/demo && cd ~/demo && git init
+  printf 'export const parse = (text: string) => text.split(",")\n' > parser.ts
+  printf 'import { parse } from "./parser"\nconsole.log(parse("a,b,c"))\n' > index.ts
+  git add -A && git commit -m "start"
+  ```
+- Your normal installation and credentials (do not show `dscode doctor` output
+  or full home paths). Any interface language works; the captions below are
+  English.
+
+## Shot list
+
+| Time | Screen | Do this | Say this (captions) |
+|---|---|---|---|
+| 0:00–0:06 | Shell in the scratch repo | `dscode` | "A coding agent in your terminal — macOS, local, one pinned harness." |
+| 0:06–0:22 | TUI, main session | Type `Add a bounds check to parse() in parser.ts and run the tests.` | "It reads the file, edits it, runs the tests." |
+| 0:22–0:36 | Same terminal | `/btw why would the first turn have a cold cache?` — leave the main turn running | "A side question runs in its own read-only child session. The answer never enters the main conversation." |
+| 0:36–0:56 | Second terminal | `dscode sessions` then `dscode send <the other session id> --steer "review the change in parser.ts and reply with what you would change"` | "Two sessions on one machine can find each other, hand work over and answer." |
+| 0:56–1:06 | Back in the first terminal | Show the reply arriving (`/mailbox`, or the agent's `read_session`/`send_session` tools if you asked it to hand the review over itself) | "The answer comes back as a message, not as a new task." |
+| 1:06–1:20 | Same terminal | `/review` | "And the diff can go to an independent reviewer model that never saw this session." |
+| 1:20–1:30 | Closing card | Static title + `npm i -g @toddzheng024/dscode` | "Agents that work as a team. `npm i -g @toddzheng024/dscode`" |
+
+Two beats worth keeping if you have the seconds:
+
+- `/permission auto-review` then `/review-usage`: the approval layer is a model that
+  scores whether **your instruction** authorized the exact action, and the panel
+  shows what that cost. Hard to stage reliably on camera; describe it in the
+  closing card instead if the demo must be shot in one take.
+- `/agents` at the end: the `/btw` child session is a real, read-only session,
+  not a hidden prompt.
+
+## Reproduce it without recording
+
+```sh
+npm i -g @toddzheng024/dscode
+cd ~/demo && dscode                      # terminal 1: the main session
+dscode sessions                          # terminal 2: both session ids
+dscode send <id> --steer "review the change in parser.ts and reply with what you would change"
+dscode read <id>                         # read that session's event page
+dscode watch <id>                        # subscribe to it instead
+```
+
+In the TUI: `/btw <question>` (side question), `/review` (independent review of
+the diff), `/permission auto-review` + `/review-usage` (approval policy and its cost),
+`/agents` (every child session), `/mailbox` (messages between sessions).

package/docs/distribution.md

@@ -0,0 +1,58 @@
+# Distribution and one-command start
+
+The npm + Hub release path is covered in [Hub distribution](hub-distribution.md). The tar installation below is retained.
+
+The deliverable is an installable `dscode-0.7.8.tar.gz`, not just a configured `.dshprofile`. After installing, the user runs `dscode` directly. The npm + Hub installation is available and the tar packages ship through GitHub Releases; a Homebrew formula in the [`qiz029/tap`](https://github.com/qiz029/homebrew-tap) tap installs the same launcher (Homebrew 7 wants `brew trust qiz029/tap` before the first install).
+
+## Publisher
+
+```sh
+npm run dist
+```
+
+It produces three tarballs, all attached to the GitHub release:
+
+| File | Contents | Needed to install |
+|---|---|---|
+| `dscode-<version>-darwin-arm64.tar.gz`, `dscode-<version>-darwin-x64.tar.gz` | Prebuilt package: the source tree + the locked `node_modules` installed for that platform + a `.dscode-prebuilt` marker (about 70 MB) | Node, Git; **no npm and no npm registry access** |
+| `dscode-<version>.tar.gz` | Source package: launcher, preset, dependency manifest and the complete lockfile, without node_modules (about 1 MB) | Node, npm, Git; downloads the locked dependencies from npm at install time |
+
+None of them contains model keys, local override configuration, sessions or research files. The prebuilt package is produced in a staging directory with `npm ci --ignore-scripts --os=darwin --cpu=<arch>` — the same command the installer runs itself, and the native modules are all precompiled optional dependencies selected by `os`/`cpu`, so one runner can build both architectures. `DSCODE_PREBUILT_ARCHS=arm64` builds one architecture only, and an empty string builds the source package alone.
+
+## User
+
+macOS 14+, Node 22.19+ (22.x) or 24+, Git (for `apply_patch`) and Google Chrome are required. npm is needed only when installing from the source package.
+
+The same script can fetch the package by itself: run from a pipe it enters remote mode, resolves the latest release, verifies the publisher's sha256 digest, unpacks, and then hands over to the `install.sh` inside the package, so the downloaded version and the install script's understanding of the layout cannot diverge. It prefers the prebuilt package for the current platform, and the whole installation only reaches GitHub — a corporate npm registry proxy blocking installs does not affect it; when a release has no prebuilt package for the platform it falls back to the source package with a notice, and `DSCODE_INSTALL_SOURCE=1` asks for the source package explicitly. When the packaged `install.sh` sees `.dscode-prebuilt` and `node_modules` it skips `npm ci` and provisions directly with `node scripts/harness.mjs setup`; a marker for a different platform refuses the installation.
+
+```sh
+curl -fsSL https://raw.githubusercontent.com/qiz029/dscode/main/install.sh | sh
+# pin a version
+curl -fsSL https://raw.githubusercontent.com/qiz029/dscode/main/install.sh | sh -s -- 0.7.8
+```
+
+Or unpack the same tarball by hand:
+
+```sh
+mkdir dscode-install
+tar -xzf dscode-0.7.8-darwin-arm64.tar.gz -C dscode-install
+sh dscode-install/install.sh
+cd /path/to/project
+dscode
+```
+
+The default installation goes to `~/.local/share/dscode` with the command linked as `~/.local/bin/dscode`. If that bin directory is not on PATH, add `export PATH="$HOME/.local/bin:$PATH"` to the shell configuration and reopen the terminal.
+
+Enter `/model` once to configure a provider and a model. macOS Computer Use still needs the user to grant Accessibility/Screen Recording permission; those permissions and credentials cannot be distributed with the package.
+
+`dscode --continue`, `dscode --resume SESSION_ID` and `dscode --cwd /path/to/project` are supported. By default it operates on the current terminal directory; state is kept in the installation's `.runtime`. A custom location can be set at install time with the absolute `DSCODE_INSTALL_DIR` and `DSCODE_BIN_DIR`.
+
+Re-running the installer keeps a tar installation current rather than refusing: it reads the installed version, leaves an equal or newer one alone, and hands an older one to that installation's own `dscode update`, which performs the swap with its state migration and backup. A directory that is not a DSCODE installation, or a `dscode` command that belongs to another installation (a source checkout, an npm launcher), is still never overwritten — the installer refuses and names the path it found. Since the version with a self-contained `dscode update`, a tar installation supports self-upgrade: `dscode update [exact version]` downloads the tarball from GitHub Releases, verifies it against the publisher's sha256 digest, migrates `.runtime`, `.env` and the local config, and swaps the directory in place (the `dscode` command path does not change and needs no relinking), keeping the old installation as a sibling backup directory to switch back to or discard by hand. An update requires no running session; when the release has a prebuilt package for the current platform it takes that, so the upgrade needs no npm either, otherwise it takes the source package and downloads the locked dependencies with npm ci. A tar installation older than that has no updater: unpack the new tarball into a new directory and migrate the state by hand once.
+
+## Why not plain npm install -g today
+
+An npm `overrides` entry in the dependencies does not become the resolution rule of a root project when the package is installed as a third-party dependency. This composition needs a single pinned DSH rc line, so it keeps the verified locked dependency graph by using the root manifest inside the install package and `npm ci`. `package.json` already declares the `dscode` bin, but a bare bin declaration is not evidence of npm global-install compatibility.
+
+A one-line `curl | sh` installation is available, reusing the GitHub Releases tarball and the publisher's sha256 digest, and preferring the npm-free prebuilt package; a release without a digest is refused rather than installed unverified. A Homebrew formula ships in the `qiz029/tap` tap: it installs the published launcher tarball into `libexec`, so the pinned dependency graph is npm's rather than the formula's, writes the `.dscode-brew` marker that keeps `dscode update` off the npm pass, and leaves the launcher to `brew upgrade`.
+
+The complete tarball contains `presets/dscode`, `bin/apply_patch` and the version-locked runtime patch scripts. setup enables dscode by default and installs Ultra effort support; the node_modules inside a prebuilt package comes from a fresh install of the lockfile in a staging directory, so the local node_modules is never packed. An old session keeps resuming under its original preset; use `dscode --mode dscode` to create a new session explicitly.

package/docs/dscode-ultra.md

@@ -0,0 +1,75 @@
+# DSCODE preset and Ultra
+
+The interactive TUI is fixed to the `dscode` preset. `/new` starts a DSCODE conversation; the preset picker is absent from slash completion and help. Typing `/mode` reports that the preset is fixed, and `/new <other-preset>` or `--mode <other-preset>` is refused. The hidden compatibility flag `--mode dscode` still works. Resuming an older conversation mounts DSCODE while preserving its transcript and recording the new effective preset; the original session header is retained. Model, reasoning effort, permissions and plan mode keep their separate controls.
+
+## Execution through a persistent shell
+
+The preset combines the pinned minimal preset's owner-scoped persistent shell with project instructions, runtime context, Skills, plan/Todo/Goal, compaction and subagents from standard. It does not copy minimal's fixed complete system prompt or its lack of compaction. Host MCP, Computer Use, hooks and auto review remain mounted. Skill and instruction discovery — including the ancestor mode — is described in [Skills](skills.md).
+
+The preset also registers a `review` tool and `/review` command backed by one independent, read-only model request over the selected Git diff. The main agent is guided to call it after code changes and focused checks, before its final reply. This is a diff-only review, not a tool-using subagent or a substitute for tests; it does not change Ultra delegation policy. See [TUI review usage](tui-commands.md).
+
+The model uses `bash` for file reads, searches and edits instead of separate `read`, `write`, `edit`, `glob` and `grep` tools. `cd`, exports, functions and background jobs persist across calls for the same agent. Each child gets a separate shell. By default children share workspace files; the parent can explicitly set `worktree: true` on `subagent` or `subagent_fork` to give a child an isolated Git checkout.
+
+`apply_patch` is available in the harness shell PATH and wraps `git apply`. Feed it a **standard unified diff**, not the Codex `*** Begin Patch` format. Git is required. `apply_patch --check` checks hunks without writing. This works outside a Git repository too.
+
+```sh
+apply_patch <<'PATCH'
+diff --git a/example.txt b/example.txt
+--- a/example.txt
++++ b/example.txt
+@@ -1 +1 @@
+-before
++after
+PATCH
+```
+
+`/shell` lists the current session's terminals. `/shell reset` closes them while the agent is idle. Timeout, cancellation, `exit`, reset and host restart discard shell state; the next call starts at the session workspace. Conversation resume restores messages and files, **not** an OS process or its exports. Interactive foreground programs that require stdin are not supported by this tool. Background work can use shell job control; `shell_retry` also exposes the existing tracked background-job mechanism.
+
+Normal persistent commands keep the active OS sandbox and do not each incur an LLM review. After a genuine sandbox denial, the model may use `shell_retry` for a single fresh-shell retry, with explicit `workdir`, wider `sandbox_permissions` and justification. This uses the original escalation approval seam and auto reviewer. Reviewer input resolves relative workdir against the session workspace and explicitly identifies the environment as fresh. It cannot see or rely on the persistent shell's exports/functions. Rejected approval prevents execution. Sandbox mode changes while persistent terminals exist are rejected upstream; close them with `/shell reset` first when changing permission modes that also change sandbox policy.
+
+Hooks which should cover both execution paths should match `^(bash|shell_retry)$`.
+
+## Ultra effort
+
+In the DeepSeek native route, `/effort` replaces the bottom composer with a Low → High → Max → Ultra bar (arrow keys to move, Enter to apply, Esc to cancel, `o` for Off). Focusing Ultra triggers a blue wave that spreads from the center before confirmation. After applying Ultra, the composer briefly shows a second center-out text-and-border ripple. Both effects are skipped when animations are disabled. Ultra is a harness policy, not a new DeepSeek API value:
+
+- Session selection and request headers retain `ultra`; the native adapter serializes it as `thinking.type: enabled` and `reasoning_effort: max`.
+- Normal tool-capable requests get collaboration guidance appended to the effective system message at the adapter boundary. The immutable logged request is not mutated. This extra text is reflected in provider usage; preflight local token estimates do not include the adapter-added text.
+- The guidance actively seeks independent useful subtasks, disjoint file ownership and independent review, while avoiding delegation for trivial work. The main agent integrates and verifies results.
+- Children inherit the effort when no model/effort override is selected. Ultra stays in the persisted request header across compaction and the TUI's standard restore path; switching effort to Max removes the extra guidance on subsequent requests. Switching to a different provider uses that provider's own effort catalog.
+- In dscode, a parent can run at most five direct children concurrently below Ultra and twenty at Ultra, judged by the parent's effort when it launches or wakes a child; admission reservations prevent concurrent launches from racing past the cap. Idle-child wake requests also count. The preset allows one delegation level, including non-Ultra sessions. Parent/child messaging remains available; direct sibling messaging is not added.
+- Every child gets a parent-chosen `name`: 1 to 10 characters, letters, digits and underscores only, starting and ending with a letter, unique among the parent's live, resumable and starting children. The child appears as `/name · description` in the TUI agents line and `/agents`, and the parent addresses it as `/name` in `send_message` and `interrupt_agent`; a child addresses its parent as `/`. Continuable child names resolve from the parent's saved catalog after a Host restart, and sending to one resumes that same child. Lookup alone does not wake it. A disposed foreground child cannot be resumed by name. Session ids keep working as before.
+- Prefer `subagent_fork` when completed conversation history helps the child; use fresh `subagent` for self-contained work that gains nothing from that history. Fork excludes the unfinished turn, so the child's assignment must still state its objective and constraints. Both child paths hide delegation tools, and runtime checks reject a child that tries to delegate again.
+- Worktree choice is independent of conversation forking. `worktree: true` creates a detached checkout under `.dscode-worktrees/<id>/` at the parent repository root, starting from `HEAD`. It requires the parent session cwd to be that Git root and the parent worktree to be clean, including untracked files. A dirty parent is rejected before creating a child, so a child never silently misses uncommitted parent changes. Omit the flag for read-only tasks or when the child needs those changes; choose it for independent parallel edits. The child session persists its own cwd; the parent receives the path in the tool result and must inspect and integrate the diff. The checkout remains available for later messages to an idle child; remove it with `git worktree remove PATH` only when no child follow-up or resume is expected. Removing it earlier makes that child's future file work fail. Worktrees with edits are retained on child failure, while an empty checkout is removed if child startup fails. The directory is added to local `.git/info/exclude` so it does not appear as an untracked parent change.
+- Every effort can start or wake child agents, so models without a `max` level (which never offer Ultra) can delegate too. Below Ultra there is no collaboration policy; the shell policy makes delegation the exception instead: the agent works itself by default, delegates only a substantial independent part or a broad read-only investigation, runs at most one child at a time and picks the lowest child effort the model offers. This is prompt guidance; the runtime enforces only the five-child cap and the single delegation level. `workflow` and `ralph` are unavailable in this preset because they can start children outside the admission cap.
+- Compaction/title requests do not get the collaboration instruction. Auto review does not inherit the main agent's Ultra selection. Permissions are unchanged.
+
+Use Ultra for complex changes with independent investigation/implementation/review opportunities. It is not the default and can cost more tokens because children make additional model requests. `/agents` shows their activity; `/status` and `/review-usage` expose the existing recorded usage surfaces. The native root token totals are not a complete bill for child sessions. The session footer separately aggregates recorded descendant calls; see [session metrics](session-metrics.md).
+
+Normal `deepseek-flash` agent requests also receive a short task-proportional instruction: answer simple questions directly; for bounded code changes, make the focused change, run the relevant check, and stop when it passes. This is guidance rather than a hard reasoning-token limit. Internal compaction and other non-agent calls do not receive it.
+
+## Delegate mode
+
+`/delegate <task>` asks the main agent to coordinate the task instead of doing it. The command only checks that the session starts at a clean Git repository root and then queues the task with a fixed coordinator protocol as the agent's next turn; planning, dispatch, verification and merging are the model following that protocol, while the runtime enforces the child cap and keeps the board. It works at every effort and overrides the below-Ultra one-child guidance for that task.
+
+The main agent first plans the parts on a delegate board with the `delegate_board` tool: each task gets a title, the child name it will run under, its owned files, a priority (`high`, `normal` or `low`) and the tasks it depends on — only those whose changes it must build on. The board rejects dependency cycles. A pending task is ready once every dependency is complete, and blocked until then; the runtime refuses to launch a blocked task. Ready tasks are ordered by effective priority, which is a task's own priority or that of any open task waiting on it, whichever is higher, so work that unblocks a high-priority task goes first. The main agent launches ready tasks in that order, in the background with `worktree: true`, while child slots are free — five below Ultra, twenty at Ultra — and launches the next ones as children settle. Launching a child under a task's planned name moves the task to running. `delegate_board update` re-plans a pending task's priority or dependencies, and dropping a task releases the tasks that waited on it. Whenever the board changes, the main agent receives its state and the number of free slots as a message ahead of its next step, so a free slot with pending work is always in view. The state is not placed in the system prompt, because rewriting the prompt on every change would invalidate the provider's prompt cache for the whole conversation; the terminal hides these board messages, and `/delegate` itself appears as one line.
+
+Children work only in their own worktree and leave their changes uncommitted. A task with dependencies starts from their verified changes: its child applies each dependency's diff from the worktree path the board recorded, then commits the result as a baseline on its worktree's detached HEAD. That commit never reaches a branch; it keeps the child's own diff separate from its dependencies' changes. A child that is blocked sends its question to `/` and waits; its task stays in running, marked as waiting, until the main agent answers with `send_message`. Once a child settles, its task shows as verifying. The main agent verifies tasks that others depend on first, since they gate further work. It reviews the worktree and reruns its checks there, then records the task as complete with the evidence, sends the child fixes, or reopens the task. A task cannot be completed before its child was launched, and the tool requires the verification evidence.
+
+Merging waits until every task is complete or dropped, because a new worktree needs a clean main workspace. Complete tasks are then merged in dependency order, each dependency before the tasks built on it, so a task with a baseline contributes only its own changes. Each is merged with `git -C <worktree> add -A && git -C <worktree> diff --cached --binary | git apply --3way`, which stages the result; nothing is committed, branched or pushed unless you ask. The final reply lists each task's outcome and the checks run in the main workspace.
+
+`/delegate-dashboard` opens the board as a kanban with pending, running, verifying and complete columns. Running and verifying are read from the children's live status, not from what the model last reported, so the board cannot claim a child is working after it stopped. Boards are kept per session under `$DSH_HOME/delegate-boards/` and survive a restart; `delegate_board clear` empties one.
+
+## Implementation and checks
+
+`presets/dscode/agent.cordis.yml` is the checked-in composition template. Setup renders it as one `@deepseek-ai/dsh-agent-preset` declaration row at the end of the profile patch, with its plugin paths resolved; DSH 0.1.7's preset registry reads declaration rows and no longer discovers presets from a directory. The launcher performs idempotent, version-checked patches to the pinned native DeepSeek adapter (Ultra), bash tool (separate name for retry), persistent shell (reset cache invalidation), and DSH-Code TUI (existing `/clear`/command discovery fixes). Unsupported upstream package versions or source shapes fail setup. These changes are included in the full tar distribution; the Hub-only configuration export does not include them.
+
+Tests cover real serialized DeepSeek requests with mocked HTTP, concurrent admission reservations, persistent cwd/exports, unified-diff file editing, fresh retry isolation, approval denial, cancellation/reset, actual child shell isolation, deterministic manual compaction and TUI-equivalent Ultra restoration. The actual terminal picker was also checked for Ultra and the default dscode mode. These are local deterministic checks, not a paid DeepSeek quality or multi-agent performance benchmark.
+
+### Task-proportional execution
+
+Ultra keeps native `max` reasoning but now explicitly routes bounded work (such as one unit test) through direct implementation and focused verification. It avoids unnecessary planning, child agents, broad repository scans and repeated review. Expand scope only for a concrete uncertainty or failure; stop when acceptance criteria and required checks pass. This is prompt guidance, not a runtime deadline or adaptive reasoning-effort switch. It has not yet been benchmarked against the reported slow session, and cannot guarantee shorter model deliberation.
+
+### Per-child reasoning effort
+
+The parent can pass `reasoning_effort` to `subagent` or `subagent_fork`, independently of the model-selection opt-in. For example: `{"name":"unit_tests","description":"Add focused unit tests","prompt":"...","reasoning_effort":"low"}`. Omission keeps existing inheritance. The selected child model validates the effort before child creation; unsupported values fail instead of silently falling back. Effort-only selection does not change provider/model or the parent's effort. Explicit provider/model overrides still require the existing model-selection policy. Ultra guidance asks parents to choose low for bounded work, high for difficult work and max only when justified. This configures newly created children, not existing children sent another message.