Skip to content

Correct the transport, VS Code, and standalone specs; retire persistsSession - #711

Draft
nedtwigg wants to merge 3 commits into
specs-terminal-auditfrom
specs-host-audit
Draft

nedtwigg wants to merge 3 commits into
specs-terminal-auditfrom
specs-host-audit

Conversation

@nedtwigg

@nedtwigg nedtwigg commented Sep 20, 2026

Copy link
Copy Markdown
Member

Spec audit, group 3 (transport / vscode / standalone / auto-update). Stacked on #710 (the spec-audit PRs merge in order #708#715); independent of the alert series. Touches one line of AGENTS.md (the harness pointer).

Commit 1 — docs and comments. Corrections: the VS Code extension-host-crash row of the governing rule (it restores structure via workspaceState, not Fresh); the persisted-surface enumeration gains tool; the Windows quit-flow step number; AlertSettingsHost installs two settings, not one; the sidecar has five shutdown steps; the reconnection-token clause that contradicted "every host is multi-webview"; the async fn vs command(async) rule; the CORS-preflight carve-out in the harness; the burrow:command nesting; payload shapes in the arrival queue; and more. Condensed: agent-recovery mechanism (≈600 words across three specs) → the modules that already carry it verbatim; peer-link mechanism → peer-link.ts; the browser-dev harness section moved from transport.md to standalone.md (nothing adapter-agnostic referenced it); duplicate rules across the three specs → pointers. standalone.md's 1,150-word "Trigger interception" split into "Quit protocol" / "Teardown ordering".

Commit 2 — code.

  • persistsSession deleted: no shipping adapter answered false, and its doc comment stated the governing rule backwards.
  • SIDECAR_RUNTIME_DEPS now covers optionalDependencies, so the inlining assertion actually covers the six @node-datachannel/<platform> packages.
  • The dev harness printed a session name it never created; it now prints the --key for the inside-Dormouse path.
  • The tautological PEER_REPLY_BUDGET_MS pin deleted.

Budgets: transport 6250→5500, vscode 7550→7200, auto-update 1200→1150, standalone 10700→11500 (the harness section moved in). Net −242 words.

Deferred: collapsing the two app-global store channels (four-host refactor), the burrow:askDelivered fold, AWAITING_REPLAY_MAX, the Windows node.exe variants, restart-refused as a field.

🤖 Generated with Claude Code

nedtwigg and others added 2 commits September 20, 2026 00:44
…chanism to the modules that own it

The browser-dev harness is standalone's, not the adapter-agnostic
protocol's, so its section moves from transport.md to standalone.md with
every pointer updated. Agent-recovery capture, the peer-link
bind-as-lease walk and the peer-link trust handshake keep their rules in
the specs and lose the mechanism paragraphs the modules already carry
verbatim; the two sentences those comments lacked are added there.

Corrections against the code: a VS Code extension-host crash restores
structure rather than starting fresh, since the periodic save writes
workspaceState; a snapshot pane may be a tool, and a save probes every
non-browser pane's cwd; a token-less reconnect answer is taken because
the hosts that do not echo run one collector per realm, not because they
have one webview; standalone's boot sequence sets the window label
first, installs the window-close listener, boots a tear-out and arms
Workspace moves after the restore, and checks for updates in main alone;
the sidecar's shutdown has five steps; a blocking Tauri command must be
async in either form; quit-teardown is an event; the Windows SIGTERM
note belongs to step 3; an arrival carries allIds and its journal record
carries settled; the bare-Wall default id comes from wrapSessionInWindow;
standalone's drag controller must not assume in-range pointer
coordinates; only the two recovery answers ride respondAsync; the
updater log tail is 10,000 bytes in both specs; VS Code installs
whatever AlertManager consumes rather than only inactivityTimeoutMs, its
shipped command set is named where the manifest is described,
burrow:command wraps its payload, and HANDSHAKE_BUDGET_MS and the PTY
route table are attributed to peer-link.ts.

The quit flow splits into Trigger interception / Quit protocol /
Teardown ordering, the duplicated Terminal context host operations
sections fold into transport.md, the VS Code webview-hosting diagram
defers to transport.md's, auto-update's file table keeps the five files
a reader opens first, and three cross-spec duplicates become pointers.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
…and name the harness key

`persistsSession` was a gate no shipping adapter ever opened: both
standalone adapters answered `true`, which is what absent already reads
as, and the only `false` in the tree was a test fixture. The member, the
gate above the record build, both adapters' declarations, the two tests
that pinned `true`, and the transport.md row go; the doc comment that
had the rule backwards goes with them. A future non-persisting host
reintroduces the gate in one line.

The sidecar's `external` list read only `dependencies`, so the six
`@node-datachannel/<platform>` packages — `optionalDependencies`,
because only one installs on any machine — were neither external nor
covered by `assertNothingInlined`, which claimed to assert the addon was
not inlined and did not. Both keys are read now.

`PEER_REPLY_BUDGET_MS` is defined as `ASK_BUDGET_MS + 2_000`, so the
test asserting it is the larger could never fail; the argument moves to
the constant's own comment and the test goes.

The harness printed `dormouse.1.<key>` for a run that launched
`dor ab --key`, whose session the holding Workspace namespaces — a name
nothing ever created. It prints the key it passed instead, and the test
pins that rather than the mismatch.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@cloudflare-workers-and-pages

cloudflare-workers-and-pages Bot commented Sep 20, 2026

Copy link
Copy Markdown

Deploying mouseterm with  Cloudflare Pages  Cloudflare Pages

Latest commit: a0dfe6e
Status: ✅  Deploy successful!
Preview URL: https://987178f5.mouseterm.pages.dev
Branch Preview URL: https://specs-host-audit.mouseterm.pages.dev

View logs

@dormouse-bot dormouse-bot left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Feedback on work in progress, not a merge verdict — mark the PR ready when you want the full review.

One finding, inline: the new native-dev aside under "Standalone browser-dev harness" contradicts the runDev rule two bullets above it.

Comment thread docs/specs/standalone.md

`pnpm innerdogfood` starts the standalone sidecar directly, a localhost-only HTTP bridge, and Vite with `VITE_DORMOUSE_BROWSER_DEV_HOST`, then opens the app URL in an `agent-browser` session. The browser build uses `BrowserSidecarAdapter` instead of `TauriAdapter` whenever that env var is present.

- **Must bind OS-assigned ports for Vite and the HTTP bridge by default** — native dev keeps `tauri.conf.json`'s `1420` unless `runDev` overrides it (above).

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This has the default backwards. pnpm tauri dev goes through tauri.mjs, which routes dev to runDev, and runDev overlays devUrl with the origin startDevVite bound on port 0 — so an ordinary native dev run is already OS-assigned. tauri.conf.json's 1420 is reached only when runDev is bypassed, which is what the bullet two above says: "Direct pnpm exec tauri dev keeps tauri.conf.json's defaults." As written, the two rules disagree about which path is the default.

The replacement fits the ratcheted 11500-word budget (pnpm lint:specs passes with it applied).

Suggested change
- **Must bind OS-assigned ports for Vite and the HTTP bridge by default** native dev keeps `tauri.conf.json`'s `1420` unless `runDev` overrides it (above).
- **Must bind OS-assigned ports for Vite and the HTTP bridge by default**, as native dev does: `tauri.conf.json`'s `1420` is what only a direct `pnpm exec tauri dev` keeps (above).

# Conflicts:
#	scripts/spec-word-budgets.json
@nedtwigg
nedtwigg changed the base branch from main to specs-terminal-audit September 20, 2026 08:17
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants