dsh-web-lifecycle

A DSH web plugin that puts two buttons in the sidebar footer:

sidebar footer  →  [ ⟳ Restart ]     stop the server, bring an identical
                                      instance back on the same host/port,
                                      and reload this page
                →  [ ⏻ Shutdown ]    stop the server for good so the terminal
                                      is free, then close this tab

Both ask for confirmation first. No more switching to a terminal several times a day to restart the harness — and nothing to clean up when you are done for the night.

• Same port, same session. A restart pins the resolved port, so the browser cookie's authority is unchanged — you stay signed in and your open session comes back after the reload.
• Two restart transports. Works standalone (detached relaunch), and gets faster and terminal-friendly when launched through the bundled dshweb wrapper.
• No runtime dependencies. Only Node built-ins.
• Inert when unsupported. No webServer / no appExit → nothing mounts, the host is never affected.

Install

# from GitHub
dsh plugin --profile web add github:DDA-DIGITAL/dsh-web-lifecycle

# from a local checkout
dsh plugin --profile web add /path/to/dsh-web-lifecycle

# from npm, once published
dsh plugin --profile web add dsh-web-lifecycle

Then restart dsh web once so the host half loads, and refresh the page for the client half:

dsh --profile web --dump-config   # the row `web-lifecycle` should be listed

Restart

Launch mode	What happens
dshweb (supervised)	Exits with code 75; the wrapper relaunches in the same terminal in about a second.
plain dsh web (detached)	A coordinator in its own process session outlives the dying process, waits for the port to be released, spawns an identical dsh web, health-checks it, and logs the chain to $DSH_HOME/plugins-data/dsh-web-lifecycle/restart.log.

Either way the page waits for the origin to drop, waits for it to answer, then reloads itself.

Shutdown

Shutdown exits with code 0 — deliberately not 75 — so the wrapper's relaunch condition is false and your prompt comes back:

dshweb: dsh web stopped (exit 0); supervisor exiting

No coordinator is spawned, so nothing can bring the server back. Under plain dsh web the process simply exits (it was detached, so your terminal was already free).

About closing the tab

The plugin does try to close the tab for you (window.close()), and that works when the GUI runs as an installed PWA or app window. For an ordinary browser tab it will not work: browsers only let a page close windows that a script opened, and DSH hands the URL to your OS browser, so there is no opener.

So the tab is handled in two steps: try to close, then — if it is still there — show a full-screen card that says "dsh web has stopped", retitles the tab to dsh web stopped, and reminds you to press ⌘W / Ctrl+W. There is no auto-reload on shutdown: there is nothing left to load.

The supervisor wrapper (optional, recommended)

Mode A keeps the server attached to your terminal and makes restarts ~1 second:

install -m 0755 scripts/dshweb ~/bin/dshweb     # or /usr/local/bin
dshweb                                          # same flags as `dsh web`
dshweb --port 3080

The wrapper runs dsh web in a loop and treats exit code 75 as "relaunch me". Ctrl-C still works (SIGINT exits 130, which is not 75, so the loop stops), and a Shutdown exits 0, which also stops the loop. Without the wrapper the plugin still works — it just falls back to the detached relaunch.

Configuration

Defaults live in the plugin row (cordis.patch.yml) and are re-applied by the plugin itself:

- id: web-lifecycle
  config:
    confirm: true          # show the confirmation popover before either action
    allowShutdown: true    # false hides the Shutdown row entirely
    healthTimeoutMs: 30000 # how long a detached restart waits for the new server
    logToConsole: true     # log the plugin's decisions into the dsh web log

Override the row by id in $DSH_HOME/profiles/web/cordis.patch.yml — that file is watched live, so the change applies without a restart.

What an action costs

Both actions interrupt everything the process was running: active turns, subagents, background jobs and scheduled work. Sessions themselves are durable and reopen after a restart, but anything in flight is gone — which is why the confirmation popovers are on by default. Turn them off with confirm: false if you prefer a single click.

After a shutdown, the only way back is a terminal: dshweb or dsh web.

Troubleshooting

Symptom	What to do
The buttons are missing	Check dsh --profile web --dump-config lists web-lifecycle, then restart dsh web and refresh the page.
Overlay says "did not come back"	Read $DSH_HOME/plugins-data/dsh-web-lifecycle/restart.log; it ends with the failing startup output. Start the server manually with dsh web.
Red status dot	The channel is not answering — the host half is not mounted, or the page is stale. Refresh; if it persists, restart once from the terminal.
Restart works but the tab asks you to authenticate	The port changed. Do not start the server with --port 0, and keep the wrapper's flags identical to the original invocation.
Shutdown card stays open	Expected on an ordinary tab — press ⌘W. It closes by itself in a PWA/app window.
A supervisor (launchd/systemd/pm2) keeps resurrecting the server	Unsupported: shutdown stops the process, the supervisor starts it again.

How it works

• Host half (lib/index.js) registers a prefix route on webServer at /dsh-web-lifecycle with POST /status, POST /restart and POST /shutdown. Requests pass through the host's own browser fence (connection.requestRejection: Host/Origin trust plus the signed cookie), falling back to a loopback check.
• Browser half (lib/client.js) is served by the client-modules host at /plugins/dsh-web-lifecycle/client.js and registers one entry into the sidebar.footer.action slot. That slot's container is a flex row, so a second entry would render beside Restart rather than under it; both rows therefore live inside one entry and are stacked by the plugin's own column container.
• Exit codes are the protocol: 75 = relaunch me, 0 = stop. Unit tests pin both, because confusing them would turn Shutdown into a Restart.

Two host quirks are worked around deliberately, both found while building this:

1. connection.rpc.handle is unusable in @deepseek-ai/dsh 0.1.5-rc.1 — it reaches webServer through a context that never injected it, so every call throws cannot get property "webServer" without inject. Registering the route directly is exactly what the connection plugin does for its own /api route.
2. ctx.get("connection") returns undefined on a context that never declared it, which silently downgrades the browser fence to loopback-only. The service is therefore named in the inject list and read as a property, which is the only access shape cordis permits.

Development

npm test     # node --test: config, argv planning, waits, lifecycle policy, HTTP envelope, client bundle shape
npm run check

Layout:

lib/relaunch.js       pure helpers shared by both halves (argv planning, waits, ports, exit codes)
lib/index.js          host half: route, restart/shutdown policy, coordinator spawn
lib/restart-agent.mjs detached coordinator (detached restart only)
lib/client.js         browser half: footer rows, popovers, status card, tab close
scripts/dshweb        supervisor wrapper (exit 75 = relaunch, anything else = stop)
test/                 unit tests

License

MIT — see LICENSE.

Repository: https://github.com/DDA-DIGITAL/dsh-web-lifecycle