Public: anyone can read this; the crew can change it.

The machine shell page is a Ghostty terminal in the browser that survives a reload and resizes cleanly #9492

Parked opened this
Closed without merging

Writers can now open a machine's shell in the browser. The terminal is ghostty-web 0.4.0, vendored, and a reload drops you back into the same tmux session. The page is at / / /machines/ /shell, the same path as the existing socket: the forge treats a plain GET there as a page and an upgrade as the socket.

Notes

stopped parked by the crew deploy 5e8027a

opened this

Writers can now open a machine's shell in the browser. The terminal is ghostty-web 0.4.0, vendored, and a reload drops you back into the same tmux session. The page is at /<owner>/<repo>/machines/<machine>/shell, the same path as the existing socket: the forge treats a plain GET there as a page and an upgrade as the socket.

What changed

  • List: /<owner>/<repo>/settings/machines now has Open shell on each machine. It drops the "browser terminal is not built yet" line.
  • Shell page (src/web/pages/machines.ts, route in src/http/server.ts): rendered on the server, writers only, like the socket. A reader gets 403. A private repository or an undeclared machine gets 404. It has a fixed-height terminal box and a status line that reserves its space, so nothing moves while it loads.
  • Vendored dependency: vendor/ghostty-web holds the npm package's files unchanged (MIT). Its README lists each file's size and sha256. The project README and NOTICE give the license and size: about 75 KB of script and a 423 KB WebAssembly file, loaded on that page only.
  • Assets (src/web/machine-term-asset.ts): the page's client is bundled with Bun.build into /assets/machine-term-<hash>.js. The build drops the copy of the WebAssembly that ghostty-web embeds in its own script, which takes the script from 680 KB to about 75 KB. The WebAssembly is served instead at /assets/ghostty-vt-<hash>.wasm as application/wasm. Both are cached immutable. staticResponse in src/web/asset.ts now accepts bytes as well as text.
  • Thin interface: Term in src/web/machine-term-wire.ts is just write, onData, resize and fit, and all the socket protocol is written against it. It sends the size when the socket opens, then one resize frame per new size, never the same size twice. Resizes are debounced by 100 ms in machine-term-client.ts.
  • Security policy: a new page option, wasm in src/web/layout.ts, adds 'wasm-unsafe-eval' to script-src on this page only. No other page's policy changes, and the security headers stay on.
  • Reload redraw (src/machines/shell.ts): a reload joins the running session, but the kernel only signals a size change, so a page reloaded at the same size would show a blank screen. resizePlan now briefly sets the terminal one row shorter, then back after 30 ms, so tmux redraws the whole screen. A newer size frame cancels the restore.

What to look at

  • resizePlan and the 30 ms timer are the only change to the shell server.
  • The build step that strips the embedded WebAssembly matches it with a regex. If a future ghostty-web version changes the format, the test catches it, because it checks the bundle has no embedded copy and stays under 200 KB.
  • Nothing here has run in a real browser yet. The reload redraw is tested as plain logic (resizePlan), not against a live tmux, and how the terminal looks and fits is unchecked.

Not done: no automatic reconnect (the status line says why the socket closed and to reload). I didn't try xterm.js. I couldn't call keep_plan, so the plan on #9472 wasn't updated.

Checks: bun scripts/gate.ts, bun x tsc --noEmit and bun scripts/design-lint.ts pass. 21 test files pass (389 tests), including the new test/machine-shell-page.test.ts, the existing shell suite unchanged, and the five cross files. The new test renders the page for a writer and refuses it for a reader. It also checks:

  • the security policy differs only on this page;
  • both assets are cached immutable and the script carries no copy of the WebAssembly;
  • the wiring sends one resize frame per size;
  • the redraw plan.

Try it: on this pull's preview, https://lab--<pull>--forge-trevato-apps.open-platform.sh, sign in as a writer and open /<owner>/<repo>/settings/machines. Press Open shell on standard, type, resize the window, then reload. A forge that can't hold a shell says so in the status line.

🤖 Generated with Claude Code

Closes #9472

3 earlier comments
commented

Writers can now open a machine's shell in the browser. The terminal is ghostty-web 0.4.0, vendored, and a reload drops you back into the same tmux session. The page is at /<owner>/<repo>/machines/<machine>/shell, the same path as the existing socket: the forge treats a plain GET there as a page and an upgrade as the socket.

What changed

  • List: /<owner>/<repo>/settings/machines now has Open shell on each machine. It drops the "browser terminal is not built yet" line.
  • Shell page (src/web/pages/machines.ts, route in src/http/server.ts): rendered on the server, writers only, like the socket. A reader gets 403. A private repository or an undeclared machine gets 404. It has a fixed-height terminal box and a status line that reserves its space, so nothing moves while it loads.
  • Vendored dependency: vendor/ghostty-web holds the npm package's files unchanged (MIT). Its README lists each file's size and sha256. The project README and NOTICE give the license and size: about 75 KB of script and a 423 KB WebAssembly file, loaded on that page only.
  • Assets (src/web/machine-term-asset.ts): the page's client is bundled with Bun.build into /assets/machine-term-<hash>.js. The build drops the copy of the WebAssembly that ghostty-web embeds in its own script, which takes the script from 680 KB to about 75 KB. The WebAssembly is served instead at /assets/ghostty-vt-<hash>.wasm as application/wasm. Both are cached immutable. staticResponse in src/web/asset.ts now accepts bytes as well as text.
  • Thin interface: Term in src/web/machine-term-wire.ts is just write, onData, resize and fit, and all the socket protocol is written against it. It sends the size when the socket opens, then one resize frame per new size, never the same size twice. Resizes are debounced by 100 ms in machine-term-client.ts.
  • Security policy: a new page option, wasm in src/web/layout.ts, adds 'wasm-unsafe-eval' to script-src on this page only. No other page's policy changes, and the security headers stay on.
  • Reload redraw (src/machines/shell.ts): a reload joins the running session, but the kernel only signals a size change, so a page reloaded at the same size would show a blank screen. resizePlan now briefly sets the terminal one row shorter, then back after 30 ms, so tmux redraws the whole screen. A newer size frame cancels the restore.

What to look at

  • resizePlan and the 30 ms timer are the only change to the shell server.
  • The build step that strips the embedded WebAssembly matches it with a regex. If a future ghostty-web version changes the format, the test catches it, because it checks the bundle has no embedded copy and stays under 200 KB.
  • Nothing here has run in a real browser yet. The reload redraw is tested as plain logic (resizePlan), not against a live tmux, and how the terminal looks and fits is unchecked.

Not done: no automatic reconnect (the status line says why the socket closed and to reload). I didn't try xterm.js. I couldn't call keep_plan, so the plan on #9472 wasn't updated.

Checks: bun scripts/gate.ts, bun x tsc --noEmit and bun scripts/design-lint.ts pass. 21 test files pass (389 tests), including the new test/machine-shell-page.test.ts, the existing shell suite unchanged, and the five cross files. The new test renders the page for a writer and refuses it for a reader. It also checks:

  • the security policy differs only on this page;
  • both assets are cached immutable and the script carries no copy of the WebAssembly;
  • the wiring sends one resize frame per size;
  • the redraw plan.

Try it: on this pull's preview, https://lab--<pull>--forge-trevato-apps.open-platform.sh, sign in as a writer and open /<owner>/<repo>/settings/machines. Press Open shell on standard, type, resize the window, then reload. A forge that can't hold a shell says so in the status line.

🤖 Generated with Claude Code

commented

Writers can open a machine's shell in the browser. The terminal is ghostty-web 0.4.0, vendored, and reloading the page drops you back into the same tmux session. The page is at /<owner>/<repo>/machines/<machine>/shell, the same path as the existing socket: a plain GET there gets the page, an upgrade gets the socket.

The first check failed because no commit had a Try: line. An empty commit now adds one, and scripts/gate.ts passes with FORGE_CHECK_BASE set to the base commit. The gate passed locally the first time because I ran it without FORGE_CHECK_BASE. No code changed in that commit.

What changed

  • List: /<owner>/<repo>/settings/machines now has Open shell on each machine.
  • Shell page (src/web/pages/machines.ts, route in src/http/server.ts): server-rendered, writers only, like the socket. A reader gets 403. A private repository or an undeclared machine gets 404. The terminal box has a fixed height and the status line reserves its space, so nothing moves while it loads.
  • Vendored code: vendor/ghostty-web holds the npm package's files unchanged (MIT). Its README lists each file's size and sha256, and the main README and NOTICE give the license and size.
  • Assets (src/web/machine-term-asset.ts): the client is bundled with Bun.build into /assets/machine-term-<hash>.js. ghostty-web embeds a base64 copy of its WebAssembly in its script; the build drops it, taking the script from 680 KB to about 75 KB. The WebAssembly is served on its own as /assets/ghostty-vt-<hash>.wasm (application/wasm, 423 KB). Both are cached immutable. staticResponse in src/web/asset.ts now accepts bytes as well as text.
  • Thin interface: Term (write, onData, resize, fit) in src/web/machine-term-wire.ts. The socket protocol, wire, is written against it. It sends the size when the socket opens, then one resize frame per new size; the client waits 100 ms for a resize to settle.
  • Security policy: a new page option, wasm in src/web/layout.ts, adds 'wasm-unsafe-eval' to script-src on this page only. No other page's policy changes.
  • Reload redraw (src/machines/shell.ts): the kernel only signals tmux when the size actually changes, so a page reloaded at the same size would stay blank. When a new connection's first size matches the current one, resizePlan makes the terminal one row shorter for 30 ms, then restores it, so tmux redraws the whole screen. A newer size frame cancels the restore.

What to look at

  • resizePlan and its 30 ms timer are the only change to the shell server.
  • The build step finds the embedded WebAssembly with a regex. If a future ghostty-web changes its format, the test fails: it checks the bundle has no embedded copy and stays under 200 KB.

Not done:

  • Nothing has run in a real browser. The reload redraw is tested as logic, not against a live tmux, and how the terminal looks and fits is unchecked.
  • No automatic reconnect: the status line says why the socket closed and to reload.
  • I didn't try xterm.js.
  • I couldn't call keep_plan, so the plan on #9472 isn't updated.

Checks: gate, bun x tsc --noEmit and bun scripts/design-lint.ts pass. 21 covering test files pass (389 tests), including the new test/machine-shell-page.test.ts, the existing shell suite unchanged, and the five cross files. The new test renders the page for a writer, refuses it for a reader, and also checks:

  • only this page's security policy changes;
  • both assets are cached immutable and the script has no embedded WebAssembly;
  • one resize frame is sent per size;
  • the redraw plan.

Try it: on this pull's preview, https://lab--9492--forge-trevato-apps.open-platform.sh:

  1. Sign in as a writer and open /<owner>/<repo>/settings/machines.
  2. Press Open shell on standard and type.
  3. Resize the window, then reload: the same session comes back.

A forge that can't hold a shell says so in the status line.

🤖 Generated with Claude Code

commented

Writers can now open a machine's shell in the browser. The terminal is ghostty-web 0.4.0, vendored, and reloading the page drops you back into the same tmux session. The page is at /<owner>/<repo>/machines/<machine>/shell, the same path as the existing socket: a plain GET there gets the page, an upgrade gets the socket.

Fixed since the last check

  • test/src-imports.test.ts: the vendored files were in a root vendor/ folder. The image ships only src/, so in production the WebAssembly read and the bundle would have failed. They now live in src/web/vendor/ghostty-web, and scripts/design-lint.ts skips that folder the same way it skips og/vendor.
  • test/security-floor-routes.test.ts: the new route has a :machine parameter the test couldn't fill. I changed the test, not the code: it now fills :machine with the built-in standard, so the new page is checked for the security headers like every other route.
  • Shard 7 (home-kpi-row and two in session-refusals): these pass here, alone and run together with the new test file. Nothing in this pull touches sessions or the home page, so I made no change for them.

What changed

  • List: /<owner>/<repo>/settings/machines now has Open shell on each machine.
  • Shell page (src/web/pages/machines.ts, route in src/http/server.ts): server-rendered, writers only, like the socket. A reader gets 403. A private repository or an undeclared machine gets 404. The terminal box has a fixed height and the status line reserves its space, so nothing moves while it loads.
  • Vendored code: the npm package's files, unchanged (MIT). Its README lists each file's size and sha256, and the main README and NOTICE give the license and size.
  • Assets (src/web/machine-term-asset.ts): the client is bundled with Bun.build into /assets/machine-term-<hash>.js. ghostty-web embeds a base64 copy of its WebAssembly in its script; the build drops it, taking the script from 680 KB to about 75 KB. The WebAssembly is served on its own as /assets/ghostty-vt-<hash>.wasm (application/wasm, 423 KB). Both are cached immutable.
  • Thin interface: Term (write, onData, resize, fit) in src/web/machine-term-wire.ts, with the socket protocol written against it. It sends the size when the socket opens, then one resize frame per new size; the client waits 100 ms for a resize to settle.
  • Security policy: a new page option, wasm in src/web/layout.ts, adds 'wasm-unsafe-eval' to script-src on this page only.
  • Reload redraw (src/machines/shell.ts): the kernel only signals tmux when the size actually changes, so a page reloaded at the same size would stay blank. When a new connection's first size matches the current one, resizePlan makes the terminal one row shorter for 30 ms, then restores it, so tmux redraws the whole screen. A newer size frame cancels the restore.

Not done:

  • Nothing has run in a real browser. The reload redraw is tested as logic, not against a live tmux, and how the terminal looks and fits is unchecked.
  • No automatic reconnect: the status line says why the socket closed and to reload.
  • I didn't try xterm.js.

Checks: gate (with FORGE_CHECK_BASE set), bun x tsc --noEmit and bun scripts/design-lint.ts pass. I ran 71 test files: the 60 that scan src/, the ones that failed, this pull's tests and the cross files. 798 tests pass. Three fail, all in test/looks.test.ts: Chromium can't open a socket in my sandbox, and this pull doesn't touch that code. The new test/machine-shell-page.test.ts renders the page for a writer, refuses it for a reader, and also checks:

  • only this page's security policy changes;
  • both assets are cached immutable and the script has no embedded WebAssembly;
  • one resize frame is sent per size;
  • the redraw plan.

Try it: on this pull's preview, https://lab--9492--forge-trevato-apps.open-platform.sh:

  1. Sign in as a writer and open /<owner>/<repo>/settings/machines.
  2. Press Open shell on standard and type.
  3. Resize the window, then reload: the same session comes back.

A forge that can't hold a shell says so in the status line.

🤖 Generated with Claude Code

commented

Parked by the crew: the check stayed red through 2 automatic tries

Sign in to join this conversation.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs