@toddzheng024/dscode-desktop 0.0.0-stage → 0.7.33

package/docs/triggers.md

@@ -0,0 +1,338 @@
+# Triggers: running the agent from an event
+
+One event starts one run. By default each run starts a fresh session; a persistent trigger resumes its own session across runs. A trigger definition says where the event comes from, which folder the session works in, what it is asked to do, and the limits that keep an unattended run bounded.
+
+A trigger is not a way to reach a session that is already open: that is [session communication](session-communication.md) (`dscode send`, the mailbox). A persistent trigger owns its session binding; it does not attach to an arbitrary open conversation. Each run ends independently, while its session history remains durable.
+
+## Experimental Desktop scheduling
+
+The [combined Desktop package](browser-use.md#install-the-experimental-combined-desktop-package)
+adds **Settings → DSCODE schedules**. Open a DSCODE session in the target project,
+then select that session in the settings page. The form creates or edits an
+interval, calendar, external-event or script task. New form entries default to
+read-only execution and a persistent task-owned session. You can pause a task,
+queue one manual run, cancel a pending job, and start, stop or restart a script
+source and inspect its output. Recent job states refresh while the page is open.
+The same four agent tools and `/trigger` commands remain available inside DSCODE
+sessions, with the workspace and mutation restrictions described below.
+
+Background refresh preserves form errors and unsaved entries. A refresh failure
+appears separately and clears after a successful refresh. Source output clears
+when you select another session or the selected session closes.
+Polling keeps the form editable. An action submitted during a refresh waits for
+that refresh to finish and then runs once, even if the refresh failed. A failed
+action focuses its error message so it is visible after submitting a long form;
+background refresh does not move focus.
+
+If a manual run cannot be confirmed, its button changes to **Retry**. While the
+settings page remains mounted, retries reuse the same request for that workspace
+and task, including when queuing succeeded but refreshing the result failed.
+Running another task or selecting another workspace does not discard that
+request. Closing and reopening the page discards this retry state; inspect
+**Recent jobs** before submitting another run after reopening it.
+
+Delivery is off by default. **Enable delivery and resume on launch** starts the
+Desktop queue owner for every registered project in this state directory and
+saves that choice in `<state>/config/desktop-scheduler.json`. Later Desktop
+launches start it after the Host's providers and preset hooks are ready.
+**Stop delivery and disable resume** cancels active trigger runs, drains script
+sources and disables automatic startup. Pending jobs and task definitions stay
+saved. A paused definition does not consume its pending jobs.
+
+Desktop uses `/trigger scheduler status|start|stop` and the corresponding
+`trigger_scheduler` actions. It does not install a launchd service. Another
+process may already own the same queue; the page reports that owner and cannot
+stop it. Use the terminal or service manager that started it. A native background
+job cancellation stops the current Desktop owner but retains the saved launch
+preference; use the settings stop action to disable that preference too.
+
+Keep Desktop running for delivery. Its quit and update inspection counts an
+enabled scheduler as active work, including time between task runs. A graceful
+quit drains its owned work while keeping the saved preference. After a crash,
+unclaimed jobs can resume on the next enabled launch; a task already running at
+the crash is recorded as interrupted and is not automatically executed again.
+Removing the package stops its owner and retains the saved data. Reinstallation
+can resume delivery if the saved preference is enabled, so disable delivery
+before removal when you do not want that behavior.
+
+Desktop runs require the DSCODE preset and `read-only` or `workspace-write`
+permission. Plan mode, read-only management sessions, unattended runs and
+subagents cannot change schedules through the agent tools or session-bound
+settings controls. The global delivery buttons are explicit user settings.
+An unattended task also cannot stop the shared scheduler through `job_kill`.
+Events do not grant authority, and required approvals stop unattended execution.
+
+This remains an unpublished integration. The queue and shutdown path have been
+qualified against two independent Host versions and the signed macOS Desktop
+Host. Component tests, shared Web-client interaction and the signed macOS
+Electron settings cover task creation, editing, manual queuing, cancellation and
+delivery controls. Windows source execution still requires qualification.
+The updated package passed native macOS installation, upgrade, removal and
+reinstallation with delivery enabled: its preference, definition and pending job
+survived, and enabled delivery resumed after upgrade and reinstallation.
+Scripted model fixtures establish
+delivery and cleanup, not live-model task quality.
+
+## Define a trigger
+
+| Where | Who reads it |
+| --- | --- |
+| `<state>/triggers/<id>.yml` or `.json` | this machine |
+| `<project>/.dsh/triggers/<id>.yml` or `.json` | this project, reviewed with it |
+
+The file name must equal the `id`, and a project file wins over a machine file with the same id. An unreadable file is reported by `dscode trigger list` without hiding the others.
+
+```yaml
+id: nightly-review
+workspace: /Users/me/work/repo        # absolute; the session binds here
+prompt: review the diff and fix what is broken
+source: { kind: calendar, cron: "0 9 * * *" }
+session: { mode: new }               # new (default), or persistent
+goal: { objective: the diff is reviewed and the tests pass, maxRounds: 12 }
+limits: { timeoutSeconds: 1800, maxRunsPerDay: 4, minIntervalSeconds: 300 }
+```
+
+| Field | Meaning |
+| --- | --- |
+| `id` | identity, also the file name and the spool/log key |
+| `enabled` | `false` prevents execution; manual runs skip, scheduled jobs remain pending (default `true`) |
+| `source` | what produces the event, see below |
+| `workspace` | the session's folder; chosen here and never changed by a run |
+| `prompt` | what the session is asked to do; `{{event.text}}`, `{{event.title}}`, `{{event.source}}`, `{{event.eventId}}` and `{{event.fields.NAME}}` are substituted, and an event whose text the template never mentions is appended |
+| `session.mode` | `new` (default): a fresh session for every run; `persistent`: create once, then resume the same session |
+| `preset` | agent preset (default `dscode`) |
+| `permission` | `auto-review`, `workspace-write` (default), `read-only` or `danger-full-access` — `ask` is refused, because nobody is there to answer |
+| `model`, `effort` | optional route and reasoning level for the run |
+| `goal` | the objective plus `maxRounds`: the run continues toward it and stops when it is reached or the rounds are spent |
+| `limits` | `timeoutSeconds` (1800), `maxRunsPerDay` (24), `minIntervalSeconds` (60), optional `maxCostUsd` |
+| `overlap` | `skip` for `new`, `queue` for `persistent`; defaults follow the session mode, and conflicting values are refused |
+| `notify` | `log` (the only value) |
+
+Unknown or misspelled fields are refused rather than ignored, so a typo like `maxRound` cannot fall back to the default cap.
+
+## Ask DSCODE to manage schedules
+
+The agent has four tools over the same definition files and SQLite jobs used by the CLI:
+
+| Tool | Actions |
+| --- | --- |
+| `trigger_manage` | `list`, `get`, `create`, `update`, `enable`, `disable`, `register`, `unregister` |
+| `trigger_jobs` | `schedule`, `list`, `cancel` |
+| `trigger_source` | `status`, `start`, `stop`, `restart`, `logs` |
+| `trigger_scheduler` | Terminal: `status`, `install`; experimental Desktop: `status`, `start`, `stop` |
+
+For example, ask “Check this project's build every weekday at 9 am in America/Los_Angeles” or “Run this trigger once in 30 minutes.” The agent creates a project-local definition with `trigger_manage`, then uses `trigger_jobs` for a one-shot event. Creating or updating a `calendar` or `interval` definition also registers its cadence. A `script` definition registers a supervised producer. An `external` definition has no recurring schedule. `update` merges top-level fields; a supplied nested object, such as `limits`, replaces that entire object and omitted fields inside it receive their normal defaults. Both `new` and `persistent` session modes are supported.
+
+A delay call supplies an existing `trigger_id`, exactly one of `after` (`30m`) or `at` (an ISO timestamp with a UTC offset), and an `idempotency_key`. Retrying the same key and request returns the original job and original due time, including after cancellation or completion. Reusing that key for a different request is refused. Keys are scoped to the workspace. `list` returns up to 100 jobs (50 by default), newest due time first, including terminal states.
+
+The tools bind definitions and job management to the current session's workspace. They create or edit project-local definitions only; machine-level definitions in that workspace can be inspected and scheduled without rewriting their files. Agent-managed execution uses the `dscode` preset with `read-only` or `workspace-write` permission. Mutations go through the existing tool approval pipeline, including automatic review when enabled. Plan mode, read-only sessions, subagents and unattended trigger runs cannot mutate schedules through these tools.
+
+Every scheduling response reports `scheduler.running`. A saved job does not by itself start the scheduler. On macOS, `trigger_scheduler` with `action: install` installs the shared launchd service, which can deliver due jobs from every registered project in that state directory. Other platforms receive instructions for their service manager. Service installation acknowledgement and observed liveness are reported separately. These tools do not stop the shared service; use the CLI for that machine-wide operation.
+
+Disabling a trigger leaves its pending jobs waiting. `unregister` cancels pending recurring jobs from that registration while leaving one-shot jobs intact. `cancel` cancels one pending job and never interrupts a running job. No completion notification is sent yet; inspect the jobs and run log for results.
+
+## Choose a session mode
+
+```yaml
+id: project-monitor
+workspace: /Users/me/work/repo
+source: { kind: external }
+session: { mode: persistent }
+prompt: "Review this event using the previous findings: {{event.text}}"
+goal: { objective: this event has been investigated, maxRounds: 12 }
+```
+
+`new` isolates each event's context. `persistent` creates a session on its first run and stores the binding in `<state>/triggers/sessions/<id>.json`; later runs resume that session through the ordinary session persistence service, including after a CLI or machine restart. Each event still has a distinct run id, a fresh goal, its own round cap and its own cost cap. An earlier blocked, paused or unfinished goal is cleared through the goal service before the new goal is created; its history and run result remain available. This is a new attempt for the new event, not an automatic retry of the old one.
+
+A persistent trigger's workspace and agent preset must continue to match its binding. Use a new trigger id to start a different workspace or preset. A missing or unreadable bound session is an error; it never silently becomes an empty conversation. Switching to `new` leaves the old binding alone, so switching back to `persistent` resumes the earlier persistent session.
+
+Persistent runs process queued events oldest first. Concurrent `fire` or scheduled `run` invocations persist their events and wait for the trigger's execution lock; the active command drains arrivals after the current run. The command stays alive while draining, waiting for `minIntervalSeconds` between runs. Reaching the daily cap, disabling the trigger, or losing the runner leaves pending events on disk for a later `run`. Direct `fire` events and legacy spool files still need a `run` invocation after every waiting process exits. `emit` commits a job to the shared scheduler queue; it returns without waiting for the model. A run stopped by interruption leaves subsequent events pending.
+
+The lock is shared across CLI processes and inherited by the Host, so killing a parent cannot start a second writer while its Host is still alive. The ordinary session persistence lock also refuses to resume a session already open for writing in another Host (including the TUI).
+
+## Sources
+
+| `source.kind` | Fields | What fires a run |
+| --- | --- | --- |
+| `interval` | `seconds` | the schedule, every N seconds |
+| `calendar` | `cron` (five numeric fields), optional `timezone`, `misfire` | the schedule, on the cron rule |
+| `watch` | `paths` | a change to one of those paths |
+| `poll` | `everySeconds`, `check` | the schedule, but only when `check` exits 0 |
+| `script` | `mode`, `command`; poll also requires `everySeconds` | a sandboxed script submits explicit events |
+| `external` | — | only what someone posts with `dscode trigger emit` |
+
+A legacy `poll` check runs in a filesystem sandbox in the workspace with a 60-second limit; anything other than exit 0 — including a timeout or a check that cannot start — means there is nothing to do. Its output is kept in the run's tail. It never falls back to an unsandboxed shell when sandbox setup fails.
+
+## Post an event
+
+```sh
+dscode trigger emit nightly-review --text "the build failed"
+dscode trigger emit nightly-review --event event.json     # or "-" for stdin
+dscode trigger fire nightly-review --text "do it now"     # post and run
+```
+
+An event body may carry only `source`, `title`, `text` and scalar `fields`; any other key is refused, because an event is data and must never name a permission, a session or a tool. Pass a stable `--event-id` when a producer may retry. `emit` commits the event and its job atomically in SQLite before returning success. Repeating the same event id and payload returns the original job, even after completion or cancellation; changing the payload under that id is refused. At most 100 pending/running jobs per project and trigger may be admitted through `emit`. `QUEUE_FULL` means no new event was accepted: retry later with the same id. Event text is limited to 64,000 bytes and the complete normalized body to 128 KiB. Tasks with external side effects should also use `eventId` for their own idempotency.
+
+`fire` retains its direct, synchronous spool path. Legacy spool files are not automatically migrated into the scheduler queue. An interrupted direct spool run can be replayed if its result was never recorded.
+
+## Run one
+
+```sh
+dscode trigger run nightly-review     # decide, then run if the limits allow
+dscode trigger list                   # definitions and each one's last outcome
+dscode trigger show nightly-review    # one definition in full
+dscode trigger log nightly-review     # recorded runs, newest first
+dscode trigger log --failed           # only what did not complete
+dscode trigger events nightly-review  # queued events and legacy spool entries
+```
+
+Before a session starts, `run` refuses: a disabled definition, a workspace that does not exist, an event id already recorded, a spent 24-hour cap, a run inside `minIntervalSeconds`, or a run that is still in flight. A refusal is recorded as `skipped` with its reason and exits 0; it never counts against the cap or the interval.
+
+| Exit code | Meaning |
+| --- | --- |
+| 0 | completed, or skipped with a reason |
+| 1 | the run failed |
+| 2 | a cap stopped it (rounds or cost) |
+| 3 | the goal is blocked or paused |
+| 124 | the timeout stopped it |
+| 130 | it was interrupted |
+
+## What one run is
+
+A fresh or resumed session in the definition's `workspace` — the same folder binding the terminal uses, so the session's shell and log stay there. The goal is created through the goal service (the model-facing goal tools require a direct human turn, which an unattended run never has), the prompt is delivered, and the goal round driver continues the work turn after turn until:
+
+- the goal is complete (exit 0) or blocked (exit 3);
+- the round cap or `maxCostUsd` is reached (exit 2);
+- `timeoutSeconds` passes (exit 124);
+- the goal is paused (exit 3);
+- an approval is needed: it is rejected, because no human is present, and the run is marked `approval_required` when a cap or the timeout then stops it (fail closed).
+
+Cost is the spend added by this run, rather than the persistent session's lifetime spend. The outcome, reason, exit code, session id, cost and rounds go to `<state>/triggers/runs.jsonl`, and the agent's last message to `<state>/triggers/logs/<id>/<runId>.log`. The session itself is durable: it appears in `dscode sessions` and `/resume`.
+
+## Schedule recurring work
+
+```yaml
+source:
+  kind: calendar
+  cron: "0 9 * * 1-5"
+  timezone: America/Los_Angeles
+  misfire: run-once
+```
+
+Cron uses five numeric fields and accepts `*`, lists, ranges and steps, such as `*/15 9-17 * * 1-5`. `timezone` accepts an IANA time zone and defaults to the machine's current time zone. Calendar iteration uses the pinned [cron-parser](https://github.com/harrisiirak/cron-parser) dependency, including its daylight-saving behavior. A cron expression or time zone that cannot be evaluated is rejected before installation.
+
+```sh
+dscode trigger install nightly-review
+dscode trigger uninstall nightly-review
+```
+
+For `calendar`, `interval`, `poll` and `script`, `install` registers the recurring source with the shared scheduler and installs its launchd service on macOS. Reinstalling the same source preserves its cursor. Editing a registered source, or re-enabling it, resets its next firing from the time the scheduler observes the change. A disabled or missing definition generates no new occurrences. `uninstall` removes the recurring registration and cancels its pending recurring jobs; separately scheduled delay jobs remain. It leaves the shared scheduler running for other triggers.
+
+`watch` continues to use its own launchd `WatchPaths` agent. An `external` source has no recurring schedule: emit events or schedule individual jobs for it. Reinstalling a previously installed recurring trigger removes its old per-trigger launchd registration before using the shared scheduler.
+
+When the machine wakes or the scheduler restarts, `misfire: run-once` (the default) merges missed cron occurrences into one job for the latest missed instant. `misfire: skip` drops missed instants older than the current minute. A firing in the current minute is still eligible. Intervals and polls merge missed occurrences into one job. There is no replay of every missed tick.
+
+## Schedule one event
+
+```sh
+dscode trigger schedule nightly-review --after 30m --text "check the build again"
+dscode trigger schedule nightly-review --at "2026-09-23T09:00:00-07:00" --event event.json
+dscode trigger jobs nightly-review
+dscode trigger cancel job-REPLACE-WITH-RETURNED-ID
+```
+
+`schedule` takes exactly one of `--after` (`s`, `m`, `h`, `d`) or `--at` (a future ISO timestamp with seconds and an explicit UTC offset). The event has the same data-only payload as `emit`; it cannot select a session, workspace or permission. The command returns a durable `jobId` immediately without starting an agent. `cancel` applies only to a pending job and never interrupts a run already claimed by a worker.
+
+Jobs are stored in `<state>/triggers/jobs.sqlite`, independently of the producer process. A delay that becomes due while the machine is asleep runs after the scheduler is available again. Due time means eligible to run: overlap, minimum intervals, daily caps and disabled definitions keep a job pending with its waiting reason shown by `jobs`. Due jobs for one trigger execute oldest first in either session mode. Jobs keep their original workspace; a changed workspace holds them with `workspace_changed` until cancelled and rescheduled.
+
+Each job has its own `jobId`; when claimed, it also has a `runId` and uses `job:<jobId>` as its event identity for cron/delay jobs; emitted jobs keep the producer's original event id. The run record carries the job id and session id. Job states are `pending`, `running`, `completed`, `failed` and `cancelled`. A false poll predicate completes the job with `no_match` without starting an agent. Failed jobs are not automatically retried. If a worker dies, the scheduler waits for any surviving Host to release its lock, then uses the run record to settle the job or marks it `failed (interrupted)` when no result survived. It never assumes an interrupted job had no external effects.
+
+## Script producers and loops
+
+Use `script` when an agent needs to write a custom detector, poll an API, or maintain a subscription. The script does cheap detection work; an emitted event starts the usual bounded agent run. Save scripts in the project so their code can be inspected alongside the trigger definition.
+
+```yaml
+source:
+  kind: script
+  mode: daemon
+  command: ["python3", ".dsh/scripts/watch_build.py"]
+  permission: read-only
+```
+
+`command` is an argv array, with no implicit shell. Relative script paths resolve from the trigger's workspace. `daemon` owns its loop and runs until stopped. For a finite check, use `mode: poll`, `everySeconds: 60`, and optionally `timeoutSeconds: 30` (default 60). A successful poll waits its interval after exit; it creates no model job unless it emits an event. Unexpected daemon exits and failed/timed-out polls restart with exponential backoff from 2 seconds up to 5 minutes. Missed polls are not replayed.
+
+Within either script mode:
+
+```sh
+dscode trigger emit build-monitor --event-id "build:123:failed" --text "Build 123 failed"
+```
+
+The private `dscode` command provided on the script's PATH supports only `trigger emit`, with `--text` or `--event FILE` (`-` reads JSON from stdin). It returns a JSON receipt containing `jobId`, `state` and `eventId`. A nonzero exit means the producer must retry the same event rather than advance its cursor. Store cursors under the writable directory named by `DSCODE_SOURCE_STATE`; it survives process restarts. `TMPDIR` is a separate temporary directory removed after each attempt. `DSCODE_TRIGGER_ID` names the bound trigger. The local ingress accepts only that trigger and validates the event before acknowledging its durable commit.
+
+The script's filesystem permission is independent of the agent run's permission. It defaults to `read-only`, with writes allowed only in its private state and temporary directories. `source.permission: workspace-write` also permits workspace writes while excluding the DSCODE state directory. Scripts inherit the scheduler's environment and network access; this is a filesystem write boundary, not credential or network isolation. macOS uses Seatbelt, Linux requires bubblewrap, and other platforms refuse execution. Sandbox setup failures never run the script unrestricted. The legacy `poll.check` shell predicate now uses the same sandbox launcher.
+
+```sh
+dscode trigger install build-monitor          # register and install shared scheduler
+dscode trigger source build-monitor status
+dscode trigger source build-monitor logs      # last 32,768 characters
+dscode trigger source build-monitor stop
+dscode trigger source build-monitor start
+dscode trigger source build-monitor restart
+```
+
+The agent uses `trigger_manage` to create/update the definition and `trigger_source` for these lifecycle actions. Saving a definition registers it; process startup still requires the shared scheduler. A stop persists until an explicit start/restart. Disabling a definition stops its producer, and re-enabling it resumes a producer whose desired state is running. Editing the command or source settings restarts the process; after editing script contents alone, use `restart`. Stop/unregister leave already accepted event jobs intact; cancel those separately when needed. Status distinguishes desired state, the observed process, next attempt, and the last error. Output tails are bounded; they are not a full log archive.
+
+Each source has a singleton lock. The scheduler starts a guardian that terminates the script process group on stop or loss of its scheduler IPC connection, escalating to `SIGKILL` after a short grace period. The script inherits the lock so a surviving process cannot overlap a replacement. Deliberately detached processes that create another process group are outside this cleanup guarantee. If the guardian itself is forcibly killed and a script survives with the lock, a replacement reports the held lease rather than starting a duplicate; inspect and terminate that orphan before restarting. Source supervision requires the scheduler service, so it can continue after the TUI closes but cannot run while the machine is asleep or powered off.
+
+## Run the scheduler
+
+```sh
+dscode trigger scheduler install     # macOS: start now and at future logins
+dscode trigger scheduler status
+dscode trigger scheduler start       # foreground, also usable under another service manager
+dscode trigger scheduler tick        # one scan; wait for the workers it starts
+dscode trigger scheduler uninstall   # remove the service; retain jobs and registrations
+```
+
+One scheduler owns each state directory. It scans roughly once per second, launches at most four workers concurrently and never runs model work itself. Each worker uses the ordinary trigger execution path, with a fresh or persistent session according to the definition. It also supervises up to 16 script processes, independently of the four model workers. Ordinary `emit` events use the same durable job queue. `scheduler tick` only scans jobs; use the long-running scheduler to supervise scripts.
+
+The macOS service is written to `~/Library/LaunchAgents/ai.dscode.scheduler.<state-hash>.plist` with an explicit Node executable, state directory and PATH. launchd restarts it after exit and starts it at login; jobs do not run while the machine is powered off. On other platforms, `install` prints the foreground command for your service manager. `scheduler.log` and per-job worker output under `<state>/triggers/jobs/<jobId>.log` explain startup failures. Updating or moving the Node/DSCODE executable requires updating and restarting the service (`scheduler uninstall`, then `scheduler install`).
+
+## In the terminal
+
+`/trigger` opens a text overview of this workspace's definitions, source registrations and scheduler status. `/triggers` is a compatible alias with the same management commands. Use `/trigger help` for the complete syntax.
+
+```text
+/trigger
+/trigger new build-monitor
+/trigger show build-monitor
+/trigger enable build-monitor
+/trigger disable build-monitor
+/trigger run build-monitor Check the latest build
+/trigger schedule build-monitor 30m Check again after deployment
+/trigger jobs build-monitor
+/trigger cancel <jobId>
+/trigger source build-monitor status
+/trigger source build-monitor restart
+/trigger source build-monitor logs
+/trigger scheduler status
+/trigger scheduler install
+```
+
+`new` creates a disabled, project-local `external` starter. Configure its prompt, goal and source before enabling it, either by asking the agent or by supplying JSON fields directly:
+
+```text
+/trigger update build-monitor {"prompt":"Review recent build failures","goal":{"objective":"Report the failures and suggested fixes"},"source":{"kind":"calendar","cron":"0 9 * * 1-5","timezone":"America/Los_Angeles"}}
+/trigger enable build-monitor
+```
+
+`create <id> <JSON>` creates a fully specified definition, and `update` uses the same top-level merge semantics as `trigger_manage`. `register` and `unregister` control recurring registration separately from the enabled flag. `schedule` accepts a duration (`30s`, `10m`, `2h`, `1d`) or an ISO timestamp with an explicit offset; the remainder of the line is literal event text and needs no shell quoting. `run` queues an event immediately and returns its job id. Both use the shared scheduler and report when it is stopped; neither launches a blocking agent run inside the TUI. `jobs` displays up to 100 workspace jobs. `runs` shows recent outcomes, and `events` shows durable emitted events and legacy spool entries.
+
+These are direct user commands and do not invoke the model or its tool-approval flow. Mutations retain the same writable-session, plan-mode, unattended/subagent and workspace boundaries as the agent management tools. Definition edits remain project-local. Source start/stop/restart saves desired state for the scheduler to apply; it does not cancel accepted jobs. `/trigger scheduler install` explicitly installs the machine-wide shared service, which can deliver work from other registered projects too.
+
+## Current limits
+
+- Nothing notifies you yet. `runs.jsonl` and `dscode trigger log --failed` are the record a notifier will read.
+- Recurring jobs have stable identities derived from their registration, source and scheduled UTC instant; job creation and advancing the schedule cursor commit together. Manual `run` invocations retain their cadence-window identities.
+- A trigger never asks for approval, and an event can never widen its authority.
+- An unattended run is bounded by `goal.maxRounds`, the limits, and its definition's permission preset; the goal round driver must be mounted for a run to get past its first turn.

package/docs/tui-commands.md

@@ -0,0 +1,204 @@
+# dscode TUI commands
+
+Restart `dscode` to load these commands. Most commands run locally; `/doctor` makes one bounded call to the selected model for analysis. At startup the TUI reads the npm registry once, within eight seconds, and shows a notice when a newer release exists; set `DSCODE_UPDATE_CHECK=off` to skip that check.
+
+If a provider rejects a request for content filtering, the turn stops with a `CONTENT_POLICY` or `CONTENT_FILTER` error and keeps the provider's explanation. Review the request and relevant context before sending a follow-up in the same session. The default retry policy does not repeat these rejected requests, and changing an API key does not resolve a content-filter rejection. DSCODE cannot identify the triggering passage unless the provider supplies it.
+
+| Command | Behavior |
+| --- | --- |
+| `/email` | `i`: connect IMAP with a masked application password; `r`: sync. Browse, preview, and press Enter to steer email directly into this session. [Email interface](email.md). |
+| `/status` | Session ID, workspace, model route, permission mode, recorded token totals/context pressure, tool/plugin counts. Unknown usage stays unknown. `/review-usage` reports the independent reviewer separately. |
+| `/provider [deepseek\|openrouter\|grok\|opencode-go\|custom]` | For self-hosted or private APIs, `/provider custom` opens [Custom model providers](custom-providers.md). Saved custom services also appear by name in the picker: Enter switches to their current or first configured model. The Custom entry adds or edits services. Switch the session between DeepSeek's official API, OpenRouter, Grok and OpenCode Go. Without an argument, open a picker (↑↓ choose, Enter switch, Esc close) that shows each provider's key status. OpenRouter is DSCODE's own adapter over OpenRouter's live model listing (cached for a day in `$DSH_HOME/openrouter-models.json`, settings in the `llm-openrouter` section; `/model` offers DSCODE's curated list from that listing rather than all of it); a switch asks for the key when none is stored, then moves to the counterpart of the current model and keeps the effort when the target offers it. When the new model would compact the current context, the switch asks first. Ultra works on both routes: on OpenRouter it sends `xhigh` plus the collaboration policy, and `low` is sent as `high`, which is how DeepSeek itself answers low. The footer shows the active provider's remaining balance (for OpenRouter, the account's remaining credits, or the key's own remaining limit when OpenRouter refuses the key those) and records the cost OpenRouter reports for each call (estimated from list prices only when it reports none); the 🔥/❄️ peak marker appears only for DeepSeek, because OpenRouter bills no peak window. OpenCode Go serves its chat-completions models to an OpenCode account login, never a key: before `/opencode login` the switch names that command instead of asking for a key, and the footer shows the subscription's usage instead of a cost; see [OpenCode Go](opencode-go.md). Stop a running turn first. |
+| `/model` | Picker for the session's current provider only, listed alphabetically by the displayed model name (digits compare naturally, so GLM 5.2 precedes GLM 5.3). Typing searches as you type (BM25 over model name, id and provider; the word being typed matches prefixes) and narrows the list without re-ranking it; Enter focuses the first match, a second Enter selects it, Esc clears the search then closes, Tab opens the provider picker. |
+| `/opencode [login\|cancel\|logout]` | Sign in to OpenCode Go with an OpenCode account, the route's only credential. `login` shows a code, opens the console in the browser and waits in the background for up to ten minutes; the consent page names the OpenCode CLI, whose login client DSCODE uses. Without an argument it shows who is signed in or how the last attempt ended. The login is stored in `~/.dscode/credentials.yaml` and renews itself. See [OpenCode Go](opencode-go.md). |
+| `/openrouter` | OpenRouter account panel: the account balance, this key's limit and its spend today, this week and this month; with a management key, also every API key's usage and the last 30 days of spend by model and serving provider. `r` refreshes, `m` sets the management key (checked against OpenRouter, stored in `~/.dscode/credentials.yaml`, read-only use; `OPENROUTER_MANAGEMENT_KEY` also works). Saving the OpenRouter API key through `/provider openrouter` or `/login openrouter` offers the management key as an optional step. |
+| `/review` | Independent review of the current changes. `DSCODE_REVIEW_MODEL=provider/model` pins the reviewer to its own model and `DSCODE_REVIEW_EFFORT=<level>` sets its reasoning level, so a small session model cannot cap the review; the budget leaves room for reasoning plus the report. |
+| `/update [exact-version]` | Upgrade DSCODE after this session exits: the TUI starts a detached helper that waits for the session to end and then runs the same `dscode update` entry (npm/Hub launcher, or tar/source self-update). Progress and the outcome are written to `$DSH_HOME/update.log` and `$DSH_HOME/update-result.json`. |
+| `/login [deepseek\|openrouter]` | Paste an API key into the private input; it is saved to `~/.dscode/credentials.yaml` (`0600`, shared across projects and installed versions). Without an argument it targets the current provider. `DEEPSEEK_API_KEY` or `OPENROUTER_API_KEY` in the environment takes precedence and makes that key read-only here. |
+| `/memories [status\|on\|off\|global-on\|global-off\|run\|note <text>\|clear]` | Global cross-session memory controls and background model usage. [Behavior and configuration](memory.md). |
+| `/session` | Current session ID, local socket, and external send/read/watch commands. [Multi-source sessions](session-bridge.md). |
+| `/mailbox [cancel MESSAGE_ID]` | Read messages and deferred notes, or cancel a request/message. [Session communication](session-communication.md). |
+| `/session-new-task` | Explicitly start a fresh communication budget while idle; ordinary continuation and resume retain their existing budgets. |
+| `/goal [<objective>\|clear\|edit <objective>\|pause\|resume]` | Show or control this session's goal: one objective plus the round cap that bounds automatic continuation. `/goal[20] <objective>` creates the goal with a 20-round cap, and `/goal[20]` re-caps the current goal — so an unattended task stops after the rounds you allowed instead of running indefinitely. A cap with no goal, or a control word after a cap, is refused with the usage. |
+| `/trigger` (alias `/triggers`) | Manage this workspace's triggers without a model turn. The default overview shows definitions, registrations and scheduler status. Use `new`, `create`/`update` with JSON fields, `enable`/`disable`, `register`/`unregister`, `run`, `schedule`, `jobs`/`cancel`, `events`, `runs`, `source` and `scheduler`; `/trigger help` lists the syntax. `run` queues an event and reports a stopped scheduler. `new` creates a disabled starter. Mutations require a writable session outside plan mode; scheduler installation starts the shared service for all registered projects. [Triggers](triggers.md). |
+| `/doctor [local\|preview]` | Read-only runtime health plus self-diagnosis from recent warning/error logs and session event traces for this workspace. By default, sends bounded, redacted event metadata to the selected model. `local` skips the model; `preview` shows the exact evidence payload. Does not read conversation text, tool arguments, or tool output. Falls back to local findings if model analysis fails. |
+| `/browser` | Browser status, start/stop, profiles, extension pairing, site permissions, Developer mode, WebMCP, human handoff/resume and tab retention; see [Browser use](browser-use.md). |
+| `/mcp` | List MCP entry IDs, loader state and transport; credentials, headers and environment values are not printed. |
+| `/mcp tools <id>` | List registered tools for a server. |
+| `/mcp enable|disable|reconnect <id>` | Change a server for this process. All agents must be idle. Reconnect disposes and remounts the server. Host servers are configured in `config/mcp.local.yml`; the dscode preset mounts none at startup. Built-in browser connections are managed separately with `/browser`. IDs may be full loader IDs or an unambiguous short ID. |
+| `/skills` | Effective skill catalog, source, provider and invocation permissions. |
+| `/skills <name>` | Description and effective file path, without injecting its instructions into the model. |
+| `/skills conflicts` | Duplicate names in the configured filesystem roots, with the runtime's effective source. Hidden candidates from runtime/remote providers are not enumerable. |
+| `/hooks` | Hook configuration location, the merged layer list and supported events. It also reports a layer whose file changed — or disappeared — after the merge, because only a restart re-reads the layers. |
+| `/hooks reload|enable|disable` | Reload installation-owned hook configuration, or switch hooks for this process while all agents are idle. |
+| `/review [--staged\|--base REF\|--commit REF] [--path RELATIVE_PATH]` | Independently review the selected Git diff in a read-only, tool-free model request. Default includes tracked and untracked uncommitted changes, and when there are none it reviews the commits made since the latest user task started (read from the HEAD reflog), so work that was committed or merged is still reviewed; `--commit` reviews a merge commit against its first parent; empty scopes do not call the model. Narrow large or unrelated diffs with `--path`. |
+| `/delegate <task>` | Hand the task to the main agent as coordinator: it records the parts on a delegate board, launches them as child agents with `worktree: true` in the background while child slots are free (five below Ultra, twenty at Ultra), answers the questions they send to `/`, verifies each finished worktree, and once every task is done merges the accepted ones into the main workspace with `git apply --3way`, leaving them staged and uncommitted. Refused unless the session starts at a clean Git repository root, and inside a child agent. See [Ultra](dscode-ultra.md#delegate-mode). |
+| `/delegate-dashboard` | Popup kanban of the current session's delegate board with four columns — pending, running, verifying, complete — and the child slots in use. A task is running while its child works or waits on an answer from the main agent (marked `?`), and verifying once the child has settled and the main agent has not yet recorded the result. Columns are divided by vertical rules and every task is its own bordered card with its id, child name and title; `▲` marks high priority and `▼` low. Pending cards run in launch order, ready ones first; a blocked task has a grey card with a hollow `◌` and names what it waits on (`after t1,t2`). Waiting cards lead their column. On a short terminal each card folds to one line so more of them fit, and a narrow terminal stacks the columns. It refreshes every second; Esc or q closes it. |
+| `/verbose` | Toggle verbose chat: thinking and tool calls appear dimmed as `· Thinking: …`, `· Tool Call: name args` and `  Output: …` (thinking capped at eight lines), with a blank line between blocks. The setting is saved per machine in `~/.dsh/dsh-code/verbose.json`. Ctrl/Alt+R toggles the same setting; Ctrl+O still opens the full history inspector. |
+| `/mouse` | Toggle mouse capture. On (default) makes the wheel scroll the chat one row per notch, merging the notches that arrive in the same frame; off hands the mouse back to the terminal for drag-select and copy, leaving PageUp/PageDown to scroll the chat. While capture is on, hold Shift (Option in iTerm2, Fn in Terminal.app) to select text. The choice is saved per machine in `~/.dsh/dsh-code/mouse.json`. |
+| `/language [code]` | Without an argument, open a picker (↑↓ choose, enter apply, esc close) for the interface language for DSCODE's own labels, notices, the status-line telemetry labels and the composer placeholder: `en` (default), `zh-CN`, `zh-TW`, `ja`, `ko`, `es`. Names and common aliases work too (`简体中文`, `jp`). The choice is saved per machine in `~/.dsh/dsh-code/language.json`; `DSCODE_LANGUAGE` overrides it for one process. |
+| `/clear` | Start a fresh session and clear the screen after successful activation; the previous session remains available through `/resume`. Stop a running turn first. |
+| Ctrl+L | Clear the screen only, keeping the conversation context. |
+| Ctrl+C | While an agent runs, cancel it immediately; a second press exits the TUI without waiting for the busy display to settle. With an idle draft, the first press clears it and the second exits. |
+
+The interactive preset is fixed to `dscode`. `/mode` is hidden from help and completion; typing it only reports the fixed mode. `/new` creates a DSCODE session and refuses other preset names. Older sessions retain their transcript when resumed under DSCODE. `/model`, `/effort`, `/permission` and plan-mode controls remain independent.
+
+Command results use the standard collapsible TUI result presentation.
+
+Normal mode shows the agent's ordinary text, including progress updates. The agent is instructed to explain its first step, report significant findings or blockers, and give brief updates roughly every minute during sustained work when it has control. This is model guidance, not a timer: a blocking tool call may delay an update until it returns. `/verbose` additionally shows reasoning and tool details; it is not required for progress updates.
+
+The agent also has a `review` tool backed by the same service. Automatic review allows **two passes per direct user task**, including failed passes; a changed path or scope does not reset the allowance. The first pass follows code changes and relevant checks. A second pass verifies confirmed findings and direct regressions from their fixes, rather than opening another audit. Recorded results preserve the allowance when resuming a session; unchanged diff+task+provider+model requests reuse cached reports. Concurrent calls do not start additional reviews. Each pass asks for thinking off (a model without that level keeps its own default), at most **32,768 output tokens per model attempt** (65,536 on the one retry that spent its whole budget without writing anything), and a **90-second deadline** including that retry. An explicit idle `/review` command can request an additional manual pass without resetting the automatic allowance.
+
+The reviewer sees the latest direct user task and at most 160 KiB of selected diff, with common secret formats redacted; it cannot inspect surrounding files, run tests or edit code. It reports at most five concrete defects affecting the task. Findings must be checked against the actual code before edits. Timeouts, truncated output, omitted files and exhausted budgets are incomplete reviews, never clean results. The agent should complete necessary fixes and affected checks, then report remaining gaps instead of repeatedly calling review.
+
+Task completion guidance keeps scope and acceptance checks stable. Once requested behavior and required checks pass, the agent proceeds to delivery; optional refactors and optimizations are separate follow-ups. Changes invalidate only the checks they affect unless evidence requires broader verification. This guidance reduces unnecessary work, but does not mechanically prove that arbitrary shell commands or agent decisions satisfy the task.
+
+`dscode doctor` runs the same diagnostic collector and model analysis without opening the TUI. It checks the current working directory's recent sessions, including subagents, and reads the owner-only `diagnostics/runtime.jsonl` warning/error journal under `DSH_HOME`. `--local` skips the model; `--preview` shows the exact evidence payload. A model call is limited to 45 seconds; missing credentials or model failure leave a local trace summary. These commands diagnose existing evidence and do not execute tools or repair state. `npm run doctor` remains the separate deterministic integration fixture.
+
+Child aliases such as `/reader` are scoped to their parent session. Names of
+continuable children survive a Host restart: sending to the alias resumes the
+same child, and the name stays reserved while that child is cold. Looking up a
+name does not start a turn. Finished foreground children cannot be resumed by
+name; reopen their tasks with an available name to launch new work. A child's
+`send_message` to `/` addresses its parent. Waiting indicators change only after
+successful delivery, so a failed reply keeps the outstanding question visible.
+Edits rejected by validation leave the task unchanged, including its child, worktree,
+verification evidence and priority. Reopening a completed task must use a child
+name that is not already planned for another open task.
+
+Both foreground and background named child runs enter the task board when the
+runtime accepts their launch. A foreground call waits for its child and releases
+that one-shot agent before returning; the task then remains in Verifying with
+its recorded worktree path. Cancellation or failure after launch also leaves the
+task for review. The coordinator must inspect the outcome and explicitly
+complete, reopen or drop it. A task is never marked complete solely because the
+child stopped. Starting a child unsuccessfully before launch leaves it Pending.
+
+## Experimental Desktop delegation board
+
+The combined Desktop package adds **Delegation board** to the right sidebar.
+Select an open DSCODE main session and run `/delegate <task>` in chat to start
+coordination. Its board shows Pending, Running, Verifying and Complete tasks,
+priorities, dependencies, blocked tasks, children waiting for the coordinator,
+and the number of running child slots. Expand **Task details** for owned scope,
+checks, worktree paths, reopen reasons and recorded verification evidence.
+
+The view reads the same live board as the coordinator and refreshes once per
+second while visible. Reading it does not launch children, change tasks or merge
+work. Closing another session leaves the selected board available; switching
+sessions clears the previous view. Task records survive restart, while running
+and verifying status is derived from live children. Recorded evidence describes
+the coordinator's checks; displaying it does not run those checks again.
+
+Child sessions and native Standard sessions cannot read a DSCODE main session's
+board through this view. The terminal continues to use `/delegate-dashboard`;
+Desktop's `/delegate` instructions point to **Delegation board**. The package is
+experimental and unpublished; see [Browser use](browser-use.md#install-the-experimental-combined-desktop-package)
+for local build and installation instructions.
+
+## Experimental Desktop diagnostics
+
+In the combined Desktop package, type complete commands such as
+`/memories status`, `/shell status`, `/review --staged`,
+`/mailbox cancel <message-id>` and `/computer status` in the composer. Their
+arguments go to the native command handler. The diagnostic commands below also
+accept arguments there. None of these commands accepts attachments. Existing
+behavior still applies: a valid `/review` uses the reviewer model, bare
+`/dscode-doctor` requests model analysis, and memory generation may run in the
+background. `/dscode-doctor local` skips model analysis.
+
+The experimental combined Desktop package registers `/dscode-status`,
+`/dscode-doctor [local|preview]`, `/dscode-skills [name|conflicts]` and
+`/dscode-mcp [list|tools|enable|disable|reconnect]`. Select a DSCODE session before
+using them. Native command names keep their existing handlers, and Standard
+sessions cannot use the DSCODE diagnostic commands. Desktop keeps its own updater
+and terminal interface; the package does not add `/dscode-update`,
+`/dscode-shell-exec` or `/dscode-hooks`.
+
+Desktop doctor reads up to six recent sessions in the selected session's
+workspace, including the current session. A workspace with no persisted history
+does not fall back to another workspace. Warning/error logs come from the shared
+Host and can include other workspaces. The collector summarizes session event
+metadata without copying conversation bodies, tool arguments or tool output.
+Known credential patterns in logs and command results are redacted; log messages
+can still contain other application details. Use `preview` to inspect the
+evidence, `local` for local findings, or the command without an argument for one
+bounded analysis call to the selected model. That call is charged to the invoking
+session under `doctor`; failure falls back to local findings.
+
+MCP changes apply only to mutable Host entries and require all agents to be idle.
+Preset modules are inspection-only. Skill conflict reports explicitly mark
+per-agent filesystem roots as unchecked, because the preset inventory does not
+expose their configuration. Current user guides ship in the package's `docs/`
+directory, and the DSCODE agent's documentation prompt points there. Links to
+unbundled developer records open the public repository, which may lag this
+unpublished package. See [Browser use](browser-use.md#install-the-experimental-combined-desktop-package)
+for local installation.
+
+## Hooks
+
+`npm run setup` creates `config/hooks.local.json` containing `{"hooks":{}}`. No hook commands run by default. This file is local to the installation, ignored by git, and excluded from distributable archives. Project `.codex/hooks.json`, `.dsh/hooks.json` and `.claude/settings.json` are layered on top by default; set `DSCODE_PROJECT_HOOKS=0` to load `config/hooks.local.json` alone.
+
+The pinned bridge reads one file for the whole process, so the layers are merged — installation, then `.codex/hooks.json`, `.dsh/hooks.json` and `.claude/settings.json` (its top-level `hooks`) — into `$DSH_HOME/hooks.resolved.json` (mode 0600), and a sibling `hooks.resolved.report.json` report records the layers and any event this bridge cannot run; `/hooks` prints both. A project file is report-only: an event this bridge cannot run, or a gate it cannot load, is skipped and listed with its reason, while `config/hooks.local.json` still fails startup on anything it cannot run. The merged file is rewritten at startup, so an edit to any layer needs a restart rather than `/hooks reload`. Matchers stay regular expressions, so a Claude Code matcher such as `Bash` does not match dscode's `bash` tool — write `^bash$`. These layers run as your OS user outside tool approval, so set `DSCODE_PROJECT_HOOKS=0` on a repository you do not trust.
+
+Edit this file with trusted commands, then `/hooks reload` (or restart). Example:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [{
+      "matcher": "^bash$",
+      "hooks": [{
+        "type": "command",
+        "command": "/absolute/path/to/your-tool-gate",
+        "timeout": 5
+      }]
+    }]
+  }
+}
+```
+
+Hook stdin is a JSON event payload; for shell tools it includes `tool_input.command`. Exit code 2 with a stderr reason blocks the tool. Successful hooks may return the upstream Codex-compatible JSON output. These are host shell commands, running in the session workspace as the OS user, outside the model's tool-approval flow. They can use local CLI credentials; configure them with the same care as local shell scripts. This is not a security sandbox for untrusted project hooks.
+
+The pinned official `@deepseek-ai/dsh-hooks-codex` bridge supports:
+
+- `SessionStart`: attach context; asynchronous delivery may miss the first request.
+- `UserPromptSubmit`: block a prompt or add context.
+- `PreToolUse`: deny a tool; cannot grant approval or rewrite arguments.
+- `PostToolUse`: add context or feedback.
+- `Stop`: request continuation. The hook must self-limit to avoid a continuation loop.
+
+`PermissionRequest`, `PreCompact`, `PostCompact`, `SubagentStart`, `SubagentStop`, async hooks and non-command hooks are not supported. dscode validates these at startup/reload so unsupported gates do not silently load. The default timeout is 10 seconds; explicit hook timeouts may be up to 600 seconds. Hook execution failures otherwise follow the upstream bridge's fail-open behavior. Non-shell tool inputs are reduced to `{command: ""}` by this bridge. Model and permission-mode fields are upstream static placeholders, not authoritative runtime status. Native `hook/invoked` and `hook/result` events remain resumable.
+
+## Skills and workspace instructions
+
+Skills come from the runtime's filesystem provider: the project's `.dsh/skills` and `.agents/skills` (project root is the nearest ancestor containing `.git`), then custom roots, then the user roots under `$DSH_HOME` and `$DSH_AGENTS_HOME`. Ancestor discovery is on by default: `.dsh/skills`, `.agents/skills` and `.claude/skills` from every directory between the working directory and home register at rank 300, nearest first; `DSCODE_SKILL_ANCESTORS=0` (also `off`/`false`/`no`) turns that off, and it belongs in the environment (the installation's `.env`) rather than `config/harness.local.yml`. `AGENTS.md` and `CLAUDE.md` from directories above the project root are folded into the workspace instructions without a switch. [Skills](skills.md) covers the scopes and ranks, the ordering rules, how to verify the mode, and the instruction-file chain.
+
+## Distribution and verification
+
+The launcher applies an idempotent, version-checked patch to the pinned `dsh-code@1.0.6` bundle for `/clear` and startup command discovery. An unsupported upstream version/shape fails setup instead of patching blindly. All other command behavior lives in `plugins/tui-tools` and hooks use the official runtime plugin. `npm ci` followed by setup reinstalls the patch, including on distributed installs.
+
+`npm test` covers hook validation, MCP idle gating/reconnect, skill conflicts and patch drift. `npm run doctor` boots the real profile, calls the command registry, tests MCP unregister/remount, and uses a real hook subprocess to block a deterministic model's shell tool. No paid model call is used.
+
+## Input and session resume
+
+- `!command`: runs the user's command in the current session directory through `$SHELL` (`/bin/sh` by default), showing stdout, stderr and the exit code without starting a model turn. Multi-line commands are supported; each run is its own shell, so `cd` and environment variables do not persist between commands. It runs non-interactively with a 120-second timeout and shows at most 64 KiB of output; exiting or switching session cancels an unfinished command.
+- `Shift+Enter`: newline; `Enter`: send. The CSI-u and xterm modifyOtherKeys Shift+Enter sequences are supported. A terminal that cannot send the modifier can use `Ctrl+J` for a newline.
+- Pasting more than 200 characters shows `[Pasted Content N chars]` in the composer as a placeholder while the surrounding text stays editable; after sending, the transcript expands to the full content and the model receives that same full content. The placeholder can be deleted as one unit. Command text starting with `/` or `!` stays visible.
+- Pasting or dropping an image file path shows `[Image 1]`, `[Image 2]` and so on in the composer; the image is sent as an attachment. On macOS, `Ctrl+V` attaches a screenshot or a copied image straight from the system clipboard; in a terminal that pastes an image as a temporary path, `Cmd+V` goes through the file-path entry point too. The first `Ctrl+V` compiles a local image-reading helper and needs Xcode Command Line Tools.
+- `dscode resume`: continues the most recent session; `dscode resume SESSION_ID`: resumes the named session. `--cwd DIRECTORY` may be appended. After a successful exit and save it prints the resume command for the current session.
+- A session's folder is chosen when it is created and never changes: resuming one, through `--resume`, `/resume`, `/search` or a queued switch, works in the folder the session is bound to, and the window's workspace, shell and durable log all follow that folder. A resume that leaves the folder `dscode` was launched in prints one warning notice naming both folders, so a window that silently changed project is visible. To reach another project's context from here, have an agent read that session or use `dscode send` across sessions instead of resuming it.
+- The main chat area hides thinking, tool arguments, tool results and completed tool calls; the dynamic area shows only the name of the tool currently running. User messages, agent prose, user shell command results and the necessary error/approval prompts are still shown. The complete record stays in the session and can be seen through the history detail or an export.
+- When a turn ends, the chat area draws a light separator line after that turn's last visible record; the next turn starts on a new line. Turn separators are kept when a session is resumed, and an export contains none.
+- A sent user message uses its own light-grey background block in the main chat area; the background stays continuous when a long message wraps, and the dark and light themes adapt separately. A session export is still plain text.
+- CJK input-method positioning: after each frame the terminal's real cursor is synchronised to the composer's current character position (including CJK width, line wrapping and the composer's internal scroll), and the render position is restored before the redraw. A change here needs the TUI restarted; how the macOS candidate window appears still has to be verified in the terminal actually in use.
+- The screen is cleared on startup; the interface shows the most recent session content according to the terminal height, with the composer and status bar pinned to the bottom. The mouse wheel or PageUp/PageDown browses earlier messages in the main chat area, and following new messages resumes after scrolling back to the bottom; Ctrl+O shows the complete session record and `/export` exports it. The terminal scrollback no longer keeps appending completed messages.
+- The effort step of `/effort` and `/model` replaces the composer at the bottom. A model with four bands shows a horizontal `low → high → max → ultra` bar; arrow keys move, Enter applies, Esc cancels and restores the composer, and `o` switches straight to off. As the cursor reaches ultra a blue effect spreads from the centre outwards; after Enter applies, the composer plays a short central ripple. Nothing plays while animations are off. Other models still show the band list they provide. When switching models, a supported effort is preserved; otherwise the picker starts at the target model's default (for example, MiMo `medium` becomes DeepSeek's default `high`). The footer shows the selected model's effort without borrowing a previous request's value. If no default is advertised, the default selection has no effort label.
+
+## DSCODE interface layout
+
+The startup header is a compact welcome box: on the left a pixel snowflake in three blues — six arms 60° apart around a bright hexagonal crystal, twelve lines tall, or eleven on terminals under 26 rows — and on the right a bold DSCODE wordmark with a thin divider that brands the box and lists the current model, effort, local version and project path. A narrow window or a short terminal compresses it to a three-line layout with ❄, keeping the last directory of a long path. A session title that changes while running still shows at the bottom. The body keeps the user and agent output, while thinking and tool-call history stay hidden.
+
+Above the composer, thinking, the reply or the current tool and its description are shown uniformly, timed as the total for the turn. Only the running marker animates; the composer plays no wave. The sub-agent overview separates running / idle / done, and `/agents` shows the tasks and current activity.
+
+The footer leads row 1 with the session name and the model with its effort, then the working directory, the permission badge and any task state. Row 2 places request TPS, session-average TPS, context and the loaded skill count on the left, with session cost, DeepSeek balance and peak/off-peak marker, optional last-turn cost and cache rate aligned together on the right. Space separates the groups; `·` separates figures within each group. At narrow widths the financial group moves to a third row before left-side figures are dropped. Average TPS yields before current TPS, context and skills. Extremely narrow terminals may omit the optional last-turn cost and clip the financial group. `/statusline` still customises every original item, and an existing custom configuration keeps working.

package/extensions/browser/manifest.json

@@ -0,0 +1,22 @@
+{
+  "manifest_version": 3,
+  "name": "DSCODE Browser",
+  "version": "0.1.0",
+  "description": "Share selected browser tabs with your local DSCODE session.",
+  "minimum_chrome_version": "125",
+  "key": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA7hXV+eosyq7w+kTH3h/jv/OLf92aNLA4XcI9rxVZr8pcdLewrdVWQRRYpp1Ug0NkcBjwoLyhWlhU1ulyEcs4HekF3l7EQpcUa8vKOMUxzzZSTqmUSVYXRoHd9Vl0plsMccL/uDCvqNCn3oi7eSpPuX0oAvOoUeyhM+2bPqSF1mMhZOqPp1U82fct09Wh68B5WQTCzzkm1GG4QqSPCjpvk1ht9GvuPXFyg2TWf/O6ZWkt94K4fgvoGdFNbwwOr8O5J+KKV3vVej1U+o7n6LbFC/9j9zzrHyneWgVNVkUAML7Uq23h5gI2ZEWGlp9Xz5UyTzYuJ/iJysbWflVErGBnQQIDAQAB",
+  "permissions": [
+    "debugger",
+    "activeTab"
+  ],
+  "host_permissions": [
+    "http://127.0.0.1/*"
+  ],
+  "background": {
+    "service_worker": "worker.mjs",
+    "type": "module"
+  },
+  "action": {
+    "default_popup": "popup.html"
+  }
+}

package/extensions/browser/popup.css

@@ -0,0 +1,6 @@
+body { width: 330px; margin: 18px; color: #20242c; background: #fafafa; font: 14px/1.5 system-ui; }
+h1 { font-size: 19px; } label, input, button { display: block; box-sizing: border-box; width: 100%; }
+input, button { padding: 9px; margin: 8px 0; border: 1px solid #c8cbd0; border-radius: 6px; }
+button { cursor: pointer; background: #fff; } button:disabled { opacity: .5; }
+#stop { border-color: #bd4520; color: #a13613; } [hidden] { display: none; }
+li { overflow-wrap: anywhere; } #status { font-weight: 600; }