T-C8B9-dashboard-term-server-packaged
State: planning/draft · Impact: medium · Complexity: small
When sdlc runs from the packaged CLI (the plain-Node cli/sdlc.js bundle, or
the compiled binary), the dashboard’s Sessions page silently falls back to
read-only mode, because the terminal server it spawns can’t be found. Users who
install the plugin never get live terminals, and nothing tells them why.
startTermServer resolves term-server.mjs via moduleDir(import.meta.url).
From source, that is the dashboard service directory. Inside the bundle,
import.meta.url collapses to <plugin>/cli/sdlc.js, so it looks in
<plugin>/cli/. term-server.mjs isn’t listed in agent-pants.yaml’s assets
anyway, so it isn’t in any of the three packs, and the compiled binary’s asset
globs exclude *.js/*.mjs. The Sessions page detects the missing server and
degrades to read-only without any message.
The automated review of #2434 (the bundled-Node dashboard fix) flagged it as a pre-existing issue outside that PR’s scope.
Proposed
Section titled “Proposed”Under all three runtimes (bun from source, node cli/sdlc.js, and the compiled
binary), the Sessions page gets a working terminal server. Where a runtime
genuinely can’t host one, the page says so explicitly.
Approach
Section titled “Approach”- Resolve the terminal server through the embedded-root-aware
pluginLibDir()/pluginRootDir()helpers, notmoduleDir(import.meta.url), the same wayindex_template.etaresolves. - Ship
term-server.mjs, and anything it imports, as a plugin asset inagent-pants.yaml, and include it in the compiled binary’s asset set. Decide whether it stays a separate.mjsprocess or re-enters through a CLI route (sdlc dashboard term-server), as the dashboard’s detached child does since #2434. The CLI route avoids the asset entirely and reusessdlcSelfInvocation(). - Replace the silent fallback with a visible notice when the terminal server isn’t available.
- Extend
bundle-node.test.ts(and therelease.ymlbinary smoke) to check that the terminal server starts under the packaged CLI.
| Area | Note |
|---|---|
solutions/ontological/lib/services/dashboard/ | startTermServer and the terminal-server module |
solutions/ontological/lib/util/plugin-root.ts | the asset-root and self-invocation helpers |
solutions/ontological/agent-pants.yaml | pack asset list |
solutions/ontological/scripts/build-binary.ts | compiled-binary asset globs |
packages/ts/dashboard-spa/ | the Sessions page fallback notice |
Acceptance criteria
Section titled “Acceptance criteria”- AC-1: under
node cli/sdlc.js dashboard start, the Sessions page opens a live terminal. A bundle-level test asserts that the terminal server starts. - AC-2: the same holds under the compiled binary. The
release.ymlbinary smoke covers it. - AC-3: when the terminal server can’t start, the Sessions page shows an explicit notice instead of silently going read-only.
Out of scope
Section titled “Out of scope”- Embedding PTYs in hosts other than the dashboard; hosts keep linking out (P12 decision).
Dependencies
Section titled “Dependencies”- #2434, which introduces
sdlcSelfInvocation()and the bundle-level dashboard test this builds on.
Discovery context
Section titled “Discovery context”The automated review on #2434, 2026-09-29, raised it as an FYI.