@toddzheng024/dscode-desktop 0.0.0-stage → 0.7.33

package/docs/email.md

@@ -0,0 +1,296 @@
+# Email inbox
+
+`/email` opens a local inbox in the TUI. The right-hand list is sorted by
+`updatedAt`, newest first; the left side previews the selected message.
+On narrow terminals, Tab switches between list and preview.
+
+- ↑/↓ selects a message; PgUp/PgDn scrolls its preview.
+- Enter immediately steers the full message, sender, subject and source into
+  the current session. A running agent receives it at the next step; an idle
+  agent starts a turn. No second Enter is needed.
+- Esc closes the inbox without sending. Receipt and browsing never start a model turn.
+- The open inbox refreshes every two seconds; `r` refreshes immediately. Selection
+  stays on the same message when newer messages arrive.
+
+The inbox belongs to the local user and is shared across sessions. Its default
+directory is `~/.dscode/email`; `DSCODE_EMAIL_DIR` overrides it. New directories
+use mode 0700 and messages use 0600. Message content enters session history only
+when selected with Enter. Existing composer drafts and attachments are preserved.
+
+## Experimental Desktop inbox
+
+The combined Desktop package adds **Open right sidebar → Email inbox**. It reads
+the same local inbox as the terminal. Select a message to preview its plain text;
+**Add email to this session** steers it into the selected DSCODE session, starting
+a turn if idle. The message is explicitly marked as external context. Reading,
+refreshing and syncing never start a turn. Standard sessions can browse the human
+inbox interface but cannot receive a DSCODE email injection or access DSCODE's
+email sender/contact tools.
+
+The Host checks that the selected message revision still matches its preview.
+A changed message must be previewed again. A request retried with the same ID is
+recognized in the persisted session admission history, including after restart;
+it is not inserted or used to wake the agent again. The result acknowledges
+admission, not successful model processing. Cancellation can discard pending
+steering. Reopening and selecting the message again creates a new request if you
+explicitly want to add it again. Switching sessions or hiding the pane clears
+the preview and connection drafts; existing composer text is untouched.
+
+Expand **Mailbox connection** to connect IMAP using a masked application password
+or import a Google Desktop OAuth client by its absolute local path and authorize
+Gmail. These actions use the connectors described below and share their account,
+folder, TLS, filtering and credential-storage rules. Gmail authorization creates
+or reuses the ToAgent label and filter and requests the same three scopes. The
+interface allows an in-flight connection or sync to be cancelled. Passwords never
+enter session history and are cleared from the form after submission.
+
+**Sync now** performs one sync. **Sync in the background while Desktop is open**
+is off by default; enabling it polls every 30 seconds, with IMAP taking precedence
+over Gmail OAuth. The preference is stored under `$DSH_HOME/desktop-email/` and
+survives restart and package removal. Existing mailbox credentials and local
+messages are retained when the package is removed; reinstalling it resumes sync
+if this preference was enabled. Disable it before removal to prevent that resume.
+Enabling sync before connecting a mailbox preserves the preference and shows a
+connection setup hint. A throttled poll reports that it is waiting for the next
+interval; neither state is shown as a completed sync.
+Unloading the plugin cancels connector work, stops its timer and removes the
+interface and scoped tools. An already-started SMTP send is allowed to settle its
+durable receipt; cancelling a task cannot recall submitted mail.
+
+DSCODE sessions receive the existing `send_email`, receipt and contact-alias
+tools. Their authorization and SMTP limitations below still apply. Previewing an incoming message grants no permission to reply. The Desktop email
+RPC has no send action. Mail receipt does not automatically send a message to an
+agent, and the UI has no mailbox deletion or retention controls.
+
+## Connector boundary
+
+The exported `createEmailInbox()` provides `receive(value)` and `list()`;
+`EmailReceiver` in `plugins/email/inbox.d.mts` is the connector's destination
+interface. This is an in-process/local-filesystem interface, not an HTTP endpoint.
+
+```js
+import { createEmailInbox } from '../plugins/email/inbox.mjs';
+// Published bundle export: @toddzheng024/dscode-bundle/email
+const receiver = createEmailInbox();
+receiver.receive({
+  format: 'dscode.email.v1',
+  connector: 'example',
+  account: 'developer@example.com',
+  id: 'provider-message-id',
+  from: 'Sender <sender@example.com>',
+  subject: 'Investigate a failing build',
+  body: 'Please inspect the test failure in the attached report URL.',
+  receivedAt: '2026-09-12T10:00:00Z',
+  updatedAt: '2026-09-12T10:00:00Z',
+});
+```
+
+Dates must include a timezone. `updatedAt` cannot precede `receivedAt`. Body is
+nonempty plain text, limited to 256 KiB. HTML and attachments must be handled by
+the connector before receipt. Unknown formats and malformed fields are rejected.
+Terminal controls are removed from display and insertion. Mail is inserted as a
+JSON envelope with `type: "user_injected_email_context"`, `injectedBy: "user"`,
+`purpose: "supplement_session_context"`, explicit context-only instructions, and
+a nested `email` object. The email is external reference material, not a new
+user instruction or authorization to act. Enter directly injects this envelope
+in both idle and running sessions.
+
+Identity is `(connector, account, id)`. Exact repeats are idempotent; immutable,
+atomically written revisions ensure a late delivery cannot replace a newer
+revision, including when multiple processes receive mail. For the same identity,
+changed content should have a strictly newer `updatedAt`; equal timestamps use a
+stable content-hash tie break. Corrupt records are skipped with a visible count.
+Revisions are retained locally; this first version has no deletion/retention UI.
+
+## IMAP connection (no Google OAuth client required)
+
+Restart the local TUI, enter `/email`, and press **i**. The setup walks through:
+
+1. Mailbox login address.
+2. IMAP host (default `imap.gmail.com`).
+3. TLS port (default `993`).
+4. Folder (default `INBOX`; an existing `ToAgent` folder may be used).
+5. Application password, entered in a masked private field.
+
+Enter accepts each field; Tab revisits fields; Ctrl+U clears the current field.
+Esc cancels, including an in-flight connection. Credentials are saved only after
+TLS login and opening the chosen folder succeed. They are never submitted to
+the agent, recorded in composer history, or printed in status/error messages.
+To update a password, press **i** and reconnect the same account and folder.
+
+For Gmail, first enable 2-Step Verification and generate an application password
+in [Google Account settings](https://support.google.com/mail/answer/185833?hl=en).
+Some organization or Advanced Protection accounts do not offer this option.
+Use that password in the TUI, not the ordinary Google account password. No Google
+Cloud project or client JSON is needed for this IMAP path.
+
+The default directly filters `INBOX` by the exact `[ToAgent]` subject prefix.
+It does not require or create a Gmail label/filter. If a custom `ToAgent` folder
+is selected, create and route mail to that folder in the mail provider first.
+Only the selected folder is checked; mail auto-archived elsewhere is not picked
+up from `INBOX`. App passwords grant mailbox access, not per-folder access; the
+connector enforces the selected folder and subject checks.
+
+Connections require TLS with certificate verification. The client opens the
+folder read-only and uses `BODY.PEEK`; it never marks mail read, changes flags,
+sends mail, or deletes messages. Strict subject checks happen before retrieving
+a full message. Plain-text MIME bodies are accepted, including multipart
+alternatives; HTML-only and attachment-only messages are skipped. Raw messages
+are capped at 2 MiB and the decoded text at 256 KiB, so larger messages are skipped.
+
+The first successful connection records UIDVALIDITY and UIDNEXT without importing
+existing mail. Subsequent polls use bounded UID ranges, process at most 50 matching
+candidates per poll, and checkpoint only after persistence. Retries deduplicate
+by source content. UIDVALIDITY changes trigger recovery using the original
+connection timestamp (at IMAP's second precision) and content identity, instead
+of trusting old UIDs or importing the whole historical inbox.
+
+All sessions share `~/.dscode/email/imap/connection.json` (or
+`$DSCODE_EMAIL_DIR/imap/connection.json`). It contains the credentials and cursor,
+is written atomically with mode 0600 inside a new 0700 directory, and is guarded
+by a kernel lock. A running TUI polls every 30 seconds even with `/email` closed;
+there is no daemon after all TUIs exit. Press **r** for an immediate sync.
+
+IMAP takes precedence over the earlier Gmail OAuth connector when both are
+configured, avoiding two background connectors polling the same mailbox. The
+existing OAuth configuration is retained. Previously imported messages remain
+in the shared inbox; cross-connector imports are not merged automatically.
+
+Development diagnostics (no passwords accepted as CLI arguments):
+
+```sh
+node bin/dscode.mjs email imap-status
+node bin/dscode.mjs email imap-sync
+```
+
+The packaged launcher supports `dscode email imap-status` and `imap-sync` after
+release. The current implementation is local and has not been publicly released.
+
+## Gmail OAuth connection (optional)
+
+The Gmail connector is implemented locally. It requires a Google Cloud Desktop
+OAuth client and the user's browser authorization before real mail can sync.
+
+1. In Google Cloud, enable **Gmail API**, configure the OAuth consent screen, and
+   create an OAuth client with application type **Desktop app**. Download its
+   JSON file. See [Google's setup instructions](https://developers.google.com/workspace/gmail/api/quickstart/nodejs).
+2. Import the downloaded file using its path (never paste its contents into chat):
+
+   ```sh
+   node bin/dscode.mjs email configure /absolute/path/to/client.json
+   ```
+
+3. Restart the local TUI, open `/email`, and press **g**. Choose the Gmail account
+   and grant the requested permissions in the system browser. Esc cancels.
+   Alternatively, run `node bin/dscode.mjs email connect`.
+4. After connection succeeds, new incoming mail must have a subject beginning
+   with `[ToAgent]` followed by whitespace or the end of the subject, and a
+   nonempty `text/plain` body. For example, `[ToAgent] Check the login module`.
+
+The distributed launcher supports the same commands as `dscode email configure`,
+`connect`, `status`, and `sync` when this version is released. Development commands
+above run the current checkout. `status` reports no secrets; `sync` performs one
+explicit sync. `/email` shows the connection status; **r** requests an immediate
+sync and **g** reauthorizes the same account if access expires.
+
+The connector creates or reuses the **ToAgent** label and an incoming-mail
+subject filter. Gmail's subject search is a candidate filter; the connector
+independently checks the exact `[ToAgent]` prefix, current label and receipt date
+before fetching a full body. Replies prefixed `Re:`, HTML-only messages, drafts,
+sent mail, trash and spam are not imported. A `text/plain` alternative within a
+multipart message is accepted; ordinary attachments and nested forwarded-message
+attachments are not imported. Plain-text MIME bodies stored separately by Gmail
+are fetched using the body attachment endpoint. No messages are sent, marked
+read, deleted or automatically submitted to an agent.
+
+OAuth requests `gmail.readonly`, `gmail.labels`, and `gmail.settings.basic` for
+reading mail and setting up the agreed label/filter. These are Google account
+permissions, not a Google-enforced per-label grant; DSCODE's connector enforces
+the mail filter. See Google's [label](https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.labels/create)
+and [filter](https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.settings.filters/create)
+permission documentation. Login uses [desktop loopback OAuth with PKCE and state validation](https://developers.google.com/identity/protocols/oauth2/native-app).
+
+The client JSON, tokens and sync state are stored privately under
+`~/.dscode/email/gmail/` (or `$DSCODE_EMAIL_DIR/gmail/`). Files are atomic 0600
+writes inside a new 0700 directory. `DSCODE_GMAIL_CLIENT_FILE` optionally points
+at an existing client JSON instead of importing it. Keep that file available
+for token refresh. Only one account is supported; reconnecting another account
+is rejected without replacing the current credentials.
+
+After first connection, this connector records a Gmail history cursor and does
+not import old mail. A running TUI syncs every 30 seconds, even with the inbox
+panel closed, provided IMAP is not configured. There is no always-on daemon: when all TUIs are closed, the next
+launch catches up. Multiple sessions share a kernel lock and a polling timestamp.
+The cursor advances only after all accepted messages are persisted. Retries are
+idempotent. If [Gmail history expires](https://developers.google.com/workspace/gmail/api/guides/sync),
+recovery lists labelled messages since the original connection date and retains
+that date boundary. Reauthorization of the same account also retains it.
+
+This first connector has no account-switch or disconnect UI. Revocation is
+available through the Google account's app-access settings. Provisioned labels
+and filters are not removed automatically.
+
+Validation: `npm test` includes deterministic Gmail transport fixtures, real
+local OAuth callback/PKCE/cancellation tests, shared-lock and cursor recovery
+checks, a local TLS server exercising the real IMAP library, MIME parsing, masked
+IMAP credential entry, and the real Ink `/email` keyboard flow. Callback tests require local
+loopback listeners. Real Google authorization and mail delivery are separate
+verification steps; automated tests use no actual Gmail credentials or messages.
+
+## Send email from the agent
+
+After configuring Gmail with an application password, restart DSCODE to load
+`send_email` and `email_send_status`. Ask, for example: “Send a [ToAgent] email
+to colleague@example.com summarizing this change and asking them to review it.”
+The agent uses the existing approval flow to check recipient and content against
+your authorization. Incoming mail does not authorize automatic replies.
+
+`send_email` accepts `to` (one address), `subject`, `body` (plain text, up to
+256 KiB), and a globally unique `idempotency_key`. It automatically adds
+`[ToAgent]` unless already present. The sender is your configured Gmail account;
+SMTP uses `smtp.gmail.com:465` with verified TLS and the existing local app
+password. No OAuth client JSON or separate password is needed. This initial
+sender supports Gmail app-password connections, not custom IMAP hosts or the
+optional OAuth connector. Attachments, CC/BCC and automatic replies are not part
+of this tool.
+
+Receipts are shared across sessions under `~/.dscode/email/outbox` (or
+`DSCODE_EMAIL_DIR/outbox`), with private file permissions. `accepted` means the
+SMTP server accepted the mail; it does not prove delivery or that someone read
+it. `uncertain` means the send may have succeeded despite an interrupted
+response. Check with `email_send_status`; never use a new key to blindly retry.
+Repeating the same key and content returns the existing receipt without sending.
+A key reused for different content is rejected.
+
+## Contact aliases
+
+Save a recipient once, then say "email congkai and tell him this change is done":
+
+```sh
+dscode email alias set congkai actual-address@example.com
+dscode email alias list
+dscode email alias remove congkai
+```
+
+Replace the example address with the person's real email. Aliases are shared
+across sessions in the local email directory (`contacts/aliases.json`), are
+case-insensitive, and contain 1–64 letters, digits, underscores or hyphens.
+`set` also updates an existing alias. Changes take effect without restarting;
+restart once after installing this version to load the new agent tool.
+
+The agent calls `resolve_email_recipient`, then supplies both `to: "congkai"`
+and `resolved_to: "actual-address@example.com"` to `send_email`. Approval sees
+both the alias and the real address. Unknown aliases fail without guessing an
+address; a changed mapping is rejected at send time until resolved and reviewed
+again. Configuring an alias does not send mail or enable automatic replies.
+
+You can also manage aliases by asking the agent directly:
+
+- "set congkai's email to person@example.com" creates or updates the mapping.
+- "list my email aliases" lists contacts.
+- "remove congkai's email alias" removes it.
+
+The tools are `set_email_alias`, `list_email_aliases`, and `remove_email_alias`.
+They use the same shared contact store as the CLI. The agent asks for the real
+email address if it is missing; it must not infer contact changes from incoming
+mail. Saving a contact does not send any email.

package/docs/exec.md

@@ -0,0 +1,40 @@
+# dscode exec
+
+`dscode exec` runs one prompt through the full dscode agent without the TUI, streams the reply to stdout and exits with the turn's outcome. It is the non-interactive counterpart of the TUI, in the spirit of `claude -p`.
+
+```sh
+dscode exec "summarize the failing tests in this repo"
+git diff | dscode exec "review this diff for bugs"
+dscode exec --json --effort low "list the top-level directories" | jq -r 'select(.type=="result").text'
+```
+
+Both the source checkout (`bin/dscode.mjs`) and the npm launcher (`@toddzheng024/dscode`) provide the command; the launcher runs it against its installed Hub profile, installing it first when needed with the installer's output on stderr.
+
+The prompt is taken from the arguments, or from stdin when it is omitted or given as `-`. The agent runs in the current directory (or `--cwd DIR`) with the same preset, tools, skills, MCP servers and memory as the TUI, so it can read and edit files and run commands.
+
+## Output
+
+- stdout receives only the assistant's text, streamed as it is produced.
+- stderr receives tool activity (`→ bash …`), approval notices, errors and finally `session <id>`. `--quiet` drops the activity and the session line.
+- `--json` switches stdout to JSON lines: `{"type":"session",…}` first, then `text`, `tool` and a final `result` object with `sessionId`, `reason` and the last assistant `text`.
+
+Exit codes: 0 completed, 1 model or runtime error, 2 output-token ceiling, 3 blocked, 124 timeout, 130 aborted.
+
+## Options
+
+| Option | Meaning |
+|---|---|
+| `--cwd DIR` | Workspace for the agent. Default: current directory. |
+| `--model PROVIDER/ID` | Model route. Default: the saved default model. |
+| `--effort LEVEL` | `low`, `high`, `max` or `ultra`. Default: the saved default effort. |
+| `--permission PRESET` | `auto-review`, `ask`, `workspace-write`, `read-only` or `danger-full-access`. Default: the profile default. |
+| `--approve-all` | Answer every approval request with allow. Without it a request that reaches the human fallback is rejected, since nobody is watching. |
+| `--resume SESSION_ID` | Continue an existing session; the id is printed at the end of every run. The session stays bound to the folder it was created in: a resume from another directory still writes the session's log there and reports it there, while this run's own working directory remains the one it was launched in, so run it from the session's folder (or pass `--cwd DIRECTORY`) when the turn must touch that folder. |
+| `--timeout SECONDS` | Give up and exit 124. |
+| `--patch FILE` | Extra dsh composition overlay, repeatable. |
+
+## How it works
+
+One prompt, one turn, started by you or by a script; a run started by an event instead is a [trigger](triggers.md), which keeps going toward a goal. The CLI half (argument parsing and the overlay in `plugins/exec/cli.mjs`, driven by `scripts/exec.mjs` in a checkout or `packages/launcher/manager.mjs` in the launcher) provisions the runtime like `dscode` does, then starts the same dsh Host with an overlay that disables the TUI rows and session cards and inserts `plugins/exec/index.mjs`. That plugin composes a `dscode` agent, applies the permission preset, forwards live text chunks and session events to stdout/stderr, answers approval requests, and asks the Host to exit when the turn ends. Sessions are ordinary dscode sessions: they appear in `/resume` and can be continued in the TUI.
+
+`scripts/verify-exec.mjs` exercises the command end to end against a fixture model (`npm run test:integration`).

package/docs/hub-distribution.md

@@ -0,0 +1,190 @@
+# npm + Hub distribution
+
+## Packages and responsibilities
+
+- `@toddzheng024/dscode`: the global `dscode` command; the first launch applies the Hub's `dscode` profile and later runs the installed version directly. It ships its own install-tool shims on `PATH`: `pnpm` is pinned to 10.15.1 for the profile install, and the `npx` shim pins DSH together with pnpm for a Hub release that still spawns a pinned-DSH `npx` command. Hub CLI 0.5.0 prepares and verifies the pinned DSH runtime itself — an exact-version `npm install` into `$DSCODE_HOME/.hub/runtimes/<version>`, then launch with the current Node — so a rewritten `PATH` cannot pick up a system version by mistake.
+- `@toddzheng024/dscode-bundle`: the complete Cordis composition, including the base layer, Computer Use, the modified TUI/runtime modules and this repository's plugins. Modified modules are generated at build time, and no third-party file is changed at install time.
+- `@toddzheng024/dscode-desktop`: the extension for official Harness Desktop, published under the npm `preview` tag. It has its own exact runtime compatibility and Hub listing, and is not part of the terminal Hub profile.
+- Hub profile `dscode`: the exact versions and integrity hashes of the bundle and the DSH runtime.
+
+The complete bundle pins the shared DSH dependencies and the vendored terminal's runtime dependencies explicitly, using the repository lockfile. The terminal's workspace package is compiled into the bundle; its dependencies must still be installed, including `chalk` and `ink`. Do not stack it with another base/TUI bundle in one profile: installing several root bundles in Hub order resolves a wide transitive dependency to the other rc line first. A standalone profile's pnpm hoisted + autoInstallPeers=false is the verified installation path. A direct `npm install` of the bundle hits Computer Use's old peer range; end users install through the launcher.
+
+## User
+
+```sh
+npm install -g @toddzheng024/dscode
+dscode
+```
+
+The first install fetches the code from Hub/npm over the network. It needs macOS 14+, Node 22.19+ (22.x) or 24+, Git and Chrome. Dependencies install with ignore-scripts, matching the verified precompiled-module path, so no third-party install script runs automatically. A normal agent shell does not force this npm option.
+
+DeepSeek and OpenRouter keys are stored locally through `/login` (`/login openrouter`), and `/provider` switches between them; other model keys are configured in `/model`, or set `DEEPSEEK_API_KEY` / `OPENROUTER_API_KEY`. Accessibility/Screen Recording permission is granted by macOS.
+
+```sh
+dscode update 0.7.8
+dscode history
+dscode rollback
+dscode doctor
+```
+
+`dscode update` first replaces the global launcher itself with npm at the target version, then moves the profile to the same version: an explicit version updates both to that exact version; with no version it asks npm for the latest launcher and updates both when there is a newer one, otherwise the profile only follows the current launcher's recommended version (the same fallback applies when npm is unreachable, so `latest` is never tracked implicitly). `npm install -g @toddzheng024/dscode@<version>` also works manually. One data directory can run several launchers/root sessions at once. Startup and version management serialise admission through a short-lived kernel lock, and each running Host holds its own version-protection lock; install/update/rollback has to wait for those Hosts to exit. When a launcher exits unexpectedly, the runtime or Hub child process inherits the lock descriptor so it does not lose protection while still running. A newer launcher notices an older one still alive and asks it to exit first. Session write exclusivity stays with the native Harness lock.
+
+The default state directory is `~/.local/share/dscode-hub`, overridable with `DSCODE_HOME`; it is separate from the existing tar installation and this repository's `.runtime`. Sessions, credentials, review and cost records live in the data directory, not inside the npm package. Configuration lives in that directory's `.env` and `config/`, supporting `hooks.local.json`, `mcp.local.yml` and `harness.local.yml`. The profile lives in `profiles/dscode`. Hub manages upgrade and rollback directories; sessions do not roll back with the profile, but crossing a future incompatible session-format version still needs a migration.
+
+A user who already has dsh-hub installed can apply directly, but must use pnpm 10.15.1, set a dedicated `DSH_HOME` and `DSH_AGENTS_HOME`, and set `npm_config_ignore_scripts=true` on the install command. The launcher is recommended because it unifies those conditions.
+
+## Release checklist
+
+Cutting a release from this repository, in order. The rule that matters most: **the git tag must equal `v<package.json version>`, and that version must not already be on npm from a different build.**
+
+1. Decide the version and bump `package.json` `version`. Never re-tag a version that has already been published.
+2. Ship the release documentation in the same commit: `docs/releases/<version>.md`, `docs/CHANGELOG.md` and both READMEs (see [AGENTS.md](https://github.com/qiz029/dscode/blob/main/AGENTS.md)).
+3. Commit, then tag and push:
+   ```sh
+   git tag v<version>
+   git push origin main --tags
+   ```
+   The `build` job fails immediately when the tag and the manifest version disagree.
+4. Watch the run:
+   ```sh
+   gh run list --workflow=release.yml --limit 3
+   gh run view <run-id>                 # job and step status
+   gh run view --job=<job-id> --log-failed
+   ```
+5. On a tag push the `publish` job runs: credential check → bundle → profile sync → launcher → Desktop npm/Hub publication and public installation verification → attach the tarballs. **The launcher is published last on purpose**; a user's first launch fails when the launcher reaches npm before its bundle and its Hub profile. The order is enforced by the job, not by discipline.
+6. Confirm the published result rather than the green check: the credential step prints `free to publish` (or `already on npm with the tested integrity` for a re-run), and the attach step either creates or updates the GitHub release the `dscode update` assets come from.
+
+7. The Homebrew tap follows on its own: `qiz029/homebrew-tap` runs a scheduled (and manually dispatchable) workflow that reads `npm view @toddzheng024/dscode version`, recomputes the launcher tarball's sha256 and commits the formula change. It is deliberately not wired to this repository's tag push — the launcher is the last stage the publish job releases, so a formula bumped earlier would send a user to a Hub profile that is not there yet.
+
+Before tagging, a dry run needs no publication: Actions → Release → Run workflow with both switches left `false` (build and verify only), or tick `verify_credentials` to check the tokens and whether the version is still free.
+
+### Known failure modes
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| `publish` fails in about 30 seconds at *Check the publishing credentials* with `... is already on npm with a different build; bump the version before pushing a release tag` | That version was already published from a different build. An identical `dist.integrity` is treated as a skippable re-run; anything else is a conflict. | Bump `package.json` and cut a new tag. Do not re-tag, and do not force-push the tag. |
+| `publish` fails at `test -n "$NPM_PUBLISH_TOKEN"` / `$DSH_HUB_TOKEN` | The repository secret is missing or empty. | Add it under Settings → Secrets and variables → Actions; see the table below. |
+| A credential that is present but dead: `npm credential OK` or `Hub credential OK` never prints and the step dies inside `npm whoami` or the profile read | The token expired or lost its scope. | Regenerate the granular npm token (Read and write for the launcher, bundle and Desktop packages, bypass 2FA) and update the secret. |
+| `build` fails in under a minute | A code or packaging problem, not credentials (0.7.14 failed this way on a missing bundle export). | Read that step's log, fix, and bump the version again if it was already published. |
+| `make release`, `make verify` or `npm run doctor` fails inside a dscode session with `sandbox-exec: sandbox_apply: Operation not permitted` | The session's own sandbox refuses to apply a nested profile. | Run them from a normal terminal, or configure `plugins/tui-tools/sandbox-runner.mjs`; see [Verification](https://github.com/qiz029/dscode/blob/main/docs/verification.md). |
+
+A tag push is the only thing that publishes. A manual run only publishes when `publish` is ticked, so a mis-typed dispatch cannot ship a release.
+
+## Publisher
+
+```sh
+# Write the real GitHub repository into the release metadata; never a fabricated URL.
+DSCODE_REPOSITORY=https://github.com/OWNER/REPO npm run build:packages
+npm run release:hub
+npm test
+npm run verify:hub
+```
+
+The same sequence is wrapped in Make targets: `make release` runs version-check, `npm run check`, `build:packages`, `release:hub`, `dist`, `verify:hub`, then Desktop preparation and exact-archive qualification in order and packs `release-candidates.tar.gz` (matching CI's build job); `make publish` runs the read-only credential check, then bundle, profile, launcher, Desktop publication/verification and release-asset upload (matching CI's publish job, requiring `NPM_PUBLISH_TOKEN`, `DSH_HUB_TOKEN` and, for attaching assets, `GH_TOKEN`). A single stage can be re-run with `make publish-bundle|publish-profile|publish-launcher`, and `make help` lists every target; the workflow itself does not call make.
+
+Artifacts live in `artifacts/npm/`: two npm tgz files, the Hub draft/release JSON and the `.dshprofile`. A build copies only whitelisted files, never user configuration, credentials or sessions; a release carries the original MIT licence and the modification notice.
+
+`verify:hub` installs a real launcher in a temporary directory and serves the not-yet-published bundle from a loopback npm registry. It checks the native locked Hub installer, imports the installed bundle's public `/startup` and `/tui` entries, checks launcher composition and Hub doctor, then uses separate external-executor fixtures for the agent loop, replacement and rollback. The import check resolves dependencies from that isolated profile so a developer checkout cannot supply missing terminal dependencies. Publication requires these results, including `terminalImports`, against the exact tarball hashes. It does not exercise interactive terminal rendering, public Hub discovery or a real npm publish. The tests request no remote model.
+
+The launcher vendors Hub CLI 0.5.0 with a narrow compatibility fix for the empty `cordis.yml` generated by Harness composition. Only the exact generated content is excluded from dependency-input receipts, and only when package-manager hooks are absent. Custom root content, other configuration and dependency locks remain checked. The compatibility fix is applied to build copies; recipient dependencies are not patched during installation.
+
+The publication order:
+
+1. Validate the package metadata and the real public source repository with `dsh-hub validate artifacts/npm/bundle`.
+2. Confirm `npm whoami` is `toddzheng024`, then publish the bundle tgz (`npm publish ... --access public`).
+3. Register/claim `@toddzheng024/dscode-bundle` in the Hub publisher console and confirm the exact version resolves.
+4. Save the generated profile draft, then publish the `dscode` release for the same version.
+5. After verifying a public Hub apply/doctor under a fresh DSH_HOME, publish the launcher tgz.
+6. Complete a first-launch verification in another clean directory using the launcher from public npm.
+
+Never publish the launcher before the bundle/Hub release is available, or the user's first launch fails. A new version has to regenerate packages and the release; an old integrity hash cannot be reused. `build:packages` and `release:hub` produce the candidate artifacts; a release counts as done only after it is published and confirmed on the public registry. v0.1.0 has been distributed publicly through npm + Hub.
+
+Hub calls retry in a bounded way (`scripts/hub-retry.mjs`): a 5xx or transport failure retries 5 times by default, 3 seconds apart, overridable with `DSCODE_HUB_RETRY_ATTEMPTS` / `DSCODE_HUB_RETRY_MS`; a 4xx (invalid token, missing package, immutable version) fails immediately. Exhausting the retries throws the last error, so a long Hub outage fails the release rather than continuing without verification.
+
+The publish script runs per stage: `npm run publish:hub -- bundle`, `npm run publish:hub -- profile`, `npm run publish:hub -- launcher`. Each stage verifies the hashes of the tested artifacts; before publishing the launcher it checks the exact version and integrity of the public Hub release. The profile stage first calls the Hub's `sync` interface (available since dsh-hub CLI 0.3.0) so Hub pulls the bundle from npm immediately instead of waiting for the hourly sync; after the sync it still requires Hub to list that exact version. Claiming still needs the publisher console, and login uses `dsh-hub login`.
+
+### Desktop release candidate and publication
+
+The Desktop package is qualified separately from the terminal runtime. Build it
+with Node 24 in an independent directory:
+
+```sh
+npm run prepare:desktop
+DSCODE_TEST_CHROME="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \
+  npm run release:desktop -- .research/desktop-release-runtime
+node scripts/verify-desktop-registry.mjs .research/desktop-release-runtime --local
+```
+
+`prepare:desktop` provisions exact direct dependencies with install scripts
+disabled; it refuses to overwrite an unrelated project. `release:desktop`
+builds a public candidate only for Harness 0.2.0-rc.2, then unpacks those exact
+bytes for Host startup/restart, browser, annotation, isolation and authenticated
+Hub RPC checks. The source runtime is checked for unintended changes. The
+local install rehearsal additionally resolves dependencies in a new native
+Harness profile and boots the installed package; it does not establish public
+npm availability or drive the Electron UI.
+
+Artifacts under `artifacts/desktop/release/` include the `.tgz`, SHA-256 file,
+installation README, release notes, candidate receipt and qualification record.
+This generated directory is replaced on each build. `make desktop` runs the
+preparation and qualification steps; `make release` includes it and requires
+`DSCODE_TEST_CHROME`.
+
+After the release gates pass:
+
+```sh
+npm run publish:desktop -- credentials
+npm run publish:desktop -- npm
+npm run publish:desktop -- hub
+npm run publish:desktop -- verify
+```
+
+Each phase checks the archive and receipt again. The npm phase publishes with
+`--tag preview`; an existing version is reusable only with identical integrity.
+The Hub phase syncs the package and requires the exact version, integrity and
+Desktop compatibility to resolve. The final phase downloads public bytes,
+checks their SHA-256, and installs the exact npm version into a new native
+Harness profile before booting it and checking the preset and Hub RPC. The
+result is saved as `artifacts/local/desktop-public-install.json`. No model
+account is used, and no real-model quality claim follows from these probes.
+
+The existing npm token must permit the new Desktop package. Successful `whoami`
+proves authentication only; the first publish establishes write permission.
+Desktop publication does not replace the terminal profile, create a DMG, or
+implement an automatic Desktop updater. GitHub Release attaches the Desktop
+archive, checksum and instructions alongside the terminal assets. Follow the
+[Plugin Hub guide](plugin-hub.md) for discovery and official management.
+
+### Login-free publishing (local machine)
+
+The account has auth-and-writes two-factor enabled, so `npm login`'s session token expires and every `npm publish` asks for a one-time code again. Use a **granular access token** instead, which the publish script picks up automatically:
+
+1. Generate a granular token on npm's Access Tokens page: tick *Bypass two-factor authentication*, grant Read and write only to `@toddzheng024/dscode`, `@toddzheng024/dscode-bundle` and `@toddzheng024/dscode-desktop` under Packages and scopes, and pick an expiry that suits you (repeat this step when it expires). Granular tokens can currently only be created on the website.
+2. `npm run publish:token store` and paste the token at the `security` password prompt. It goes into the login keychain (service `dscode-npm-publish`) and never into `~/.npmrc`, the command line or the shell history.
+3. `npm run publish:token check` confirms the token authenticates as `toddzheng024`.
+
+After that `npm run publish:hub -- bundle|launcher` takes the token from the keychain and hands it to npm through a one-off temporary `--userconfig`, so no login and no one-time code are needed. A temporary environment can override with `NPM_PUBLISH_TOKEN`; with neither present it falls back to the original interactive flow. `npm run publish:token remove` deletes the keychain token.
+
+npm has announced that publishing directly with a bypass-2FA token is retired in January 2027; from then local publishing has to move to trusted publishing (OIDC) in CI.
+
+### GitHub Actions
+
+Two workflows:
+
+- `.github/workflows/checks.yml`: runs `npm run check` on `macos-14` for every push/PR (a matrix of Node 22.19.0 and 24) and uploads the coverage artifacts; a newer push to the same ref cancels the previous run.
+- `.github/workflows/release.yml`: on a `v*` tag push (or a manual `workflow_dispatch`) it runs the `build` job first — `npm run check` → `npm run build:packages` → `npm run release:hub` → `npm run verify:hub` — uploading `artifacts/npm` and `artifacts/local/hub-verification.json` as the `release-candidates` artifact. A separate `desktop` job prepares Harness 0.2.0-rc.2 and verifies the exact public Desktop archive with real Chrome, then uploads `desktop-candidate`. The `publish` job depends on both jobs and is attached to the `release` environment (add required reviewers under repository Settings → Environments for manual approval).
+
+Publish credentials live in repository Secrets (Settings → Secrets and variables → Actions):
+
+| Secret | Purpose |
+| --- | --- |
+| `DSH_HUB_TOKEN` | Hub CI credential. `@dsh-plugin-hub/cli`'s `getAccessToken()` prefers it, so the pipeline runs no device login and does not depend on a 5-minute WorkOS access token. |
+| `NPM_PUBLISH_TOKEN` | npm granular token (tick *Bypass two-factor authentication*, granting Read and write to `@toddzheng024/dscode`, `@toddzheng024/dscode-bundle` and `@toddzheng024/dscode-desktop`, including permission to create the Desktop package on its first publication). `npm run publish:hub` writes it into a one-off `--userconfig` that never touches disk or the shell history. |
+
+Publishing runs in the three documented stages, each re-verifying the hashes checked above: `publish:hub -- bundle` → `publish:hub -- profile` (sync Hub from npm first, then require that exact version to resolve) → `publish:hub -- launcher`. **The launcher always follows the bundle and the public Hub release**, or the user's first launch fails. Claiming a new package in the Hub console is still manual; when the tag and the `package.json` version disagree the `build` job fails outright and nothing is published.
+
+Manual dry run: Actions → Release → Run workflow with both switches left at `false`, which only builds and verifies the candidate artifacts without publishing.
+
+Credential check only: Actions → Release → Run workflow with `verify_credentials` ticked. It runs the full `build` job, then enters the `publish` job and uses `node scripts/check-publish-credentials.mjs` to do a **read-only** check — whether the npm token authenticates as `toddzheng024`, whether the Hub token can read the `dscode` profile, and whether the current version number is still free on npm — then stops without publishing anything. The check fails when the version is already on npm, which is exactly what blocks "push a tag after forgetting to bump the version".
+
+The Hub stage (`profile`) uses the WorkOS session written by `dsh-hub login` into `~/.dsh/.hub/auth.json`; the access token lasts 5 minutes and the script refreshes it automatically with the refresh token, so `dsh-hub login` is only needed again once the refresh token expires.