@ddtcorex/dsh-maestro-supervisor 0.6.4 → 0.6.6

package/lib/cli.js

@@ -5,6 +5,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as os from 'node:os';
 import { resolveHarnessRoot, resolveDeepseekHarnessDir } from './paths.js';
+import { buildKillStalePortsCommand, isSelfCopyError, checkPlannedRestart, writePlannedRestart } from './restart-guards.js';
 export async function runCli(args) {
     const cmd = args[2] ?? '--help';
     if (cmd === '--help' || cmd === '-h' || cmd === 'help') {
@@ -165,7 +166,7 @@ Commands:
                         fs.cpSync(srcPath, destPath, { recursive: true, force: true });
                     }
                     catch (e) {
-                        if (String(e?.message ?? '').includes('cannot be the same'))
+                        if (isSelfCopyError(String(e?.message ?? '')))
                             continue;
                         throw e;
                     }
@@ -182,10 +183,19 @@ Commands:
             },
             restartWeb: async () => {
                 const { execSync } = await import('node:child_process');
-                // Kill stale MainThread holding 3080/3000 before any restart attempt
+                // Single-owner: mark planned restart 30s before any systemctl/nohup
+                // so pollHealth + tick suppress the transient down (no double restart).
+                try {
+                    writePlannedRestart(30000);
+                }
+                catch { }
+                // Kill stale MainThread holding 3080 before any restart attempt
                 // (EADDRINUSE crash leaves old pid alive with http 200; new start would fail)
+                // Scoped to :3080 only — an unfiltered `ss -tlnp` matches every
+                // listening process on the host, not just dsh web (regression: killed
+                // unrelated services like redis/horizon on every restart).
                 try {
-                    execSync(`pids=$(ss -tlnp 2>/dev/null | sed -n 's/.*pid=\\([0-9]*\\).*/\\1/p' | sort -u); if [ -n "$pids" ]; then echo "[supervisor] killing stale pids $pids"; kill $pids 2>/dev/null || true; sleep 2; fi`, { timeout: 5000, stdio: 'pipe' });
+                    execSync(buildKillStalePortsCommand(), { timeout: 5000, stdio: 'pipe' });
                 }
                 catch { }
                 // Prefer systemd — if dsh-web.service is installed, restart/start it
@@ -206,6 +216,10 @@ Commands:
                 try {
                     const harnessRoot = resolveDeepseekHarnessDir();
                     const logPath = path.join(os.homedir(), '.dsh/dsh-web.log');
+                    try {
+                        writePlannedRestart(30000);
+                    }
+                    catch { }
                     execSync(`setsid nohup bash -c 'export NVM_DIR="$HOME/.nvm"; [ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"; cd ${JSON.stringify(harnessRoot)} && exec node --import tsx/esm apps/cli/src/bin.ts web --no-open >> ${JSON.stringify(logPath)} 2>&1' &`, { timeout: 5000 });
                     console.log('[supervisor] started dsh-web via nohup fallback (direct node, portable)');
                 }
@@ -214,9 +228,9 @@ Commands:
                 }
             },
             notify: async (msg) => console.log(`[notify] ${msg}`),
-            intervalMs: 3000,
+            isPlannedRestartActive: () => checkPlannedRestart(),
         });
-        supervisor.start();
+        await supervisor.start();
         // keep process alive
         await new Promise(() => { });
     }

package/lib/config.d.ts

@@ -0,0 +1 @@
+export declare function readSupervisorConfig(): Promise<Record<string, any>>;

package/lib/config.js

@@ -0,0 +1,18 @@
+import { load, readFlat } from '@ddtcorex/dsh-maestro-config-lib';
+export async function readSupervisorConfig() {
+    try {
+        const doc = await load();
+        if (doc?.domains?.supervisor && typeof doc.domains.supervisor === 'object' && !Array.isArray(doc.domains.supervisor)) {
+            return doc.domains.supervisor;
+        }
+    }
+    catch { }
+    try {
+        const f = await readFlat().catch(() => ({}));
+        if (f?.supervisor && typeof f.supervisor === 'object' && !Array.isArray(f.supervisor)) {
+            return f.supervisor;
+        }
+    }
+    catch { }
+    return {};
+}

package/lib/health-poller.d.ts

@@ -5,6 +5,8 @@ export interface HealthState {
     degraded?: boolean;
     logTail?: string;
 }
+export declare function getActiveEnterMs(): number | undefined;
+export declare function getActiveEnterWallMs(): number | undefined;
 export interface PollHealthOpts {
     fetch?: () => Promise<{
         status: number;
@@ -14,6 +16,8 @@ export interface PollHealthOpts {
     logTail?: () => Promise<string>;
     url?: string;
     timeoutMs?: number;
+    /** injectable for tests — overrides systemctl lookup */
+    getActiveEnterMs?: () => number | undefined;
 }
 export declare function pollHealth(opts?: PollHealthOpts): Promise<HealthState>;
 export declare function collectLogTail(): Promise<string>;

package/lib/health-poller.js

@@ -1,3 +1,55 @@
+import { checkPlannedRestart } from './restart-guards.js';
+import { execSync as execSyncImpl } from 'node:child_process';
+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 {
+        const out = execSyncImpl('systemctl --user show -p ActiveEnterTimestamp dsh-web.service 2>/dev/null', { encoding: 'utf8' });
+        const m = out.match(/ActiveEnterTimestamp=(.+)/);
+        if (m) {
+            const s = m[1].trim();
+            if (!s || s === 'n/a')
+                return undefined;
+            const ms = Date.parse(s);
+            if (!Number.isNaN(ms))
+                return ms;
+        }
+    }
+    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;
+}
 const ERROR_PATTERNS = [
     'ERR_MODULE_NOT_FOUND',
     'ERR_PNPM',
@@ -16,7 +68,12 @@ const ERROR_PATTERNS = [
     'address already in use',
 ];
 export async function pollHealth(opts = {}) {
-    const fetchFn = opts.fetch ?? defaultFetch(opts.url ?? 'http://127.0.0.1:3080/', opts.timeoutMs ?? 5000);
+    // 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
+    // combined with a low down-threshold this caused a self-sustaining restart
+    // loop (see Supervisor.downThreshold). 12s gives boot room without masking
+    // a genuinely dead process for long.
+    const fetchFn = opts.fetch ?? defaultFetch(opts.url ?? 'http://127.0.0.1:3080/', opts.timeoutMs ?? 12000);
     const psAliveFn = opts.psAlive ?? defaultPsAlive;
     const logTailFn = opts.logTail ?? defaultLogTail;
     let httpCode;
@@ -24,7 +81,8 @@ export async function pollHealth(opts = {}) {
     try {
         const res = await fetchFn();
         httpCode = res.status;
-        if (res.status !== 200) {
+        // 401 is healthy: dsh web is up but requires browser token (since 0.1.2). Only 5xx / network errors are down.
+        if (res.status !== 200 && res.status !== 401) {
             fetchError = `http ${res.status}`;
         }
     }
@@ -38,20 +96,72 @@ 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.
+    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 logError;
-    // Find most recent error line (not first) and ignore stale errors that are
-    // followed by a successful boot (log tail is append-only, old EADDRINUSE stays forever).
-    // We check last occurrence and ensure no "dsh web: http" success after it.
+    // Filter logTail to only consider lines after ActiveEnterTimestamp.
+    // Fallback: last 200 lines after last "dsh web: http" success marker (log is append-only).
     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;
+        }
+    }
+    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.
+    }
+    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;
+        }
+    }
+    // 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 = lines.length - 1; i >= 0; i--) {
-        const lower = lowerLines[i];
+    for (let i = scanLines.length - 1; i >= 0; i--) {
+        const lower = scanLower[i];
         for (const pat of ERROR_PATTERNS) {
             if (lower.includes(pat.toLowerCase())) {
                 lastErrorIdx = i;
-                matchedLine = lines[i].trim().slice(0, 500);
+                matchedLine = scanLines[i].trim().slice(0, 500);
                 break;
             }
         }
@@ -59,10 +169,11 @@ export async function pollHealth(opts = {}) {
             break;
     }
     if (lastErrorIdx !== -1) {
-        // If a successful boot line appears after the last error, error is stale (already recovered)
+        // 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 < lines.length; i++) {
-            if (lowerLines[i].includes('dsh web: http')) {
+        for (let i = lastErrorIdx + 1; i < scanLines.length; i++) {
+            if (scanLower[i].includes('dsh web: http')) {
                 hasSuccessAfter = true;
                 break;
             }
@@ -70,8 +181,23 @@ 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),
+            };
+        }
         return {
             up: false,
             httpCode,
@@ -80,8 +206,18 @@ export async function pollHealth(opts = {}) {
             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.
+    if (graceActive && logError) {
+        // Effective downThreshold doubling is handled by supervisor, but health also suppresses log tail
+        return {
+            up: true,
+            httpCode,
+            logTail: logContent.slice(-5000),
+        };
+    }
     if (logError) {
-        // EADDRINUSE is fatal even with http 200 — old process still holds 3080/3000
+        // EADDRINUSE is fatal even with http 200 — old process still holds 3080
         // and new start failed; treat as FULL down so supervisor kills + restarts.
         const lowerErr = logError.toLowerCase();
         const isFatalPortError = lowerErr.includes('eaddrinuse') || lowerErr.includes('address already in use');
@@ -122,7 +258,7 @@ export async function pollHealth(opts = {}) {
     catch {
         // ignore
     }
-    return { up: httpCode === 200, httpCode, logTail: logContent.slice(-5000) };
+    return { up: httpCode === 200 || httpCode === 401, httpCode, logTail: logContent.slice(-5000) };
 }
 function defaultFetch(url, timeoutMs) {
     return async () => {

package/lib/notifier.d.ts

@@ -1,6 +1,11 @@
 export interface NotifierOpts {
     send?: (msg: string) => Promise<void>;
 }
+export declare function notifyAutoRestart(reason: string, opts?: NotifierOpts & {
+    httpCode?: string | number;
+    lkgId?: string;
+    reportPath?: string;
+}): Promise<void>;
 export declare function notify(msg: string, opts?: NotifierOpts): Promise<void>;
 export declare function notifyCrash(reportPath: string, error: string, opts?: NotifierOpts): Promise<void>;
 export declare function notifyDegraded(id: string, error: string, opts?: NotifierOpts): Promise<void>;

package/lib/notifier.js

@@ -1,3 +1,13 @@
+import { checkPlannedRestart } from './restart-guards.js';
+export async function notifyAutoRestart(reason, opts = {}) {
+    if (checkPlannedRestart())
+        return;
+    const httpCode = opts.httpCode ?? 'n/a';
+    const lkgId = opts.lkgId ?? opts.lkg ?? 'n/a';
+    const reportPath = opts.reportPath ?? opts.report ?? 'n/a';
+    const msg = `🔄 dsh web auto-restart — ${reason} — ${new Date().toISOString()} — up:${httpCode} — LKG:${lkgId} — report:${reportPath}`;
+    await notify(msg, opts);
+}
 export async function notify(msg, opts = {}) {
     const send = opts.send ?? defaultSend;
     try {

package/lib/plugin.js

@@ -202,15 +202,56 @@ export async function resumeInterrupted(ctx, ids) {
                 ctx.logger?.warn?.(`[supervisor] auto-resume: no live agent available for ${id}`);
                 continue;
             }
+            // Ensure bash tool is registered before followup — initial resume header with
+            // only 11 tools (missing bash) broke 36646045... etc. Wait briefly for
+            // ctx.tools to populate (preset mount + shell). Best-effort: poll up to 5s.
+            try {
+                const tools = ctx.get?.('tools') ?? ctx.tools;
+                const hasBash = () => {
+                    try {
+                        if (typeof tools?.get === 'function')
+                            return tools.get('bash') !== undefined;
+                        if (typeof tools?.has === 'function')
+                            return tools.has('bash');
+                        if (Array.isArray(tools?.list?.()))
+                            return tools.list().some((t) => t?.name === 'bash' || t === 'bash');
+                        // Fallback: check systemPrompt assembly indirectly via tools registry size
+                        return true;
+                    }
+                    catch {
+                        return true;
+                    }
+                };
+                if (!hasBash()) {
+                    for (let i = 0; i < 10; i++) {
+                        await new Promise(r => setTimeout(r, 500));
+                        if (hasBash())
+                            break;
+                    }
+                    if (!hasBash())
+                        ctx.logger?.warn?.(`[supervisor] auto-resume: bash tool still not ready for ${id} — continuing anyway`);
+                }
+            }
+            catch { }
             const { createUserMessage } = await import('@deepseek-ai/dsh-llm').catch(() => ({
                 createUserMessage: (input) => ({ ...input, role: 'user', id: crypto.randomUUID() }),
             }));
+            // Use an explicit recovery prompt instead of bare "continue" — the synthetic
+            // TOOL_OUTCOME_UNKNOWN / TOOL_NOT_STARTED result (repair.ts:104) tells the
+            // model to verify external state before retrying. A bare "continue" made
+            // the model reply with text instead of re-issuing bash, leaving the
+            // session stuck after every crash (36646045..., 31ae53a2...).
+            const resumeMessage = 'The previous turn was interrupted by a crash and the harness has synthesized a tool result with TOOL_OUTCOME_UNKNOWN / TOOL_NOT_STARTED. ' +
+                'Outcome of the last tool call is unknown — it may or may not have had side effects. ' +
+                'Verify external state with bash (e.g., ls, cat, git status) before retrying. ' +
+                'Retry only if the operation is read-only or idempotent; if it may have side effects, verify first or ask the user. ' +
+                'Then continue the original task from where it was interrupted — re-issue the next bash/tool call that the plan requires.';
             agent.followup(createUserMessage({
-                content: [{ type: 'text', text: 'continue' }],
+                content: [{ type: 'text', text: resumeMessage }],
                 source: { kind: 'user' },
             }));
             resumed.push(id);
-            ctx.logger?.info?.(`[supervisor] auto-resume: sent continue trigger for ${id}`);
+            ctx.logger?.info?.(`[supervisor] auto-resume: sent recovery continue for ${id}`);
         }
         catch (e) {
             ctx.logger?.warn?.(`[supervisor] auto-resume failed ${id}: ${e?.message ?? String(e)}`);
@@ -239,12 +280,91 @@ export function createResumeRpcHandler(ctx, opts = {}) {
         return { ok: true, value: { resumed: await resume(ctx, ids) } };
     };
 }
+function ensureSystemdKeepalive(ctx) {
+    // Best-effort: ensure dsh-web-keepalive.service exists and is enabled, and linger is on.
+    // This is the user-level auto-fix for the 11:42:58 crash where manager session 97
+    // Removed caused user manager to exit despite Linger, killing dsh-web.
+    // Runs inside dsh web (as the current user) so systemctl --user bus is available when manager is alive.
+    // Failures are swallowed — never throw from apply().
+    try {
+        const home = os.homedir();
+        const systemdDir = path.join(home, '.config/systemd/user');
+        const keepalivePath = path.join(systemdDir, 'dsh-web-keepalive.service');
+        // Migrate old keepalive.service (pre-prefix) if present
+        const oldKeepalivePath = path.join(systemdDir, 'keepalive.service');
+        if (fs.existsSync(oldKeepalivePath) && !fs.existsSync(keepalivePath)) {
+            try {
+                fs.renameSync(oldKeepalivePath, keepalivePath);
+                ctx.logger?.info?.('[supervisor] migrated keepalive.service → dsh-web-keepalive.service');
+            }
+            catch {
+                try {
+                    fs.copyFileSync(oldKeepalivePath, keepalivePath);
+                }
+                catch { }
+            }
+        }
+        if (!fs.existsSync(keepalivePath)) {
+            try {
+                fs.mkdirSync(systemdDir, { recursive: true });
+                // Inline template — avoids needing to resolve package's systemd/dsh-web-keepalive.service.template at runtime
+                const content = `[Unit]\nDescription=Keepalive for user manager linger — prevents systemd --user exit on manager session close\nAfter=default.target\n\n[Service]\nType=simple\nExecStart=/bin/sleep infinity\nRestart=always\nRestartSec=3\n\n[Install]\nWantedBy=default.target\n`;
+                fs.writeFileSync(keepalivePath, content, 'utf-8');
+                ctx.logger?.info?.('[supervisor] dsh-web-keepalive.service installed');
+            }
+            catch (e) {
+                ctx.logger?.warn?.(`[supervisor] keepalive install failed: ${e?.message ?? String(e)}`);
+                return;
+            }
+        }
+        // Try to enable linger + enable/start units best-effort (may need sudo for linger, ignore failure)
+        try {
+            const { execSync } = require('node:child_process');
+            const username = (() => { try {
+                return os.userInfo().username;
+            }
+            catch {
+                return process.env.USER || process.env.LOGNAME || '';
+            } })();
+            const lingerPath = username ? `/var/lib/systemd/linger/${username}` : '';
+            if (lingerPath && !fs.existsSync(lingerPath)) {
+                try {
+                    execSync(`loginctl enable-linger ${username} 2>/dev/null || true`, { timeout: 3000, stdio: 'ignore' });
+                }
+                catch { }
+            }
+            try {
+                execSync('systemctl --user daemon-reload 2>/dev/null || true', { timeout: 3000, stdio: 'ignore' });
+            }
+            catch { }
+            try {
+                execSync('systemctl --user enable dsh-web-keepalive.service 2>/dev/null || true', { timeout: 3000, stdio: 'ignore' });
+            }
+            catch { }
+            try {
+                execSync('systemctl --user start dsh-web-keepalive.service 2>/dev/null || true', { timeout: 3000, stdio: 'ignore' });
+            }
+            catch { }
+            // Also ensure dsh-web + supervisor are enabled (in case user installed plugin but never ran install-systemd.sh)
+            try {
+                execSync('systemctl --user enable dsh-web.service dsh-web-supervisor.service 2>/dev/null || true', { timeout: 3000, stdio: 'ignore' });
+            }
+            catch { }
+        }
+        catch { }
+    }
+    catch { }
+}
 export function apply(ctx, config = {}) {
     // The whole body is wrapped: per AGENTS.md, apply() must never throw
     // synchronously or let a rejected promise escape, no matter what fails
     // (ctx.effect missing/throwing, RPC registration throwing, or even the
     // error-reporting logger call itself throwing).
     try {
+        try {
+            ensureSystemdKeepalive(ctx);
+        }
+        catch { }
         ctx.effect(() => {
             let disposed = false;
             let timer = null;

package/lib/restart-guards.d.ts

@@ -0,0 +1,8 @@
+export declare function buildKillStalePortsCommand(ports?: number[]): string;
+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;
+export declare function plannedRestartPath(): string;
+export declare function writePlannedRestart(ttlMs?: number): void;
+export declare function checkPlannedRestart(markerPath?: string): boolean;
+export declare function clearPlannedRestart(): void;

package/lib/restart-guards.js

@@ -0,0 +1,94 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+// Regression guard: PR #17 added a "kill stale pid holding :3080/:3000 before
+// restart" step (EADDRINUSE recovery), but the original `ss -tlnp` call had no
+// port filter — it matched every listening process on the host, so every
+// restart also killed unrelated services (redis, php-fpm, horizon, ssh, ...).
+// The dsh-web MainThread holds both 3080 and 3000 (see AGENTS.md Known Issues),
+// so filtering `ss` itself to those ports is both correct and sufficient.
+export function buildKillStalePortsCommand(ports = [3080]) {
+    const filter = ports.map(p => `sport = :${p}`).join(' or ');
+    return `pids=$(ss -tlnp '( ${filter} )' 2>/dev/null | sed -n 's/.*pid=\\([0-9]*\\).*/\\1/p' | sort -u); if [ -n "$pids" ]; then echo "[supervisor] killing stale pids $pids"; kill $pids 2>/dev/null || true; sleep 2; fi`;
+}
+// LKG rollback copies each entry with fs.cpSync — an entry that resolves back
+// into itself (e.g. a symlink cycle reachable from ~/.dsh, observed in
+// production pointing into ~/.npm/_npx/.../node_modules/unist-util-position)
+// always throws here. Node's wording for this varies by version ("cannot be
+// the same", "subdirectory of itself"/"of self") — match all known phrasings
+// so the entry is skipped instead of aborting the whole rollback.
+export function isSelfCopyError(message) {
+    const lower = message.toLowerCase();
+    return lower.includes('cannot be the same') || lower.includes('subdirectory of');
+}
+// Coordination contract with dsh-safe-web-update's restart-dsh-web.sh (see
+// <workspace-root>/docs/specs/2026-08-28-supervisor-planned-restart-design.md):
+// that script writes this marker right before it intentionally takes dsh-web
+// down, so the supervisor's own health poll does not mistake a deliberate
+// restart (kill -> dry-boot -> relaunch, up to ~130s) for a crash and race it
+// with its own rollback + restartWeb(). Presence + freshness is authoritative;
+// the marker's content is never parsed.
+export const PLANNED_RESTART_TTL_MS = 180_000;
+export function isPlannedRestartFresh(mtimeMs, nowMs, ttlMs = PLANNED_RESTART_TTL_MS) {
+    return nowMs - mtimeMs < ttlMs;
+}
+export function plannedRestartPath() {
+    return path.join(os.homedir(), '.dsh/.supervisor/planned-restart.json');
+}
+export function writePlannedRestart(ttlMs = 30000) {
+    const p = plannedRestartPath();
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.writeFileSync(p, JSON.stringify({ ts: Date.now(), ttl: ttlMs }), { mode: 0o600 });
+    try {
+        fs.chmodSync(p, 0o600);
+    }
+    catch { }
+}
+export function checkPlannedRestart(markerPath) {
+    // Legacy path explicit: check mtime of that file
+    if (markerPath) {
+        try {
+            const stat = fs.statSync(markerPath);
+            return isPlannedRestartFresh(stat.mtimeMs, Date.now());
+        }
+        catch {
+            return false;
+        }
+    }
+    // New JSON marker with {ts, ttl}
+    try {
+        const raw = fs.readFileSync(plannedRestartPath(), 'utf8');
+        const j = JSON.parse(raw);
+        if (typeof j.ts === 'number' && typeof j.ttl === 'number') {
+            return Date.now() - j.ts < j.ttl;
+        }
+    }
+    catch { }
+    // Fallback: legacy plain file written by dsh-safe-web-update (no .json, mtime-based)
+    try {
+        const legacy = path.join(os.homedir(), '.dsh/.supervisor/planned-restart');
+        const stat = fs.statSync(legacy);
+        return isPlannedRestartFresh(stat.mtimeMs, Date.now());
+    }
+    catch { }
+    return false;
+}
+export function clearPlannedRestart() {
+    try {
+        fs.unlinkSync(plannedRestartPath());
+    }
+    catch { }
+    // also clear legacy plain file if present (best-effort, avoids stale suppression)
+    try {
+        const legacy = path.join(os.homedir(), '.dsh/.supervisor/planned-restart');
+        if (fs.existsSync(legacy) && legacy !== plannedRestartPath()) {
+            // only remove legacy if it was created as test artifact; keep conservative
+            // but clearing both ensures checkPlannedRestart() returns false after clear
+            try {
+                fs.unlinkSync(legacy);
+            }
+            catch { }
+        }
+    }
+    catch { }
+}

package/lib/supervisor.d.ts

@@ -21,7 +21,11 @@ export interface SupervisorDeps {
     notify: (msg: string) => Promise<void>;
     intervalMs?: number;
     debounceMs?: number;
+    downThreshold?: number;
     getTime?: () => number;
+    isPlannedRestartActive?: () => boolean | Promise<boolean>;
+    writePlannedRestart?: (ttlMs?: number) => void;
+    checkPlannedRestart?: () => boolean;
     runDebugAgent?: (opts: {
         reportPath: string;
         health: HealthState;
@@ -46,18 +50,26 @@ export declare class Supervisor {
     private rollingBack;
     private lastLKGWrite;
     private lastDegradedNotify;
+    private consecutiveDown;
+    private consecutiveDegraded;
     private timer;
     constructor(deps: SupervisorDeps);
+    private getWritePlannedRestart;
+    private getCheckPlannedRestart;
+    restartWeb(): Promise<void>;
     private getRunDebugAgent;
     private getFindInterrupted;
     private getResumeSessions;
     private getAutoResumeEnabled;
     private getResumeWithinMs;
+    private getEffectiveIntervalMs;
+    private getEffectiveDownThreshold;
     private findInterruptedRecent;
     private collectGitDiff;
     private attemptAutoResume;
     private handleDebugResult;
     tick(): Promise<void>;
-    start(): void;
+    start(): Promise<void>;
+    startSync(): void;
     stop(): void;
 }

package/lib/supervisor.js

@@ -4,6 +4,9 @@ import * as fs from 'node:fs';
 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 { buildKillStalePortsCommand } from './restart-guards.js';
 export async function resumeViaRpc(ids, fetchFn = globalThis.fetch) {
     const rpcId = crypto.randomUUID();
     const response = await fetchFn('http://127.0.0.1:3080/dsh-maestro-supervisor-resume/resume', {
@@ -30,10 +33,45 @@ export class Supervisor {
     rollingBack = false;
     lastLKGWrite = 0;
     lastDegradedNotify = 0;
+    consecutiveDown = 0;
+    consecutiveDegraded = 0;
     timer = null;
     constructor(deps) {
         this.deps = deps;
     }
+    getWritePlannedRestart() {
+        return this.deps.writePlannedRestart ?? defaultWritePlannedRestart;
+    }
+    getCheckPlannedRestart() {
+        return this.deps.checkPlannedRestart ?? defaultCheckPlannedRestart;
+    }
+    async restartWeb() {
+        this.getWritePlannedRestart()(30000);
+        if (this.deps.restartWeb) {
+            await this.deps.restartWeb();
+            return;
+        }
+        // Fallback systemctl path (mirrors cli.ts) — kept for standalone use
+        const { execSync } = await import('node:child_process');
+        try {
+            execSync(buildKillStalePortsCommand(), { timeout: 5000, stdio: 'pipe' });
+        }
+        catch { }
+        try {
+            execSync('systemctl --user is-active --quiet dsh-web.service && systemctl --user restart dsh-web.service || systemctl --user start dsh-web.service', { timeout: 15000, stdio: 'pipe' });
+            return;
+        }
+        catch { }
+        try {
+            execSync('systemctl --user start dsh-web.service', { timeout: 15000, stdio: 'pipe' });
+            return;
+        }
+        catch { }
+        const { resolveDeepseekHarnessDir } = await import('./paths.js');
+        const harnessRoot = resolveDeepseekHarnessDir();
+        const logPath = path.join(os.homedir(), '.dsh/dsh-web.log');
+        execSync(`setsid nohup bash -c 'export NVM_DIR="$HOME/.nvm"; [ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"; cd ${JSON.stringify(harnessRoot)} && exec node --import tsx/esm apps/cli/src/bin.ts web --no-open >> ${JSON.stringify(logPath)} 2>&1' &`, { timeout: 5000 });
+    }
     getRunDebugAgent() {
         return this.deps.runDebugAgent ?? runDebugAgent;
     }
@@ -139,6 +177,28 @@ export class Supervisor {
         catch { }
         return 5 * 60 * 1000; // default 5 minutes
     }
+    async getEffectiveIntervalMs() {
+        if (this.deps.intervalMs !== undefined)
+            return this.deps.intervalMs;
+        try {
+            const cfg = await readSupervisorConfig();
+            if (typeof cfg.intervalMs === 'number' && cfg.intervalMs > 0)
+                return cfg.intervalMs;
+        }
+        catch { }
+        return 3000;
+    }
+    async getEffectiveDownThreshold() {
+        if (this.deps.downThreshold !== undefined)
+            return this.deps.downThreshold;
+        try {
+            const cfg = await readSupervisorConfig();
+            if (typeof cfg.downThreshold === 'number' && cfg.downThreshold > 0)
+                return cfg.downThreshold;
+        }
+        catch { }
+        return 3;
+    }
     async findInterruptedRecent(withinMs) {
         const ms = withinMs ?? this.getResumeWithinMs();
         // Prefer injected mock for testability
@@ -231,44 +291,119 @@ export class Supervisor {
     }
     async tick() {
         const health = await this.deps.pollHealth();
-        // DEGRADED: http 200 but log has plugin error → report, notify, no rollback
+        // DEGRADED: http 200 but log has plugin error → report + notify, rollback after consecutive threshold
         if (health.degraded) {
+            this.consecutiveDown = 0;
+            // Check suppression first — don't count degraded during planned restart grace
+            let suppressedByMarkerDeg = false;
+            try {
+                suppressedByMarkerDeg = this.getCheckPlannedRestart()();
+            }
+            catch {
+                suppressedByMarkerDeg = false;
+            }
+            if (suppressedByMarkerDeg) {
+                this.consecutiveDegraded = 0;
+                return;
+            }
+            if (this.deps.isPlannedRestartActive) {
+                let planned = false;
+                try {
+                    planned = await Promise.resolve(this.deps.isPlannedRestartActive());
+                }
+                catch {
+                    planned = false;
+                }
+                if (planned) {
+                    this.consecutiveDegraded = 0;
+                    return;
+                }
+            }
             const now = this.deps.getTime ? this.deps.getTime() : Date.now();
-            if (now - this.lastDegradedNotify < 60000)
+            // degraded needs 3 consecutive (not downThreshold which tests set to 1) to avoid flapping
+            const degradedThreshold = 3;
+            this.consecutiveDegraded++;
+            if (this.consecutiveDegraded < degradedThreshold) {
+                if (now - this.lastDegradedNotify < 60000)
+                    return;
+                this.lastDegradedNotify = now;
+                try {
+                    const ts = new Date().toISOString().replace(/[:.]/g, '-');
+                    const logTail = health.logTail ?? '';
+                    const gitDiff = await this.collectGitDiff().catch(() => '');
+                    const reportPath = await this.deps.writeReport({ ts, health, action: `degraded — ${health.error ?? 'plugin'}`, logTail, gitDiff }).catch(() => '');
+                    await this.deps.notify(`DEGRADED: ${health.error ?? 'plugin'} (report: ${reportPath})`).catch(() => { });
+                    const runner = this.getRunDebugAgent();
+                    const isInjected = !!this.deps.runDebugAgent;
+                    if (isInjected) {
+                        void runner({ reportPath, health }).then(res => this.handleDebugResult(reportPath, res)).catch(() => { });
+                        setTimeout(() => {
+                            this.findInterruptedRecent().then(r => {
+                                if (r.interrupted.length)
+                                    void this.attemptAutoResume(r.interrupted).catch(() => { });
+                            }).catch(() => { });
+                        }, 0);
+                    }
+                    else if (!process.env.VITEST) {
+                        void runner({ reportPath, health }).then(res => this.handleDebugResult(reportPath, res)).catch(() => { });
+                        setTimeout(() => {
+                            this.findInterruptedRecent().then(r => {
+                                if (r.interrupted.length)
+                                    void this.attemptAutoResume(r.interrupted).catch(() => { });
+                            }).catch(() => { });
+                        }, 0);
+                    }
+                }
+                catch { }
                 return;
-            this.lastDegradedNotify = now;
+            }
+            // consecutive degraded threshold reached → treat as down: rollback + restart
+            this.consecutiveDegraded = 0;
+            const degradedError = health.error ?? 'degraded plugin error';
+            if (this.rollingBack)
+                return;
+            const now2 = this.deps.getTime ? this.deps.getTime() : Date.now();
+            const debounceMs2 = this.deps.debounceMs ?? 60000;
+            if (now2 - this.lastRollback < debounceMs2)
+                return;
+            this.rollingBack = true;
+            this.lastRollback = now2;
             try {
-                const ts = new Date().toISOString().replace(/[:.]/g, '-');
-                const logTail = health.logTail ?? '';
-                const gitDiff = await this.collectGitDiff().catch(() => '');
-                const reportPath = await this.deps.writeReport({ ts, health, action: `degraded — ${health.error ?? 'plugin'}`, logTail, gitDiff }).catch(() => '');
-                await this.deps.notify(`DEGRADED: ${health.error ?? 'plugin'} (report: ${reportPath})`).catch(() => { });
-                // Phase 3: debug + resume — use injected fn if provided (even in VITEST), otherwise fire-and-forget real impl (skip in VITEST)
-                const runner = this.getRunDebugAgent();
-                const isInjected = !!this.deps.runDebugAgent;
-                if (isInjected) {
-                    void runner({ reportPath, health }).then(res => this.handleDebugResult(reportPath, res)).catch(() => { });
-                    setTimeout(() => {
-                        this.findInterruptedRecent().then(r => {
-                            if (r.interrupted.length)
-                                void this.attemptAutoResume(r.interrupted).catch(() => { });
-                        }).catch(() => { });
-                    }, 0);
+                const failed = await this.deps.writeFailed().catch(() => ({ ts: new Date().toISOString().replace(/[:.]/g, '-'), manifest: null }));
+                const ts2 = failed?.ts ?? new Date().toISOString().replace(/[:.]/g, '-');
+                const logTail2 = health.logTail ?? '';
+                const gitDiff2 = await this.collectGitDiff().catch(() => '');
+                const degradedHealth = { up: false, httpCode: health.httpCode, error: `degraded → down: ${degradedError}`, logTail: logTail2, degraded: false };
+                const reportPath2 = await this.deps.writeReport({ ts: ts2, health: degradedHealth, action: `rollback — degraded: ${degradedError}`, logTail: logTail2, gitDiff: gitDiff2 }).catch(() => '');
+                try {
+                    await this.deps.rollback();
+                }
+                catch (e) {
+                    await this.deps.notify(`rollback failed: ${e?.message ?? String(e)} (report: ${reportPath2})`).catch(() => { });
                 }
-                else if (!process.env.VITEST) {
-                    void runner({ reportPath, health }).then(res => this.handleDebugResult(reportPath, res)).catch(() => { });
-                    setTimeout(() => {
-                        this.findInterruptedRecent().then(r => {
-                            if (r.interrupted.length)
-                                void this.attemptAutoResume(r.interrupted).catch(() => { });
-                        }).catch(() => { });
-                    }, 0);
+                if (this.deps.restartWeb) {
+                    try {
+                        await this.deps.restartWeb();
+                        await this.deps.notify(`restarted dsh-web after rollback (report: ${reportPath2})`).catch(() => { });
+                    }
+                    catch (e) {
+                        await this.deps.notify(`restart dsh-web failed: ${e?.message ?? String(e)} (report: ${reportPath2})`).catch(() => { });
+                    }
                 }
+                await this.deps.notify(`DEGRADED → rollback (report: ${reportPath2}, error: ${degradedError})`).catch(() => { });
+                try {
+                    await this.deps.notify(`🔄 dsh web auto-restart — degraded: ${degradedError} — ${new Date().toISOString()}`).catch(() => { });
+                }
+                catch { }
+            }
+            finally {
+                this.rollingBack = false;
             }
-            catch { }
             return;
         }
         if (health.up) {
+            this.consecutiveDown = 0;
+            this.consecutiveDegraded = 0;
             // 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) {
@@ -282,6 +417,57 @@ export class Supervisor {
             }
             return;
         }
+        // Single-owner 30s marker: planned restart in progress — suppress crash
+        // handling entirely for 30s (no writeFailed/writeReport/rollback).
+        // Check both the new JSON marker (writePlannedRestart) and the legacy
+        // isPlannedRestartActive (dsh-safe-web-update plain file) for compat.
+        let suppressedByMarker = false;
+        try {
+            suppressedByMarker = this.getCheckPlannedRestart()();
+        }
+        catch {
+            suppressedByMarker = false;
+        }
+        if (suppressedByMarker) {
+            this.consecutiveDown = 0;
+            return;
+        }
+        // Down while an intentional restart (e.g. dsh-safe-web-update) is in
+        // flight is expected, not a crash — never race it with our own
+        // rollback/restartWeb.
+        if (this.deps.isPlannedRestartActive) {
+            let planned = false;
+            try {
+                planned = await Promise.resolve(this.deps.isPlannedRestartActive());
+            }
+            catch {
+                planned = false;
+            }
+            if (planned) {
+                this.consecutiveDown = 0;
+                return;
+            }
+        }
+        // Down — require consecutive confirmations before treating as a crash.
+        // A lone timed-out poll (e.g. a slow plugin-tree boot) must not trigger
+        // rollback/restart: that restart produces its own transient errors on
+        // the next poll, which would otherwise re-trigger this same path forever.
+        this.consecutiveDown++;
+        let downThreshold = await this.getEffectiveDownThreshold();
+        // When a planned restart marker is active, double the threshold (3→6 at
+        // 3s interval ≈ 9s→18s). Health-poller already suppresses fetch failed in
+        // this window, but supervisor also doubles so a transient that escapes
+        // health still needs longer to trigger. The early return above already
+        // suppresses fully for 30s; doubling remains for the legacy
+        // isPlannedRestartActive path and for any race where the marker was
+        // written between the early check and this line.
+        try {
+            if (this.getCheckPlannedRestart()())
+                downThreshold *= 2;
+        }
+        catch { }
+        if (this.consecutiveDown < downThreshold)
+            return;
         // Down — check debounce and rolling state
         if (this.rollingBack)
             return;
@@ -290,6 +476,7 @@ export class Supervisor {
         if (now - this.lastRollback < debounceMs)
             return;
         this.rollingBack = true;
+        this.consecutiveDown = 0;
         this.lastRollback = now;
         try {
             const failed = await this.deps.writeFailed().catch(() => ({ ts: new Date().toISOString().replace(/[:.]/g, '-'), manifest: null }));
@@ -339,14 +526,18 @@ export class Supervisor {
             this.rollingBack = false;
         }
     }
-    start() {
+    async start() {
         if (this.timer)
             return;
-        const intervalMs = this.deps.intervalMs ?? 3000;
+        const intervalMs = await this.getEffectiveIntervalMs();
         this.timer = setInterval(() => { this.tick().catch(() => { }); }, intervalMs);
         // Immediate tick so a reboot is recovered in ~0-3s, not 3s
         this.tick().catch(() => { });
     }
+    // Synchronous start wrapper for callers that do not await (daemon cli fire-and-forget)
+    startSync() {
+        void this.start();
+    }
     stop() {
         if (this.timer) {
             clearInterval(this.timer);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ddtcorex/dsh-maestro-supervisor",
-  "version": "0.6.4",
+  "version": "0.6.6",
   "description": "Supervisor daemon for DSH Web resilience — auto-detect crashes, rollback to LKG, report",
   "type": "module",
   "main": "./lib/index.js",
@@ -36,6 +36,9 @@
     "README.md",
     "cordis.patch.yml"
   ],
+  "dependencies": {
+    "@ddtcorex/dsh-maestro-config-lib": "^0.1.2"
+  },
   "devDependencies": {
     "@types/node": "^26.3.0",
     "typescript": "^5.9.3",
@@ -44,7 +47,7 @@
   "scripts": {
     "build": "tsc -p tsconfig.json && tsc -p tsconfig.client.json && node scripts/build-client.mjs",
     "verify": "tsc --noEmit && tsc -p tsconfig.client.json --noEmit",
-    "test": "vitest run",
+    "test": "vitest run --testTimeout=10000",
     "test:watch": "vitest"
   }
 }