@ddtcorex/dsh-maestro-supervisor 0.7.10 → 0.8.2

package/lib/health-poller.js

@@ -1,18 +1,12 @@
-import { checkPlannedRestart } from './restart-guards.js';
+import { checkPlannedRestart, BOOT_BOUNDARY_MARKER } from './restart-guards.js';
 import { execSync as execSyncImpl } from 'node:child_process';
+/**
+ * Wall-clock epoch ms of the current dsh-web unit start, or undefined when
+ * systemd does not manage the unit (portable host) or the lookup is disabled.
+ * `ActiveEnterTimestampMonotonic` is deliberately gone: a monotonic reading
+ * cannot be compared with a timestamp-less append-only log.
+ */
 export function getActiveEnterMs() {
-    if (process.env.VITEST)
-        return undefined;
-    try {
-        const out = execSyncImpl('systemctl --user show -p ActiveEnterTimestampMonotonic dsh-web.service 2>/dev/null', { encoding: 'utf8' });
-        const m = out.match(/ActiveEnterTimestampMonotonic=(\d+)/);
-        if (m)
-            return Number(m[1]);
-    }
-    catch { }
-    return undefined;
-}
-export function getActiveEnterWallMs() {
     if (process.env.VITEST)
         return undefined;
     try {
@@ -30,25 +24,9 @@ export function getActiveEnterWallMs() {
     catch { }
     return undefined;
 }
-function isRecentlyStarted(opts, wallMs) {
-    if (process.env.VITEST)
-        return false;
-    const now = Date.now();
-    // 30s grace after ActiveEnterTimestamp (wall clock) — covers manual systemctl start without marker
-    const wall = wallMs ?? (() => {
-        try {
-            const fn = opts.getActiveEnterWallMs;
-            if (typeof fn === 'function')
-                return fn();
-            return getActiveEnterWallMs();
-        }
-        catch {
-            return undefined;
-        }
-    })();
-    if (typeof wall === 'number' && now - wall < 30000)
-        return true;
-    return false;
+/** @deprecated kept for callers; identical to getActiveEnterMs(). */
+export function getActiveEnterWallMs() {
+    return getActiveEnterMs();
 }
 // Specific parse/boot-failure markers only. Bare 'JSON'/'YAML' were removed
 // (2026-08-31): they matched any line whose payload merely *contained* those
@@ -69,6 +47,92 @@ const ERROR_PATTERNS = [
     'EADDRINUSE',
     'address already in use',
 ];
+/**
+ * Decide whether the current unit start can already be judged.
+ *
+ * `activeEnterAtMs` is WALL-CLOCK epoch ms from
+ * `systemctl --user show -p ActiveEnterTimestamp dsh-web.service`.
+ * Deliberately NOT `ActiveEnterTimestampMonotonic`: a monotonic reading can
+ * never be compared against an append-only log that carries no timestamps, and
+ * that mismatch is why the previous scan filter silently fell through and let
+ * the previous boot's crash text be read as this boot's (incident 2026-09-13).
+ *
+ * - 'unknown' — no boot anchor (systemd absent, lookup disabled, clock skew):
+ *               behave exactly as before the fix; never suppress anything.
+ * - 'booting' — the unit started less than `bootGraceMs` ago and has not yet
+ *               proven itself by actually serving a request: weak failures are
+ *               suppressed and log lines are inconclusive.
+ * - 'settled' — the boot proved itself, or the grace window expired: judge
+ *               normally.
+ */
+export function bootFreshness(opts) {
+    const { activeEnterAtMs, now, bootGraceMs, probeSucceeded } = opts;
+    if (activeEnterAtMs === undefined || !Number.isFinite(activeEnterAtMs))
+        return 'unknown';
+    if (now < activeEnterAtMs)
+        return 'unknown';
+    if (probeSucceeded)
+        return 'settled';
+    return now - activeEnterAtMs < bootGraceMs ? 'booting' : 'settled';
+}
+/**
+ * Classify a fetch failure by what it says about the process.
+ *
+ * 'refused' — nothing is listening, so the process is gone: a strong down
+ *             signal that must never be masked by a boot grace.
+ * 'timeout' — something may be alive but slow: weak, only meaningful once the
+ *             boot grace expired.
+ * 'other'   — anything we cannot attribute.
+ *
+ * Walks the `cause` chain because undici surfaces a refused connection as
+ * `TypeError: fetch failed` with the real `ECONNREFUSED` on `cause`.
+ */
+export function classifyFetchFailure(err) {
+    const parts = [];
+    let cur = err;
+    for (let depth = 0; cur != null && depth < 5; depth++) {
+        if (typeof cur === 'string') {
+            parts.push(cur);
+            break;
+        }
+        const code = typeof cur.code === 'string' ? cur.code : '';
+        const name = typeof cur.name === 'string' ? cur.name : '';
+        const message = typeof cur.message === 'string' ? cur.message : '';
+        parts.push(`${code} ${name} ${message}`);
+        cur = cur.cause;
+    }
+    const text = parts.join(' ').toLowerCase();
+    if (/econnrefused|connection refused|ehostunreach|enetunreach/.test(text))
+        return 'refused';
+    if (/abort|timed? ?out|etimedout|und_err_connect_timeout/.test(text))
+        return 'timeout';
+    return 'other';
+}
+export const SUCCESS_MARKER = 'dsh web: http';
+/** Index of the last boot-boundary line in the tail, or -1 when it predates the tail. */
+export function lastBootBoundaryIndex(lines) {
+    for (let i = lines.length - 1; i >= 0; i--) {
+        if (lines[i].includes(BOOT_BOUNDARY_MARKER))
+            return i;
+    }
+    return -1;
+}
+/** Index of the last "dsh web: http" success marker (`lowerLines` must be lower-cased). */
+export function lastSuccessMarkerIndex(lowerLines) {
+    for (let i = lowerLines.length - 1; i >= 0; i--) {
+        if (lowerLines[i].includes(SUCCESS_MARKER))
+            return i;
+    }
+    return -1;
+}
+/** Wall-clock ms parsed from a boot-boundary line, or undefined when unparseable. */
+export function parseBootBoundaryMs(line) {
+    const m = /boot-boundary\s+(\S+)/.exec(line);
+    if (!m)
+        return undefined;
+    const ms = Date.parse(m[1]);
+    return Number.isNaN(ms) ? undefined : ms;
+}
 export async function pollHealth(opts = {}) {
     // 5s was too tight for a busy plugin-tree boot: a lone AbortError from a slow
     // (but otherwise fine) response was indistinguishable from a real crash, and
@@ -78,15 +142,19 @@ export async function pollHealth(opts = {}) {
     // high load (loadavg 12) stalls; configurable via domains.supervisor.pollTimeoutMs.
     // If opts.timeoutMs is not injected, read from supervisor config (maestro settings).
     let effectiveTimeout = opts.timeoutMs;
-    if (effectiveTimeout === undefined) {
+    let bootGraceMs = opts.bootGraceMs;
+    if (effectiveTimeout === undefined || bootGraceMs === undefined) {
         try {
             const { readSupervisorConfig } = await import('./config.js');
             const cfg = await readSupervisorConfig();
-            if (typeof cfg.pollTimeoutMs === 'number' && cfg.pollTimeoutMs > 0)
+            if (effectiveTimeout === undefined && typeof cfg.pollTimeoutMs === 'number' && cfg.pollTimeoutMs > 0)
                 effectiveTimeout = cfg.pollTimeoutMs;
+            if (bootGraceMs === undefined && typeof cfg.bootGraceMs === 'number' && cfg.bootGraceMs > 0)
+                bootGraceMs = cfg.bootGraceMs;
         }
         catch { }
         effectiveTimeout ??= 20000;
+        bootGraceMs ??= 180000;
     }
     const fetchFn = opts.fetch ?? defaultFetch(opts.url ?? 'http://127.0.0.1:3080/', effectiveTimeout);
     const psAliveFn = opts.psAlive ?? defaultPsAlive;
@@ -111,64 +179,64 @@ export async function pollHealth(opts = {}) {
     catch {
         // ignore log read errors
     }
-    // Suppression gate: during 30s planned-restart window, boot transients are expected.
-    // Fetch failures are treated as suppressed (up:true), and log scanning is windowed.
+    // Suppression gate: an in-flight planned restart, or a boot that has not yet
+    // proven itself, means transients are expected. A refused connection is
+    // never suppressed: nothing is listening, so the process is gone (D2).
     const suppressed = checkPlannedRestart();
-    const recentlyStarted = isRecentlyStarted(opts);
-    const graceActive = suppressed || recentlyStarted;
-    // ActiveEnterTimestampMonotonic lookup — primary filter source; fallback to last success window
-    let activeEnterMs;
-    try {
-        const fn = opts.getActiveEnterMs ?? getActiveEnterMs;
-        activeEnterMs = fn();
-        void activeEnterMs;
-    }
-    catch {
-        activeEnterMs = undefined;
+    let activeEnterAtMs = opts.activeEnterAtMs;
+    if (activeEnterAtMs === undefined) {
+        try {
+            const fn = opts.getActiveEnterMs ?? getActiveEnterMs;
+            activeEnterAtMs = fn();
+        }
+        catch {
+            activeEnterAtMs = undefined;
+        }
     }
-    let logError;
-    // Filter logTail to only consider lines after ActiveEnterTimestamp.
-    // Fallback: last 200 lines after last "dsh web: http" success marker (log is append-only).
+    const now = Date.now();
     const lines = logContent.split('\n');
     const lowerLines = lines.map(l => l.toLowerCase());
-    // find last success marker
-    let lastSuccessIdx = -1;
-    for (let i = lowerLines.length - 1; i >= 0; i--) {
-        if (lowerLines[i].includes('dsh web: http')) {
-            lastSuccessIdx = i;
-            break;
-        }
-    }
+    // Scope the scan to the current boot. The boundary line is only trusted for
+    // the unit start it was written for: a start more than a boot budget later
+    // (a systemd auto-restart, a manual start) is a different boot.
+    const boundaryIdx = lastBootBoundaryIndex(lines);
+    const boundaryMs = boundaryIdx === -1 ? undefined : parseBootBoundaryMs(lines[boundaryIdx]);
+    const scopedToThisBoot = boundaryMs !== undefined
+        && activeEnterAtMs !== undefined
+        && activeEnterAtMs >= boundaryMs
+        && activeEnterAtMs - boundaryMs <= bootGraceMs;
+    const bootLines = scopedToThisBoot ? lines.slice(boundaryIdx + 1) : lines;
+    const bootLower = scopedToThisBoot ? lowerLines.slice(boundaryIdx + 1) : lowerLines;
+    // Proof of a finished boot is a serving probe, not a log line (see bootFreshness).
+    const probeSucceeded = httpCode === 200 || httpCode === 401;
+    const bootPhase = bootFreshness({ activeEnterAtMs, now, bootGraceMs, probeSucceeded });
+    const booting = bootPhase === 'booting';
+    const graceActive = suppressed || booting;
+    // Inside the current boot, only lines after its own success marker may be a
+    // post-start crash. With no marker and no scope proving these lines are this
+    // boot's, the scan is inconclusive (D3) instead of inheriting the previous
+    // boot's crash text — that inheritance is what produced the 2026-09-13
+    // rollback report ("rollback — degraded: This operation was aborted") from a
+    // healthy, still-booting instance reading the previous boot's EADDRINUSE.
+    const successIdx = lastSuccessMarkerIndex(bootLower);
     let scanLines;
     let scanLower;
-    if (lastSuccessIdx !== -1) {
-        const after = lines.slice(lastSuccessIdx + 1);
-        const afterLower = lowerLines.slice(lastSuccessIdx + 1);
-        // keep only last 200 lines after success (fallback window)
-        if (after.length > 200) {
-            scanLines = after.slice(-200);
-            scanLower = afterLower.slice(-200);
-        }
-        else {
-            scanLines = after;
-            scanLower = afterLower;
-        }
-        // If ActiveEnter is available, the same window applies — old EADDRINUSE before restart
-        // is before the success marker and thus excluded. No extra timestamp->line mapping needed.
+    if (successIdx !== -1) {
+        scanLines = bootLines.slice(successIdx + 1);
+        scanLower = bootLower.slice(successIdx + 1);
+    }
+    else if (booting && !scopedToThisBoot) {
+        scanLines = [];
+        scanLower = [];
     }
     else {
-        // no success marker: consider last 200 lines total (both primary and fallback)
-        if (lines.length > 200) {
-            scanLines = lines.slice(-200);
-            scanLower = lowerLines.slice(-200);
-        }
-        else {
-            scanLines = lines;
-            scanLower = lowerLines;
-        }
+        scanLines = bootLines;
+        scanLower = bootLower;
+    }
+    if (scanLines.length > 200) {
+        scanLines = scanLines.slice(-200);
+        scanLower = scanLower.slice(-200);
     }
-    // If ActiveEnter lookup succeeded/failed, we already applied the fallback window.
-    // When system has no success marker and no ActiveEnter, scanLines is still last 200.
     let lastErrorIdx = -1;
     let matchedLine = '';
     for (let i = scanLines.length - 1; i >= 0; i--) {
@@ -183,12 +251,11 @@ export async function pollHealth(opts = {}) {
         if (lastErrorIdx !== -1)
             break;
     }
+    let logError;
     if (lastErrorIdx !== -1) {
-        // Within the windowed view, if a success appears after the error it would have been before the slice,
-        // but check anyway for safety (error before success within window)
         let hasSuccessAfter = false;
         for (let i = lastErrorIdx + 1; i < scanLines.length; i++) {
-            if (scanLower[i].includes('dsh web: http')) {
+            if (scanLower[i].includes(SUCCESS_MARKER)) {
                 hasSuccessAfter = true;
                 break;
             }
@@ -196,22 +263,33 @@ export async function pollHealth(opts = {}) {
         if (!hasSuccessAfter)
             logError = matchedLine;
     }
-    else if (suppressed) {
-        // suppressed window with no windowed error — ensure stale errors before success are ignored
-        // (already handled by windowing)
-    }
-    // Legacy full-scan fallback for hasSuccessAfter across original lines when no windowed error
-    // but original had error before success — already suppressed by windowing, no need to re-check.
-    // Distinguish FULL (http !=200) vs DEGRADED (http 200 but log has plugin error)
-    // Suppression: during 30s grace (planned-restart OR recently started), transient fetch failures are not a crash
     if (fetchError) {
-        if (graceActive) {
-            // treat fetch failed / http 404 as up:true suppressed (don't write error) — also doubles effective downThreshold
-            return {
-                up: true,
-                httpCode,
-                logTail: logContent.slice(-5000),
-            };
+        const kind = classifyFetchFailure(fetchError);
+        // D1: a timeout/abort while the current boot is unproven is a slow boot,
+        // not a crash — increment nothing. D2: a refused connection is different
+        // (nothing is listening, the process is gone) and is never masked.
+        if (booting && kind !== 'refused') {
+            return { up: true, httpCode, bootPhase, logTail: logContent.slice(-5000) };
+        }
+        // D5: inside the boot window a refused connection with a verifiably alive
+        // process is a boot symptom, not a crash — the listener may not be bound
+        // yet. Outside the window, or with a dead process, the verdict below is
+        // exactly the pre-D5 behaviour (degraded when the port still answers,
+        // down when it does not).
+        if (booting && kind === 'refused') {
+            let alive = false;
+            try {
+                alive = await psAliveFn();
+            }
+            catch {
+                alive = false;
+            }
+            if (alive) {
+                return { up: true, httpCode, bootPhase, logTail: logContent.slice(-5000) };
+            }
+        }
+        if (suppressed) {
+            return { up: true, httpCode, bootPhase, logTail: logContent.slice(-5000) };
         }
         // Corroborate with a cheap port-liveness check before declaring a crash.
         // The HTTP fetch shares dsh-web's own event loop, so a busy-but-alive
@@ -232,6 +310,7 @@ export async function pollHealth(opts = {}) {
             return {
                 up: true,
                 httpCode,
+                bootPhase,
                 error: logError ? `${fetchError} + ${logError}` : fetchError,
                 degraded: true,
                 logTail: logContent.slice(-5000),
@@ -240,52 +319,31 @@ export async function pollHealth(opts = {}) {
         return {
             up: false,
             httpCode,
+            bootPhase,
             error: logError ? `${fetchError} + ${logError}` : fetchError,
             degraded: false,
             logTail: logContent.slice(-5000),
         };
     }
-    // During grace, a windowed logError that is still present is considered stale/boot transient
-    // as well — treat as up to avoid double restart. The fallback window already filters pre-restart errors.
+    // During grace, a windowed logError that is still present is considered
+    // stale/boot transient as well — treat as up to avoid double restart.
     if (graceActive && logError) {
-        // Effective downThreshold doubling is handled by supervisor, but health also suppresses log tail
-        return {
-            up: true,
-            httpCode,
-            logTail: logContent.slice(-5000),
-        };
+        return { up: true, httpCode, bootPhase, logTail: logContent.slice(-5000) };
     }
     if (logError) {
-        // EADDRINUSE is fatal even with http 200 — old process still holds 3080
-        // and new start failed; treat as FULL down so supervisor kills + restarts.
+        // EADDRINUSE is fatal even with http 200 — an old process still holds
+        // the port and the new start failed; treat as FULL down so the supervisor
+        // kills + restarts.
         const lowerErr = logError.toLowerCase();
         const isFatalPortError = lowerErr.includes('eaddrinuse') || lowerErr.includes('address already in use');
         if (isFatalPortError) {
-            return {
-                up: false,
-                httpCode,
-                error: logError,
-                degraded: false,
-                logTail: logContent.slice(-5000),
-            };
+            return { up: false, httpCode, bootPhase, error: logError, degraded: false, logTail: logContent.slice(-5000) };
         }
         // http 200 but log error → DEGRADED (isolatable), not FULL
         if (httpCode === 200) {
-            return {
-                up: true,
-                httpCode,
-                error: logError,
-                degraded: true,
-                logTail: logContent.slice(-5000),
-            };
+            return { up: true, httpCode, bootPhase, error: logError, degraded: true, logTail: logContent.slice(-5000) };
         }
-        return {
-            up: false,
-            httpCode,
-            error: logError,
-            degraded: false,
-            logTail: logContent.slice(-5000),
-        };
+        return { up: false, httpCode, bootPhase, error: logError, degraded: false, logTail: logContent.slice(-5000) };
     }
     // Also check psAlive as secondary signal — if fetch ok but ps dead, still down
     try {
@@ -297,7 +355,7 @@ export async function pollHealth(opts = {}) {
     catch {
         // ignore
     }
-    return { up: httpCode === 200 || httpCode === 401, httpCode, logTail: logContent.slice(-5000) };
+    return { up: httpCode === 200 || httpCode === 401, httpCode, bootPhase, logTail: logContent.slice(-5000) };
 }
 function defaultFetch(url, timeoutMs) {
     return async () => {

package/lib/intents.d.ts

@@ -13,3 +13,20 @@ export declare function intentsDir(): string;
 export declare function intentPath(sessionId: string): string;
 export declare function readIntent(sessionId: string): RestartIntent | undefined;
 export declare function consumeIntent(sessionId: string): void;
+/**
+ * Post-swap outcome written by the supervisor daemon after acting on a
+ * restart request (`<sessionId>.outcome.json`, mode 600, same dir). Read by
+ * `dsh_web_restart_status` so callers learn the new PID + HTTP status without
+ * hand-probing `ss`/`curl`.
+ */
+export interface RestartOutcome {
+    state: 'ok' | 'failed';
+    oldPid?: number;
+    newPid?: number;
+    httpStatus?: number;
+    swappedAt: number;
+    error?: string;
+}
+export declare function outcomePath(sessionId: string): string;
+export declare function writeRestartOutcome(sessionId: string, outcome: RestartOutcome): void;
+export declare function readRestartOutcome(sessionId: string): RestartOutcome | undefined;

package/lib/intents.js

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync, unlinkSync } from 'node:fs';
+import { existsSync, readFileSync, unlinkSync, mkdirSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { homedir } from 'node:os';
 export function intentsDir() {
@@ -25,3 +25,25 @@ export function consumeIntent(sessionId) {
     }
     catch { }
 }
+export function outcomePath(sessionId) {
+    const safe = sessionId.replace(/[^A-Za-z0-9._-]/g, '_');
+    return join(intentsDir(), `${safe}.outcome.json`);
+}
+export function writeRestartOutcome(sessionId, outcome) {
+    try {
+        mkdirSync(intentsDir(), { recursive: true });
+        writeFileSync(outcomePath(sessionId), JSON.stringify(outcome), { encoding: 'utf8', mode: 0o600 });
+    }
+    catch { }
+}
+export function readRestartOutcome(sessionId) {
+    try {
+        const p = outcomePath(sessionId);
+        if (!existsSync(p))
+            return undefined;
+        return JSON.parse(readFileSync(p, 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+}

package/lib/plugin.js

@@ -9,7 +9,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as os from 'node:os';
 import { fileURLToPath } from 'node:url';
-import { findInterrupted as defaultFindInterrupted, findDanglingOpenTurns as defaultFindDanglingOpenTurns } from './resume.js';
+import { findInterrupted as defaultFindInterrupted, findDanglingOpenTurns as defaultFindDanglingOpenTurns, resolveSessionLogPath } from './resume.js';
 import { readIntent, consumeIntent } from './intents.js';
 import { appendResumeLog } from './resume-log.js';
 import { makeSkillProvider } from './skill-provider.js';
@@ -294,12 +294,13 @@ async function readRouteFromHandle(persistence, sid) {
  * first match so huge logs cost one streamed pass, not a full decode.
  */
 async function readRouteFromRawLog(sessionsRoot, group, sessionId) {
-    const zstdPath = path.join(sessionsRoot, group, sessionId, 'session.jsonl.zstd');
-    const jsonlPath = path.join(sessionsRoot, group, sessionId, 'session.jsonl');
+    const logPath = resolveSessionLogPath(path.join(sessionsRoot, group, sessionId));
+    if (logPath === undefined)
+        return undefined;
     try {
-        if (fs.existsSync(zstdPath)) {
+        if (logPath.endsWith('.zstd')) {
             const { execSync } = await import('node:child_process');
-            const out = execSync(`zstd -d -c ${JSON.stringify(zstdPath)} 2>/dev/null | grep -a -m1 '"type":"request/context"'`, { encoding: 'utf-8' });
+            const out = execSync(`zstd -d -c ${JSON.stringify(logPath)} 2>/dev/null | grep -a -m1 '"type":"request/context"'`, { encoding: 'utf-8' });
             const line = out.split('\n').find((l) => l.includes('request/context'));
             if (line !== undefined) {
                 try {
@@ -309,18 +310,16 @@ async function readRouteFromRawLog(sessionsRoot, group, sessionId) {
             }
             return undefined;
         }
-        if (fs.existsSync(jsonlPath)) {
-            const content = fs.readFileSync(jsonlPath, 'utf-8');
-            for (const line of content.split('\n')) {
-                if (!line.includes('"request/context"'))
-                    continue;
-                try {
-                    const route = routeFromEvents([JSON.parse(line)]);
-                    if (route !== undefined)
-                        return route;
-                }
-                catch { }
+        const content = fs.readFileSync(logPath, 'utf-8');
+        for (const line of content.split('\n')) {
+            if (!line.includes('"request/context"'))
+                continue;
+            try {
+                const route = routeFromEvents([JSON.parse(line)]);
+                if (route !== undefined)
+                    return route;
             }
+            catch { }
         }
     }
     catch { }

package/lib/restart-exec.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Serialized systemd restart for `dsh-web.service`: stop, wait until the
+ * unit is inactive, then start — instead of one raw `systemctl restart`
+ * that boots the new process while the old one still holds :3082 and
+ * crash-loops on EADDRINUSE (2026-09-11 outage: 4 restarts in
+ * 15 min over a ~90s SIGTERM stop → 30 EADDRINUSE crashes).
+ *
+ * All side effects are injectable so tests never touch systemd.
+ */
+export interface SerializedRestartDeps {
+    /** Run a shell command; must throw on non-zero exit. */
+    exec?: (cmd: string) => void;
+    /** Whether the unit is currently active. */
+    isActive?: () => boolean;
+    sleep?: (ms: number) => Promise<void>;
+    /** Max time to wait for inactivity before starting anyway. */
+    stopTimeoutMs?: number;
+    /** Poll interval while waiting for inactivity. */
+    pollMs?: number;
+    /** Clock (injectable for tests). */
+    now?: () => number;
+}
+export declare function serializedSystemdRestart(deps?: SerializedRestartDeps): Promise<void>;
+export declare const DSH_WEB_UNIT_NAME = "dsh-web.service";
+export declare function dshWebUnitPath(): string;
+/** Does systemd own `dsh-web.service` on this host? */
+export declare function systemdUnitExists(unitPath?: string): boolean;
+/**
+ * The direct-node `nohup` fallback exists for portable hosts that have no
+ * systemd unit. When the unit exists, systemd owns the boot: spawning node
+ * behind its back is how a second instance appears — the two starts / one
+ * rollback report of 2026-09-13. Gate on "the unit does not exist", never on
+ * "this particular start failed".
+ */
+export declare function shouldUseNohupFallback(unitExists: boolean): boolean;

package/lib/restart-exec.js

@@ -0,0 +1,60 @@
+import { execSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+const STOP_TIMEOUT_MS = 120_000;
+const POLL_MS = 2_000;
+export async function serializedSystemdRestart(deps = {}) {
+    const exec = deps.exec ?? ((cmd) => {
+        execSync(cmd, { timeout: 15_000, stdio: 'pipe' });
+    });
+    const isActive = deps.isActive ?? (() => {
+        try {
+            execSync('systemctl --user is-active --quiet dsh-web.service', { timeout: 5_000, stdio: 'pipe' });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    });
+    const sleep = deps.sleep ?? ((ms) => new Promise(r => setTimeout(r, ms)));
+    const stopTimeoutMs = deps.stopTimeoutMs ?? STOP_TIMEOUT_MS;
+    const pollMs = deps.pollMs ?? POLL_MS;
+    const now = deps.now ?? Date.now;
+    // Best-effort: the unit may already be down (crash) — the wait + start
+    // below still apply.
+    try {
+        exec('systemctl --user stop dsh-web.service');
+    }
+    catch { /* fall through to wait + start */ }
+    const deadline = now() + stopTimeoutMs;
+    while (isActive()) {
+        if (now() >= deadline)
+            break;
+        await sleep(pollMs);
+    }
+    exec('systemctl --user start dsh-web.service');
+}
+export const DSH_WEB_UNIT_NAME = 'dsh-web.service';
+export function dshWebUnitPath() {
+    return process.env.DSH_WEB_UNIT_PATH ?? path.join(os.homedir(), '.config/systemd/user/dsh-web.service');
+}
+/** Does systemd own `dsh-web.service` on this host? */
+export function systemdUnitExists(unitPath = dshWebUnitPath()) {
+    try {
+        return fs.existsSync(unitPath);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The direct-node `nohup` fallback exists for portable hosts that have no
+ * systemd unit. When the unit exists, systemd owns the boot: spawning node
+ * behind its back is how a second instance appears — the two starts / one
+ * rollback report of 2026-09-13. Gate on "the unit does not exist", never on
+ * "this particular start failed".
+ */
+export function shouldUseNohupFallback(unitExists) {
+    return !unitExists;
+}

package/lib/restart-guards.d.ts

@@ -1,4 +1,22 @@
 export declare function buildKillStalePortsCommand(ports?: number[]): string;
+/**
+ * Sentinel appended to dsh-web.log immediately before a supervised restart.
+ *
+ * The log is append-only and carries no timestamps, so this line is the only
+ * durable ordering between "the previous boot's crash" and "this boot's
+ * output". Without it the health scan inherited the previous, failed boot's
+ * `EADDRINUSE` stack and rolled back a healthy, still-booting instance
+ * (incident 2026-09-13).
+ */
+export declare const BOOT_BOUNDARY_MARKER = "[supervisor] boot-boundary";
+/** The production dsh-web log (override with DSH_WEB_LOG for tests/tools). */
+export declare function dshWebLogPath(): string;
+/**
+ * Append the boot-boundary sentinel. Pass an explicit `logPath` in tests, or
+ * redirect with DSH_WEB_LOG. With no destination at all under VITEST this is a
+ * deliberate no-op so a unit test can never append to the operator's real log.
+ */
+export declare function markBootBoundary(logPath?: string): void;
 export declare function isSelfCopyError(message: string): boolean;
 export declare const PLANNED_RESTART_TTL_MS = 180000;
 export declare function isPlannedRestartFresh(mtimeMs: number, nowMs: number, ttlMs?: number): boolean;
@@ -11,9 +29,11 @@ export interface RestartRequest {
     ttl: number;
     callerSessionId?: string;
     reason?: string;
+    oldPid?: number;
 }
 export declare function writeRestartRequest(caller: {
     callerSessionId?: string;
     reason?: string;
+    oldPid?: number;
 }, ttlMs?: number): void;
 export declare function readRestartRequest(): RestartRequest | undefined;