Dor Tools Phase B: the tool Surface — a terminal and a browser on one Session

.gitignore

@@ -33,6 +33,7 @@ standalone/sidecar/dor-cli/
 standalone/sidecar/iframe-proxy.cjs
 standalone/sidecar/agent-browser-host.cjs
 standalone/sidecar/remote-host.cjs
+standalone/sidecar/tool-host.cjs
 standalone/sidecar/node_modules/
 standalone/node_modules/
 

AGENTS.md

@@ -44,7 +44,7 @@ Use one implementation map per spec: either an exhaustive `Files` / `Code Map` s
 - **`docs/specs/theme.md`** — Theme system: the two-layer CSS variable strategy, the consumed-token resolver, the terminal color contract, and the theme debugger.
 - **`docs/specs/dor-cli.md`** — The `dor` CLI staged onto every Dormouse terminal's `PATH`: bundling + env contract, `spawnAndCapture` rules for external binaries, control-socket plumbing, the Surface handle model, and the command set.
 - **`docs/specs/dor-browser.md`** — The unified browser surface: `BrowserPanel` with swappable `renderMode`, browser chrome, the agent-browser stack, and the iframe proxy + CSP boundaries. Builds on the handle model in dor-cli.md.
-- **`docs/specs/dor-tool.md`** — Dor Tools (design-stage): the `tool` Surface — a terminal and a browser on one Session spine — with its capability-gated verb model and OSC 367 contract. Only the capability gating is implemented.
+- **`docs/specs/dor-tool.md`** — Dor Tools: the `tool` Surface — a terminal and a browser on one Session spine — its capability-gated verbs, the port scan that grows the browser, `dormouse.yml` identity, the repo-trust gate, and OSC 367. Behind the `dormouse.flags.tools` flag.
 - **`docs/specs/vscode.md`** — VS Code host layer: webview hosting, webview ↔ Workspace mapping, persistence ordering, theme integration, CSP, and the build/dogfood pipeline. The transport protocol it speaks lives in transport.md.
 - **`docs/specs/standalone.md`** — Standalone (Tauri) host layer: the Rust ↔ Node-sidecar bridge, boot sequence, AppBar, persistence, shutdown ordering, and the build/dev workflow. The transport protocol it speaks lives in transport.md.
 - **`docs/specs/auto-update.md`** — Standalone auto-update: check → user-approved download → install-on-quit, the Baseboard update notice, Windows sidecar teardown, and per-platform quit behavior.
@@ -90,7 +90,7 @@ Specs are written ahead of the code on purpose: a new component's spec starts as
 - **Reservations.** When unbuilt design constrains present code — a reserved wire field, a reserved ref grammar, an additive-evolution guarantee — state that constraint in the body, marked `Reserved:`, pointing at the `## Future` item it serves. Test: if deleting the sentence would let someone break future compatibility today, it belongs in the body.
 - **Promotion is part of done.** Implementing a staged item is not finished until its text moves above the fold — rewritten from "will" to "is", with `Source of truth:` added — and the built portion is deleted from `## Future`. Never leave completed plan text (build orders, phase lists) below the fold; delete it — git history keeps the record.
 
-The mechanically checkable parts of these conventions are enforced by `scripts/spec-lint.mjs` (`pnpm lint:specs`, also the first step of the root `pnpm test`): every spec indexed here, `## Future` last, relative links/anchors resolving, backticked repo paths existing on disk, the leading glossary callout wherever its vocabulary is used, one implementation map per spec, scopes defined exactly once with references resolving, `Reserved:` paragraphs naming `## Future` or a scope, and every `*.rationale.md` pairing with its spec, keyed by that spec's headings, with no `## Future`. It also ratchets file size: every spec, rationale file, and this file carries a word budget in `scripts/spec-word-budgets.json`, and growth past it fails the lint — cut, or raise the budget deliberately in the same PR. `SELF_HOST.md` — the one spec living outside `docs/specs/` — rides the same checks.
+The mechanically checkable parts of these conventions are enforced by `scripts/spec-lint.mjs` (`pnpm lint:specs`, also the first step of the root `pnpm test`): every spec indexed here, `## Future` last, relative links/anchors resolving, backticked repo paths existing on disk, the leading glossary callout wherever its vocabulary is used, one implementation map per spec, scopes defined exactly once with references resolving, `Reserved:` paragraphs naming `## Future` or a scope, and every `*.rationale.md` pairing with its spec, keyed by that spec's headings, with no `## Future`. It also ratchets file size: every spec, rationale file, and this file carries a word budget in `scripts/spec-word-budgets.json`, and growth past it fails the lint — cut, or raise the budget deliberately in the same PR. This file's budget is split — conventions prose and each spec-index line are capped separately, so adding a spec never costs another spec's routing line. `SELF_HOST.md` — the one spec living outside `docs/specs/` — rides the same checks.
 
 Advisory spec/comment reviews follow `docs/prose-audit.md` (`pnpm audit:prose`).
 

docs/specs/dor-cli.md

@@ -119,6 +119,12 @@ on `dor-lib-common`. It owns three concerns:
   argument containing a literal `%VAR%`** — `cmd.exe` expands it on the way
   through a `.cmd` shim, an unavoidable batch limitation. Today's forwarded
   arguments (URLs, selectors, the host's hardcoded `eval` scripts) carry none.
+- **`git` is the second caller.** The host resolves a project's upstream for the
+  Dor Tools trust key (`docs/specs/dor-tool.md` -> Trust). `spawnAndCapture`
+  exposes no `cwd` and the sidecar's is `/` under a macOS `.app`, so the
+  directory travels in argv as `git -C <absolute path>` — a host-resolved
+  project root, never a raw string off the wire. Both subcommands are
+  repository-local, so no credential prompt can block on the closed stdin.
 - **`windowsHide`.** cross-spawn runs `.cmd` shims through `cmd.exe`; without it
   each spawn flashes a focus-stealing console window — and the panel's
   screenshot loop spawns one per stream-frame pulse, so a live page would
@@ -342,6 +348,13 @@ baseboard. `dor list` rows sort by the Workspace-stable `surface:N` ref, whose
 registry `Wall` owns and persists with the session, independent of Lath layout
 order.
 
+`dor tool` runs a command as a Dor Tool — a Surface that grows a browser in
+place once the command binds a port. It uses the `ensure` spawn path's
+mechanics but **not** its command+cwd matching: a tool has an identity only if
+a `dormouse.yml` entry gave it one. Source of truth: `dor/src/commands/tool.ts`,
+help snapshot `dor/test/snapshots/help/tool.md`; behavior is owned by
+`docs/specs/dor-tool.md`.
+
 **Port enumeration is opt-in.** When the request sets `includePorts` (`dor list
 --ports` / `--port`), the host calls `PlatformAdapter.getOpenPorts(id)`
 (`docs/specs/dor-browser.md` → Dev-Server Chip) for each terminal Surface in