@ddtcorex/dsh-maestro-supervisor 0.6.8 → 0.7.1

package/lib/skill-provider.js

@@ -0,0 +1,70 @@
+import { readFile, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+const SKILL_NAME = 'dsh-safe-restart';
+/** Minimal frontmatter reader for our own SKILL.md — enough to serve the provider contract. */
+function parseFrontmatter(raw) {
+    const m = raw.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+    if (!m)
+        return { name: SKILL_NAME, description: '', body: raw };
+    const fm = m[1].split('\n').reduce((acc, line) => {
+        const kv = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
+        if (kv)
+            acc[kv[1]] = kv[2].replace(/^["']|["']$/g, '');
+        return acc;
+    }, {});
+    return { name: fm.name || SKILL_NAME, description: fm.description || '', body: m[2] };
+}
+export function makeSkillProvider(skillsDir) {
+    return {
+        // The dsh-skill service attributes candidates through the provider
+        // object's own `name` (maestro-skills returns `{ name, list, get }`); a
+        // missing name surfaces at runtime as `skill provider "undefined" returned
+        // skill ... for provider "maestro-supervisor"` and fails every turn.
+        name: 'maestro-supervisor',
+        async list(_options) {
+            const entry = join(skillsDir, SKILL_NAME);
+            const st = await stat(entry).catch(() => null);
+            if (!st?.isDirectory())
+                return [];
+            const skillFilePath = join(entry, 'SKILL.md');
+            const fileSt = await stat(skillFilePath).catch(() => null);
+            if (!fileSt?.isFile())
+                return [];
+            const raw = await readFile(skillFilePath, 'utf-8').catch(() => null);
+            if (raw === null)
+                return [];
+            const { name, description } = parseFrontmatter(raw);
+            return [{
+                    name,
+                    description,
+                    invocation: { modelInvocable: true, userInvocable: true },
+                    source: 'custom',
+                    provider: 'maestro-supervisor',
+                    rank: 360,
+                    locator: skillFilePath,
+                    path: skillFilePath,
+                    resourceBase: { kind: 'directory', path: entry },
+                    metadata: { name, description },
+                }];
+        },
+        async get(candidate, _options) {
+            try {
+                const raw = await readFile(candidate.path, 'utf-8');
+                const { name, description, body } = parseFrontmatter(raw);
+                return {
+                    name, description,
+                    invocation: candidate.invocation,
+                    source: candidate.source,
+                    provider: candidate.provider,
+                    resourceBase: candidate.resourceBase,
+                    path: candidate.path,
+                    content: body,
+                    metadata: candidate.metadata,
+                };
+            }
+            catch {
+                return undefined;
+            }
+        },
+    };
+}

package/lib/supervisor.d.ts

@@ -1,4 +1,5 @@
 import type { HealthState } from './health-poller.js';
+import type { RestartRequest } from './restart-guards.js';
 export interface SupervisorDeps {
     pollHealth: () => Promise<HealthState>;
     writeLKG: () => Promise<{
@@ -26,6 +27,7 @@ export interface SupervisorDeps {
     isPlannedRestartActive?: () => boolean | Promise<boolean>;
     writePlannedRestart?: (ttlMs?: number) => void;
     checkPlannedRestart?: () => boolean;
+    clearPlannedRestart?: () => void;
     runDebugAgent?: (opts: {
         reportPath: string;
         health: HealthState;
@@ -40,6 +42,8 @@ export interface SupervisorDeps {
     resumeSessions?: (ids: string[]) => Promise<{
         resumed: string[];
     }>;
+    readRestartRequest?: () => RestartRequest | undefined;
+    onRestartRequestHandled?: (req: RestartRequest) => void;
 }
 export declare function resumeViaRpc(ids: string[], fetchFn?: (url: string, init: RequestInit) => Promise<Response>): Promise<{
     resumed: string[];
@@ -53,9 +57,14 @@ export declare class Supervisor {
     private consecutiveDown;
     private consecutiveDegraded;
     private timer;
+    private restartRequestHandled;
+    private restartRequestTimer;
+    private awaitingHealthyBoot;
+    private pendingRestartRequest;
     constructor(deps: SupervisorDeps);
     private getWritePlannedRestart;
     private getCheckPlannedRestart;
+    private getClearPlannedRestart;
     restartWeb(): Promise<void>;
     private getRunDebugAgent;
     private getFindInterrupted;

package/lib/supervisor.js

@@ -5,7 +5,7 @@ import * as path from 'node:path';
 import * as os from 'node:os';
 import { resolveHarnessRoot } from './paths.js';
 import { readSupervisorConfig } from './config.js';
-import { writePlannedRestart as defaultWritePlannedRestart, checkPlannedRestart as defaultCheckPlannedRestart } from './restart-guards.js';
+import { writePlannedRestart as defaultWritePlannedRestart, checkPlannedRestart as defaultCheckPlannedRestart, clearPlannedRestart, PLANNED_RESTART_TTL_MS } from './restart-guards.js';
 import { buildKillStalePortsCommand } from './restart-guards.js';
 export async function resumeViaRpc(ids, fetchFn = globalThis.fetch) {
     const rpcId = crypto.randomUUID();
@@ -36,6 +36,10 @@ export class Supervisor {
     consecutiveDown = 0;
     consecutiveDegraded = 0;
     timer = null;
+    restartRequestHandled = false;
+    restartRequestTimer = null;
+    awaitingHealthyBoot = false;
+    pendingRestartRequest;
     constructor(deps) {
         this.deps = deps;
     }
@@ -45,6 +49,9 @@ export class Supervisor {
     getCheckPlannedRestart() {
         return this.deps.checkPlannedRestart ?? defaultCheckPlannedRestart;
     }
+    getClearPlannedRestart() {
+        return this.deps.clearPlannedRestart ?? clearPlannedRestart;
+    }
     async restartWeb() {
         this.getWritePlannedRestart()(30000);
         if (this.deps.restartWeb) {
@@ -291,6 +298,44 @@ export class Supervisor {
     }
     async tick() {
         const health = await this.deps.pollHealth();
+        // dsh_web_restart hand-off: the tool wrote a caller marker and handed the
+        // restart to the daemon (out-of-band). Honor one request per marker — one
+        // grace timer → restartWeb once → notify. The suppression marker and the
+        // single-flight latch are held until a post-restart health.up tick clears
+        // them, so the in-flight down of our own restart can never be mistaken for
+        // a crash and raced with a rollback + second restart by the crash path.
+        const restartReq = this.deps.readRestartRequest ? this.deps.readRestartRequest() : undefined;
+        if (restartReq?.callerSessionId && !this.restartRequestHandled) {
+            this.restartRequestHandled = true;
+            this.restartRequestTimer = setTimeout(() => {
+                void (async () => {
+                    try {
+                        // Debounce crash handling from the moment the restart is issued —
+                        // the crash path sets lastRollback the same way. A slow boot must
+                        // not be classified as a crash even after the suppression marker's
+                        // own 30s TTL runs out.
+                        this.lastRollback = this.deps.getTime ? this.deps.getTime() : Date.now();
+                        await this.restartWeb();
+                        // Supervisor.restartWeb() wrote a 30s marker; extend it past a slow
+                        // boot. It is cleared only once the boot proves healthy below.
+                        this.getWritePlannedRestart()(PLANNED_RESTART_TTL_MS);
+                        await this.deps.notify(`restarted dsh-web after self-restart by session ${restartReq.callerSessionId}`);
+                    }
+                    catch (e) {
+                        await this.deps.notify(`self-restart dsh-web failed: ${e?.message ?? String(e)}`).catch(() => { });
+                    }
+                    finally {
+                        // Hold the marker and latch until health.up: clearing here would
+                        // drop crash suppression mid-restart, and re-arming here would let
+                        // a still-present marker re-fire into a second restart.
+                        this.awaitingHealthyBoot = true;
+                        this.pendingRestartRequest = restartReq;
+                        this.restartRequestTimer = null;
+                    }
+                })();
+            }, 5000);
+            return;
+        }
         // DEGRADED: http 200 but log has plugin error → report + notify, rollback after consecutive threshold
         if (health.degraded) {
             this.consecutiveDown = 0;
@@ -404,6 +449,29 @@ export class Supervisor {
         if (health.up) {
             this.consecutiveDown = 0;
             this.consecutiveDegraded = 0;
+            // Post-self-restart boot proved healthy: clear the suppression marker,
+            // run the post-restart session-scan hook and re-arm the single-flight
+            // latch. A failed clear keeps the latch set so the same marker is never
+            // re-handled into a second restart.
+            if (this.awaitingHealthyBoot) {
+                this.awaitingHealthyBoot = false;
+                const req = this.pendingRestartRequest;
+                this.pendingRestartRequest = undefined;
+                let cleared = false;
+                try {
+                    this.getClearPlannedRestart()();
+                    cleared = true;
+                }
+                catch { }
+                if (cleared)
+                    this.restartRequestHandled = false;
+                if (req) {
+                    try {
+                        this.deps.onRestartRequestHandled?.(req);
+                    }
+                    catch { }
+                }
+            }
             // Throttle LKG writes to at most once per 5 minutes
             const now = this.deps.getTime ? this.deps.getTime() : Date.now();
             if (now - this.lastLKGWrite > 5 * 60 * 1000) {
@@ -543,5 +611,9 @@ export class Supervisor {
             clearInterval(this.timer);
             this.timer = null;
         }
+        if (this.restartRequestTimer) {
+            clearTimeout(this.restartRequestTimer);
+            this.restartRequestTimer = null;
+        }
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ddtcorex/dsh-maestro-supervisor",
-  "version": "0.6.8",
+  "version": "0.7.1",
   "description": "Supervisor daemon for DSH Web resilience — auto-detect crashes, rollback to LKG, report",
   "type": "module",
   "main": "./lib/index.js",
@@ -33,6 +33,7 @@
   },
   "files": [
     "lib",
+    "skills",
     "README.md",
     "cordis.patch.yml"
   ],

package/skills/dsh-safe-restart/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: dsh-safe-restart
+description: Use before updating any dsh-maestro-* client bundle or DSH Web asset, or before reloading the running dsh web host process; validate first and perform a user-approved host restart through the bundled guarded recipe. In-session agents use the `dsh_web_restart` tool; hand off to a human only if the tool is unavailable.
+compatibility: dsh
+---
+
+# Safe DSH Web Restart
+
+## Purpose
+
+One `dsh web` process serves both the live Web UI on port 3080 and the
+GitLab-webhook service on port 3000. A host restart drops the live socket and
+the in-flight turn, although sessions rehydrate from the append-only log when
+the browser reconnects. Treat a restart as disruptive: validate first and get
+explicit user consent before a real swap.
+
+## Classify the change before touching the live process
+
+- **Static asset in `apps/web/dist/`** — patch the asset and verify served
+  bytes with `curl`; no restart.
+- **Client plugin bundle** (client JavaScript, CSS, slots, React) — run that
+  package's `build:client`, confirm a bundle marker, then refresh the browser;
+  no host restart.
+- **Host Node library, `cordis.patch.yml`, or profile plugin composition** —
+  validate a candidate and restart only after the user says to do so.
+
+## Required preflight for a host restart
+
+1. Run relevant package tests and build steps, then check the output really
+   carries the expected marker.
+2. Dry-boot the candidate on an ephemeral port with an isolated `DSH_HOME`.
+   Keep the live process and its sessions/settings untouched. If the review
+   webhook conflicts on port 3000, exclude that provider for the candidate or
+   run a no-server composition check instead.
+3. Verify HTTP 200 and the new marker on the candidate. Retain last-known-good
+   assets until the real swap has passed post-swap checks.
+4. Ask for explicit consent and timing. “restart đi” is consent; silence is
+   not.
+
+## Run the bundled helper only after consent
+
+The skill loader provides this directory as the skill resource base. Substitute
+that real path for `<skill-resource-base>`; never use a copied, machine-specific
+path from documentation.
+
+```bash
+# Safe inspection only: resolves the serving tree but changes nothing.
+bash <skill-resource-base>/scripts/restart-dsh-web.sh \
+  --repo /path/to/deepseek-harness --dry-run
+```
+
+Run the `dsh_web_restart` tool instead of executing the helper — the helper is
+for external agents and humans. In-session agents must never run it from their
+own turn (see "Never do these" below).
+
+`--repo` may be replaced by `DSH_REPO`; `--log` or `DSH_RESTART_LOG` changes
+the append-only log destination. The helper refuses a real swap without
+`--confirm`, dynamically resolves listeners rather than trusting saved PIDs,
+and refuses to launch if ports are still occupied. `--dry-run` never runs
+`kill` or `setsid`.
+
+## Post-swap checks
+
+Do not read the top of an old append-only log as liveness evidence. Instead:
+
+1. Confirm exactly one healthy listener tree owns ports 3000 and 3080 with
+   `ss -tlnp`.
+2. Confirm HTTP 200 from port 3080.
+3. Check served bytes contain the **new**, unique marker; or make a fresh
+   browser/Playwright probe for the changed UI. Shared third-party markers are
+   not sufficient proof.
+4. If a marker or live behaviour is wrong, restore the retained last-known-good
+   assets and relaunch with the same guarded process.
+
+## Never do these
+
+- Kill the process from an inline agent shell; the killing action can terminate
+  that shell before it relaunches DSH.
+- **Never invoke this skill from inside a DSH chat session's agent turn.** The agent itself runs inside `dsh web`; killing `dsh web` from its own turn interrupts that turn (`interrupted` in the append-only log) and the `setsid nohup` relaunch never completes from the killed shell. If you are an agent, run the `dsh_web_restart` tool instead — it performs the swap from the safe side of the tree. Print the exact `setsid nohup ... --confirm` command only when the tool is unavailable, and only for the human to run in their own terminal; do not execute it yourself.
+- Restart for a client-only or static change.
+- Hard-code a PID or a local developer's workspace path.
+- Treat a 200 response alone as proof that a rebuilt plugin was loaded.
+
+## Agent handoff (required when you are an agent)
+
+If you are running inside `dsh web` (any `dsh-*` skill, `maestro-*` skill, or subagent), you **must not** execute the helper or the restart yourself:
+
+1. Run all preflight checks (`--dry-run`, `pnpm verify`, marker grep) and report the results.
+2. Run the `dsh_web_restart` tool instead of executing the helper — the helper is for external agents and humans.
+3. If the tool reports it is unavailable, print the exact detached `setsid nohup ... --confirm` command for the human to run; then wait for explicit human confirmation in a new terminal. The interrupted turn will rehydrate from the log when the browser reconnects — no data is lost.

package/skills/dsh-safe-restart/scripts/restart-dsh-web.sh

@@ -0,0 +1,279 @@
+#!/usr/bin/env bash
+# Restart the DSH Web process tree only after the caller has obtained consent.
+set -euo pipefail
+
+repo="${DSH_REPO:-}"
+log="${DSH_RESTART_LOG:-/tmp/dsh-web-restart.log}"
+# Coordination with dsh-web-supervisor (see workspace docs/specs/
+# 2026-08-28-supervisor-planned-restart-design.md): the supervisor treats a
+# down poll as a crash unless this marker is fresh, so it never races this
+# script's own kill -> dry-boot -> relaunch sequence with its own rollback.
+marker="${DSH_SUPERVISOR_MARKER:-$HOME/.dsh/.supervisor/planned-restart}"
+confirmed=false
+dry_run=false
+auto_mode=false
+
+dry_boot_and_verify() {
+  local dsh_repo="$1"
+  local port="${2:-0}"
+  local marker="${3:-}"
+  local dsh_home
+  dsh_home="$(mktemp -d)"
+  local log_tmp
+  log_tmp="$(mktemp)"
+  # ephemeral boot with isolated DSH_HOME
+  DSH_HOME="$dsh_home" pnpm --dir "$dsh_repo" exec dsh web --port "$port" --no-open >"$log_tmp" 2>&1 &
+  local pid=$!
+  local ok=false
+  for _ in $(seq 1 15); do
+    if curl -s "http://127.0.0.1:$port/" 2>/dev/null | grep -q "${marker:-}"; then
+      ok=true
+      break
+    fi
+    if ! kill -0 "$pid" 2>/dev/null; then break; fi
+    sleep 1
+  done
+  kill -TERM "$pid" 2>/dev/null || true
+  wait "$pid" 2>/dev/null || true
+  rm -rf "$dsh_home" "$log_tmp"
+  [[ "$ok" == true ]]
+}
+
+usage() {
+  cat <<'EOF'
+Usage: restart-dsh-web.sh --repo <deepseek-harness> [--log <path>] [--confirm|--auto] [--dry-run]
+
+Safely hand over the DSH Web process that owns ports 3000 and 3080.
+
+Options:
+  --repo <path>  DeepSeek Harness checkout (or set DSH_REPO).
+  --log <path>   Append-only launch log (or set DSH_RESTART_LOG).
+  --confirm      Permit a real process handover (human-gated). Required unless --dry-run.
+  --auto         Permit auto handover (supervisor, no consent prompt). Alias for --confirm with auto log prefix.
+  --dry-run      Print the resolved process tree; never stop or launch anything.
+  -h, --help     Show this help text.
+EOF
+}
+
+fail() {
+  printf '[restart] FAIL: %s\n' "$1" >&2
+  exit "${2:-1}"
+}
+
+while (($#)); do
+  case "$1" in
+    --repo)
+      (($# >= 2)) || fail '--repo requires a path' 64
+      repo="$2"
+      shift 2
+      ;;
+    --log)
+      (($# >= 2)) || fail '--log requires a path' 64
+      log="$2"
+      shift 2
+      ;;
+    --confirm)
+      confirmed=true
+      shift
+      ;;
+    --auto)
+      confirmed=true
+      auto_mode=true
+      shift
+      ;;
+    --dry-run)
+      dry_run=true
+      shift
+      ;;
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    *)
+      fail "unknown option: $1" 64
+      ;;
+  esac
+done
+
+[[ -n "$repo" ]] || fail 'provide --repo or DSH_REPO' 64
+[[ -f "$repo/package.json" ]] || fail "repo has no package.json: $repo" 64
+if [[ "$dry_run" != true && "$confirmed" != true ]]; then
+  fail 'refusing live restart without --confirm' 64
+fi
+
+for command in ss ps grep sort; do
+  command -v "$command" >/dev/null 2>&1 || fail "required command is unavailable: $command"
+done
+
+listener_pids="$({ ss -tlnp 2>/dev/null || true; } | grep -E ':(3000|3080)([[:space:]]|$)' | grep -oE 'pid=[0-9]+' | cut -d= -f2 | sort -u || true)"
+[[ -n "$listener_pids" ]] || fail 'no listeners found on ports 3000 or 3080'
+
+resolve_tree() {
+  local current="$1"
+  local parent command_line
+  while [[ -n "$current" && "$current" != 1 ]]; do
+    command_line="$(ps -o cmd= -p "$current" 2>/dev/null || true)"
+    # Never walk into a service manager: when dsh-web runs as a systemd
+    # --user unit (ExecStart=node ... directly, no intervening pnpm
+    # wrapper), the parent of the listener process IS the manager itself.
+    # Without this guard the loop keeps climbing (no "pnpm" match, parent
+    # != 1 yet) and includes the manager's own PID in tree_pids -- SIGTERM
+    # to it tears down every user unit, not just dsh-web (2026-08-28
+    # incident: killed the whole systemd --user session).
+    case "$command_line" in
+      *systemd\ --user*) break ;;
+    esac
+    printf '%s\n' "$current"
+    [[ "$command_line" == *pnpm* ]] && break
+    parent="$(ps -o ppid= -p "$current" 2>/dev/null | tr -d '[:space:]')"
+    [[ "$parent" == "$current" ]] && break
+    current="$parent"
+  done
+}
+
+tree_pids="$(for pid in $listener_pids; do resolve_tree "$pid"; done | sort -u)"
+[[ -n "$tree_pids" ]] || fail 'could not resolve a process tree for the listeners'
+
+# dsh-web.service has Restart=always: a raw `kill -TERM` on its MainPID looks
+# like a crash to systemd, which immediately relaunches it -- racing this
+# script's own relaunch for ports 3000/3080 (observed live 2026-08-28: restart
+# counter climbed past 20 before either side won). When systemd owns it,
+# defer the whole stop/start to systemctl instead of managing PIDs directly.
+systemd_managed=false
+systemctl --user is-active --quiet dsh-web.service 2>/dev/null && systemd_managed=true
+
+printf '[restart] listener pids: %s\n' "$(tr '\n' ' ' <<<"$listener_pids")"
+printf '[restart] process tree: %s\n' "$(tr '\n' ' ' <<<"$tree_pids")"
+printf '[restart] managed by: %s\n' "$([[ "$systemd_managed" == true ]] && echo 'systemd (dsh-web.service)' || echo 'raw process (no systemd unit)')"
+
+if [[ "$dry_run" == true ]]; then
+  printf '[restart] dry-run: no process will be stopped or launched\n'
+  exit 0
+fi
+
+# --- safe-guard: don't restart while tools are still running (torn prevention) ---
+# Scan for dangling open turns (turn/start without turn/end) within last 5m.
+# If found, wait up to 30s for them to finish, then require --auto to force.
+check_dangling() {
+  local count_dangling
+  count_dangling() {
+    node --input-type=module <<'NODE' 2>/dev/null || echo 0
+import fs from 'node:fs'
+import { execSync } from 'node:child_process'
+try{
+  const root = (process.env.DSH_HOME || (await import('node:os')).homedir() + '/.dsh') + '/sessions'
+  let count=0
+  for(const proj of fs.readdirSync(root)){
+    const pp = root + '/' + proj
+    try{ if(!fs.statSync(pp).isDirectory()) continue }catch{continue}
+    for(const sess of fs.readdirSync(pp)){
+      const p = pp + '/' + sess + '/session.jsonl.zstd'
+      try{ fs.statSync(p) }catch{continue}
+      try{
+        const st = fs.statSync(p)
+        if(Date.now() - st.mtimeMs > 5*60*1000) continue
+      }catch{continue}
+      try{
+        const out = execSync(`zstd -d -c ${JSON.stringify(p)} 2>/dev/null | tail -n 20`, {encoding:'utf8', timeout:2000})
+        const lastStart = out.lastIndexOf('"type":"turn/start"')
+        if(lastStart!==-1 && !out.slice(lastStart).includes('"type":"turn/end"')) count++
+      }catch{}
+    }
+  }
+  console.log(count)
+}catch{ console.log(0) }
+NODE
+  }
+  local dangling
+  dangling="$(count_dangling)"
+  if [[ "$dangling" != "0" && -n "$dangling" ]]; then
+    printf '[restart] WARN: %s dangling open turn(s) within 5m — tools may be running\n' "$dangling" | tee -a "$log" >&2
+    if [[ "$auto_mode" != true ]]; then
+      printf '[restart] waiting 30s for tools to finish (re-run with --auto to force)\n' | tee -a "$log" >&2
+      for _ in $(seq 1 30); do sleep 1; done
+      local dangling2
+      dangling2="$(count_dangling)"
+      if [[ "$dangling2" != "0" && -n "$dangling2" ]]; then
+        printf '[restart] still %s dangling after wait — aborting (use --auto to force)\n' "$dangling2" | tee -a "$log" >&2
+        fail "refusing restart with $dangling2 dangling turn(s) — tools still running" 64
+      fi
+    fi
+  fi
+}
+check_dangling
+
+mkdir -p "$(dirname "$log")"
+printf '[restart] stopping process tree: %s\n' "$(tr '\n' ' ' <<<"$tree_pids")" >> "$log"
+
+# Mark this as an intentional restart before the port goes down, so
+# dsh-web-supervisor's health poll does not race us with its own rollback.
+# Removed on every exit path (success or failure) via the trap.
+mkdir -p "$(dirname "$marker")"
+date -Iseconds > "$marker"
+trap 'rm -f "$marker"' EXIT
+
+if [[ "$systemd_managed" == true ]]; then
+  # systemctl stop is a clean, intentional stop -- Restart=always does not
+  # fire for it, unlike an out-of-band kill of the unit's MainPID.
+  printf '[restart] stopping dsh-web.service via systemctl\n' >> "$log"
+  systemctl --user stop dsh-web.service 2>>"$log" || fail 'systemctl --user stop dsh-web.service failed'
+else
+  kill -TERM $tree_pids 2>/dev/null || true
+
+  tree_stopped=false
+  for _ in $(seq 1 20); do
+    alive=false
+    for pid in $tree_pids; do
+      if kill -0 "$pid" 2>/dev/null; then
+        alive=true
+        break
+      fi
+    done
+    if [[ "$alive" == false ]]; then
+      tree_stopped=true
+      break
+    fi
+    sleep 0.5
+  done
+
+  if [[ "$tree_stopped" != true ]]; then
+    printf '[restart] process tree did not stop after TERM; sending KILL\n' >> "$log"
+    kill -KILL $tree_pids 2>/dev/null || true
+    sleep 1
+  fi
+fi
+
+for port in 3000 3080; do
+  if ss -tln 2>/dev/null | grep -q ":$port "; then
+    fail "port $port remains held; refusing to double-boot"
+  fi
+done
+
+command -v curl >/dev/null 2>&1 || fail 'required command is unavailable: curl'
+
+if [[ "$systemd_managed" == true ]]; then
+  printf '[restart] starting dsh-web.service via systemctl\n' >> "$log"
+  systemctl --user start dsh-web.service 2>>"$log" || fail 'systemctl --user start dsh-web.service failed'
+else
+  command -v setsid >/dev/null 2>&1 || fail 'required command is unavailable: setsid'
+  command -v pnpm >/dev/null 2>&1 || fail 'required command is unavailable: pnpm'
+
+  printf '[restart] launching DSH Web from %s\n' "$repo" >> "$log"
+  (
+    cd "$repo"
+    setsid nohup "$(command -v pnpm)" dsh web --no-open </dev/null >> "$log" 2>&1 &
+  )
+fi
+
+for _ in $(seq 1 90); do
+  # 401 is healthy: dsh-web is up but requires the browser token (matches
+  # dsh-web-supervisor's own health-poller convention since DSH 0.1.2).
+  code="$(curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1:3080/ || true)"
+  if [[ "$code" == 200 || "$code" == 401 ]]; then
+    printf '[restart] DSH Web is serving HTTP %s on port 3080\n' "$code"
+    exit 0
+  fi
+  sleep 1
+done
+
+fail 'DSH Web did not serve HTTP 200/401 on port 3080 before timeout'