dsh-safe-restart

dsh-safe-restart

A macOS-only DSH host plugin that safely restarts the DSH process from inside
an Agent session. It terminates only the exact DSH listener process through a
detached helper, lets the browser reconnect through DSH's native
ConnectionController (no manual refresh), resumes the original persisted
session, and starts exactly one automatic continuation turn to verify the
restart and continue the interrupted task.

The plugin registers a single Agent tool, restart_dsh. There is no Web
button and no settings UI.

Design: docs/plans/2026-08-22-dsh-safe-restart-design.md

What it does

• One Agent tool: restart_dsh — schedules a safe restart of the current
  DSH host, bound to the invoking Agent's current session.
• macOS only — every other platform is rejected before any side effect.
• Verified on DSH 0.1.0-rc.8 — the recovery coordinator relies on host
  internals that are still moving in the rc cycle (agent/created,
  ctx.agents.resume setup, installModelSelection). End-to-end restart +
  auto-continuation was verified on 0.1.0-rc.8 (standalone profile, macOS).
  The declared range is >=0.1.0-rc.8 <0.2.0; anything outside it is untested
  and may need adapter work.
  After any DSH upgrade, re-verify: pnpm test, then one real
  restart_dsh round — confirm PID change, HTTP 200, journal consumed, and a
  continuation turn whose turn/end reason is completed (not error).
• Detached helper — the journal write is durable first, then a helper
  process is spawned detached and unref'd; it survives host termination,
  replaces the DSH process, and records the outcome.
• Native browser reconnect — after the host comes back, the existing Web
  client reconnects through DSH's built-in connection/resync loop. No manual
  page refresh and no "continue" message are needed.
• One automatic continuation turn — the same persisted session resumes
  with its preset and model selection, and exactly one plugin-sourced
  continuation message is delivered per restart.
• Interrupted streams are not resumed — the exact token stream that was
  running when the host dropped is not continued. DSH closes that turn as
  interrupted; recovery starts a new turn in the same session.

Tool schema

restart_dsh({
  "continue_after_restart": true,   // boolean, default true
  "continuation": "optional instruction" // string, optional, max 2000 chars
})

Field	Type	Default	Meaning
continue_after_restart	boolean	true	Whether to deliver one automatic continuation turn after recovery. Set false for a pure restart with no continuation.
continuation	string (optional)	—	Task-specific instruction for the single continuation turn (max 2000 chars). When omitted, the default instruction is: "Verify that DSH recovered successfully, then continue the pre-restart task using the current session and durable workspace state."

The target session is always the invoking Agent's current session; a caller
cannot name another session. The tool returns:

{ "restartId": "<uuid>", "scheduled": true, "continueAfterRestart": true }

Installation

Install from the plugin repository root:

dsh plugin --profile standalone add /path/to/dsh-safe-restart

The plugin activates on the next DSH start — restart_dsh is not loaded
until then. Use an already-validated external restart path (e.g. a codex /
safe-restart script that stops and relaunches DSH and verifies HTTP 200) for
that one activation restart, then verify http://127.0.0.1:<port> returns
HTTP 200 before continuing.

Usage

Ask the Agent to call restart_dsh. With the default
continue_after_restart: true, what the user sees is:

1. The host connection drops briefly (the tool response may be cut short).
2. The browser reconnects automatically through DSH's native
   ConnectionController — no manual refresh.
3. The original persisted session reappears with its preset and model.
4. Exactly one new assistant turn appears, carrying the restart ID marker
   [restartId: <uuid>], verifying recovery and continuing the task.

A restart with "continue_after_restart": false performs the same safe
restart and browser recovery but adds no continuation turn.

Safety

• Never killall — the helper terminates only the recorded PID, and only
  after verifying its exact command line against the launch identity recorded
  at schedule time (the current Node executable plus the DSH entry argument).
  An unrelated or unknown process is never touched.
• One active restart — a second restart_dsh while a record is in flight
  is rejected (restart already active).
• 60-second cooldown — a restart within 60 s of the most recent one is
  rejected (restart in cooldown).
• 30-second health timeout — after spawning the replacement, the helper
  polls the health endpoint for at most 30 s (PID exit and port release use a
  12 s budget).
• No retry loop — each restartId is executed at most once; a record that
  is not scheduled is refused, and a failed restart is never retried.
• Exactly-once delivery — before delivering the continuation, the
  coordinator scans the session's durable log for the restart ID marker; a
  previous delivery that crashed before the consumed transition is detected
  and consumed without re-delivering. An ambiguous window becomes
  delivery-uncertain instead of a blind retry.
• No secrets persisted — the journal and log carry no credentials and no
  environment values.
• Interrupted token stream is not resumed — the continuation is a fresh
  turn in the same session, never a replay of the interrupted generation.

Storage

All durable state lives under ~/.dsh/storages/dsh-safe-restart/:

Path	Purpose
active.json	The single in-flight restart record (atomic writes: temp file → fsync → rename).
.lock	Exclusive restart lock, created with open(..., 'wx'); one active restart at a time.
history/<restartId>.json	Terminal records, archived when a record reaches a terminal phase.
restart.log	Timestamped, non-secret lifecycle lines: restartId, old/new PID, port-release result, HTTP result, terminal phase.

Phases

Phase	Meaning
scheduled	The tool request was persisted; the detached helper has not claimed it yet.
restarting	The helper validated and terminated the old PID, spawned the replacement, and is waiting for health.
ready	The new host answered HTTP 200; newPid and readyAt are set. Waiting for the resumed session's Agent.
delivering	The continuation message was created and handed to the Agent; awaiting durable confirmation.
consumed	Terminal: exactly one continuation delivered (or, for continueAfterRestart=false, none) and archived.
failed	Terminal: the restart failed with a bounded, non-secret error message; never retried.
delivery-uncertain	Terminal: the continuation window was ambiguous (e.g. the host died between delivering and confirmation). Not blindly redelivered.

Troubleshooting

• failed record — check restart.log and the record's error field
  (e.g. PID validation failure, port not released, health timeout). The record
  is already archived; no action is required for future restarts.

• delivery-uncertain record — the continuation may or may not have been
  delivered. Check the session's durable log for the marker
  [restartId: <uuid>]:

  • marker present → the message was delivered; the record is archived, done.
  • marker absent → it was not delivered and will not be redelivered; decide
    whether to re-run the task manually.

• Stale lockless scheduled record — if the helper crashed before it
  could claim the record (or the claim failed), a scheduled record with no
  helper running and no lock can be left behind. Recovery polls it for a
  bounded window and then deliberately leaves it for inspection. It blocks new
  restarts (restart already active).

• Ready but no Agent (blocks subsequent restarts) — if a record reaches
  ready but the matching session's Agent never reappears (for example the
  session was deleted or the browser tab was never reopened), active.json
  stays in ready and every later restart_dsh is rejected until the
  record is resolved.

  Remedy (manual, after inspection):

  1. Inspect ~/.dsh/storages/dsh-safe-restart/active.json — note its
     restartId and phase — and the latest lines of
     ~/.dsh/storages/dsh-safe-restart/restart.log to see what happened.
  2. If the continuation marker [restartId: <restartId>] already exists in
     the session's durable log, the continuation was delivered; archive the
     record as consumed: move active.json to
     history/<restartId>.json with "phase": "consumed" and remove
     active.json.
  3. If the continuation was never delivered and never will be, archive the
     record with a terminal phase instead ("failed" or
     "delivery-uncertain"), then remove active.json.
  4. Check ~/.dsh/storages/dsh-safe-restart/.lock — it records the owning
     restartId. Remove the lock only when its restartId matches the
     archived record; never delete a lock owned by a different restart.
  5. Leave history/<restartId>.json and restart.log in place — they are
     the audit trail. The next restart_dsh is then allowed again.

Verification script

scripts/verify-real-restart.mjs is an external, read-only evidence collector
that runs outside the DSH process (plain Node ESM, zero dependencies). It
never performs a restart and never touches the live listener. It reads the
journal and probes the HTTP endpoint, then reports one JSON object:

{
  "oldPid": 111,            // replaced DSH PID, from the selected record
  "newPid": 222,            // healthy replacement PID (null when unknown)
  "pidChanged": true,       // newPid is set and differs from oldPid
  "http200": true,          // live GET http://127.0.0.1:<port>/ returned 200
  "phase": "consumed",      // lifecycle phase of the selected record
  "continuationCount": 1    // consumed records that delivered a continuation
}

node scripts/verify-real-restart.mjs --check-latest        # latest history record, default port 3081
node scripts/verify-real-restart.mjs --journal /path/to/journal --port 3000
node scripts/verify-real-restart.mjs --journal /tmp/fixture --port 0 --dry-run   # detection only, no HTTP

--dry-run prints the detection logic (listener PID via lsof -ti tcp:<port>
and a journal contents summary) without probing HTTP, so it can be exercised
without a live restart. It exits nonzero on malformed journal JSON, an
unusable listener detection, or unexpected errors. continuationCount counts
consumed records whose continueAfterRestart is true — per the design each
such record delivered exactly one continuation turn; pure-restart records
(false) delivered none and are not counted.

Uninstall

Remove the plugin with the remove counterpart of the install command, e.g.:

dsh plugin --profile standalone remove dsh-safe-restart

then restart DSH once so the tool is dropped. If you also want to remove the
durable state, delete ~/.dsh/storages/dsh-safe-restart/ after confirming no
restart is in flight (no active.json).

Recovery limitation

If the browser tab was closed during the restart, simply reopen it: DSH's
native reconnect restores the same persisted session (same preset, model,
and history). The continuation is delivered exactly once regardless of how
many times the tab reconnects.