@ddtcorex/dsh-maestro-supervisor 0.8.0 → 0.8.2

package/lib/boot-guard.d.ts

@@ -0,0 +1,33 @@
+import { type BootLockDeps } from './boot-lock.js';
+/**
+ * D6 — one restart implementation per concern.
+ *
+ * `performSingleBootRestart` (the daemon's path) takes `boot.lock` and appends
+ * the `[supervisor] boot-boundary` sentinel through `markBootBoundary()`. The
+ * manual skill script (`skills/dsh-safe-restart/scripts/restart-dsh-web.sh`)
+ * must do exactly the same, or a human restart is neither serialized with a
+ * supervised one (two boots racing for :3082) nor scoped in the append-only log
+ * (the poller reads the previous boot's crash as this boot's).
+ *
+ * This module is that shared entry point: the script shells out to
+ * `lib/bin.js boot-guard acquire|release --pid <shell pid>` instead of writing
+ * either marker itself.
+ */
+/** Log the boundary sentinel belongs to (isolated home wins when set, for rehearsals). */
+export declare function bootBoundaryLogPath(env?: NodeJS.ProcessEnv): string;
+export interface BootGuard {
+    acquired: boolean;
+    release: () => void;
+}
+/**
+ * Acquire the shared boot lock for `deps.pid` and append the boundary sentinel.
+ * The sentinel is written first-thing after the lock, matching
+ * `performSingleBootRestart` (marker before the port goes down).
+ */
+export declare function acquireBootGuard(deps?: BootLockDeps, logPath?: string): BootGuard;
+/** Release the lock only if `pid` still owns it (see releaseBootLock). */
+export declare function releaseBootGuard(pid: number, deps?: BootLockDeps): boolean;
+export declare const BOOT_GUARD_BUSY_EXIT = 3;
+export declare const BOOT_GUARD_USAGE_EXIT = 64;
+/** CLI used by the skill script; returns the process exit code. */
+export declare function runBootGuardCli(args: string[], deps?: BootLockDeps, logPath?: string): number;

package/lib/boot-guard.js

@@ -0,0 +1,68 @@
+import * as path from 'node:path';
+import { acquireBootLock, releaseBootLock } from './boot-lock.js';
+import { markBootBoundary, dshWebLogPath } from './restart-guards.js';
+/**
+ * D6 — one restart implementation per concern.
+ *
+ * `performSingleBootRestart` (the daemon's path) takes `boot.lock` and appends
+ * the `[supervisor] boot-boundary` sentinel through `markBootBoundary()`. The
+ * manual skill script (`skills/dsh-safe-restart/scripts/restart-dsh-web.sh`)
+ * must do exactly the same, or a human restart is neither serialized with a
+ * supervised one (two boots racing for :3082) nor scoped in the append-only log
+ * (the poller reads the previous boot's crash as this boot's).
+ *
+ * This module is that shared entry point: the script shells out to
+ * `lib/bin.js boot-guard acquire|release --pid <shell pid>` instead of writing
+ * either marker itself.
+ */
+/** Log the boundary sentinel belongs to (isolated home wins when set, for rehearsals). */
+export function bootBoundaryLogPath(env = process.env) {
+    if (env.DSH_WEB_LOG)
+        return env.DSH_WEB_LOG;
+    if (env.DSH_HOME)
+        return path.join(env.DSH_HOME, 'dsh-web.log');
+    return dshWebLogPath();
+}
+/**
+ * Acquire the shared boot lock for `deps.pid` and append the boundary sentinel.
+ * The sentinel is written first-thing after the lock, matching
+ * `performSingleBootRestart` (marker before the port goes down).
+ */
+export function acquireBootGuard(deps = {}, logPath) {
+    const lock = acquireBootLock(deps);
+    if (!lock)
+        return { acquired: false, release: () => { } };
+    markBootBoundary(logPath ?? bootBoundaryLogPath());
+    return { acquired: true, release: lock.release };
+}
+/** Release the lock only if `pid` still owns it (see releaseBootLock). */
+export function releaseBootGuard(pid, deps = {}) {
+    return releaseBootLock(pid, deps);
+}
+export const BOOT_GUARD_BUSY_EXIT = 3;
+export const BOOT_GUARD_USAGE_EXIT = 64;
+/** CLI used by the skill script; returns the process exit code. */
+export function runBootGuardCli(args, deps = {}, logPath) {
+    const action = args[0];
+    const pidIdx = args.indexOf('--pid');
+    const pid = pidIdx === -1 ? Number.NaN : Number(args[pidIdx + 1]);
+    if (!Number.isInteger(pid) || pid <= 0) {
+        console.error('boot-guard: --pid <owner pid> is required (pass the shell PID: $$)');
+        return BOOT_GUARD_USAGE_EXIT;
+    }
+    if (action === 'acquire') {
+        const guard = acquireBootGuard({ ...deps, pid }, logPath);
+        if (!guard.acquired) {
+            console.error('busy: another boot holds boot.lock');
+            return BOOT_GUARD_BUSY_EXIT;
+        }
+        console.log('acquired');
+        return 0;
+    }
+    if (action === 'release') {
+        releaseBootGuard(pid, deps);
+        return 0;
+    }
+    console.error(`boot-guard: unknown action: ${action ?? ''} (expected acquire|release)`);
+    return BOOT_GUARD_USAGE_EXIT;
+}

package/lib/boot-lock.d.ts

@@ -0,0 +1,56 @@
+/**
+ * One-boot-at-a-time guard (spec D4, incident 2026-09-13). Every path that
+ * starts dsh web takes this lock from the moment the restart is issued until
+ * the port answers, so a racing tick, the dsh_web_restart hand-off, or a
+ * rollback that fires while the first boot is still coming up skips instead of
+ * producing the second systemd start that made the incident's log tail toxic.
+ *
+ * The lock is an atomically created file (`O_EXCL`) carrying `{pid, ts}`. An
+ * existing lock is honored unless its owner is gone or it has outlived
+ * `staleMs` (the boot budget). Node exposes no flock(2) binding; O_EXCL plus
+ * PID liveness gives the same mutual exclusion deterministically, and every
+ * side effect is injectable so tests never touch the real ~/.dsh/.supervisor.
+ */
+export declare const DEFAULT_BOOT_LOCK_STALE_MS = 180000;
+export interface BootLockDeps {
+    lockPath?: string;
+    createExclusive?: (p: string, body: string) => boolean;
+    readLock?: (p: string) => string | undefined;
+    remove?: (p: string) => void;
+    pidAlive?: (pid: number) => boolean;
+    now?: () => number;
+    staleMs?: number;
+    sleep?: (ms: number) => Promise<void>;
+    portUp?: () => Promise<boolean>;
+    waitTimeoutMs?: number;
+    pollMs?: number;
+    /**
+     * Owner recorded in the lock file; defaults to this process. The skill script
+     * (D6) holds the lock with the shell's own PID, so liveness stays meaningful
+     * while the shell performs the restart.
+     */
+    pid?: number;
+}
+export interface BootLock {
+    path: string;
+    release: () => void;
+}
+export declare function bootLockPath(): string;
+/** Take the boot lock, or return undefined when another live boot owns it. */
+export declare function acquireBootLock(deps?: BootLockDeps): BootLock | undefined;
+/**
+ * Release the lock only when `pid` still owns it. A boot that lost the race (or
+ * whose stale lock was taken over) must never delete the winner's lock file.
+ */
+export declare function releaseBootLock(pid: number, deps?: BootLockDeps): boolean;
+/** Poll the port until it answers or the boot budget expires. */
+export declare function waitForPort(deps?: BootLockDeps): Promise<boolean>;
+/**
+ * Run `fn` under the boot lock, then hold the lock until the port answers (or
+ * the boot budget expires). Returns `{ acquired: false }` — without running
+ * `fn` — when another boot already owns the lock.
+ */
+export declare function withBootLock<T>(fn: () => Promise<T>, deps?: BootLockDeps): Promise<{
+    acquired: boolean;
+    value?: T;
+}>;

package/lib/boot-lock.js

@@ -0,0 +1,155 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+/**
+ * One-boot-at-a-time guard (spec D4, incident 2026-09-13). Every path that
+ * starts dsh web takes this lock from the moment the restart is issued until
+ * the port answers, so a racing tick, the dsh_web_restart hand-off, or a
+ * rollback that fires while the first boot is still coming up skips instead of
+ * producing the second systemd start that made the incident's log tail toxic.
+ *
+ * The lock is an atomically created file (`O_EXCL`) carrying `{pid, ts}`. An
+ * existing lock is honored unless its owner is gone or it has outlived
+ * `staleMs` (the boot budget). Node exposes no flock(2) binding; O_EXCL plus
+ * PID liveness gives the same mutual exclusion deterministically, and every
+ * side effect is injectable so tests never touch the real ~/.dsh/.supervisor.
+ */
+export const DEFAULT_BOOT_LOCK_STALE_MS = 180_000;
+export function bootLockPath() {
+    return process.env.DSH_SUPERVISOR_BOOT_LOCK ?? path.join(os.homedir(), '.dsh/.supervisor/boot.lock');
+}
+function resolved(deps) {
+    return {
+        lockPath: deps.lockPath ?? bootLockPath(),
+        createExclusive: deps.createExclusive ?? ((p, body) => {
+            try {
+                fs.mkdirSync(path.dirname(p), { recursive: true });
+                fs.writeFileSync(p, body, { flag: 'wx', mode: 0o600 });
+                return true;
+            }
+            catch {
+                return false;
+            }
+        }),
+        readLock: deps.readLock ?? ((p) => {
+            try {
+                return fs.readFileSync(p, 'utf8');
+            }
+            catch {
+                return undefined;
+            }
+        }),
+        remove: deps.remove ?? ((p) => { try {
+            fs.unlinkSync(p);
+        }
+        catch { } }),
+        pidAlive: deps.pidAlive ?? ((pid) => {
+            if (!Number.isInteger(pid) || pid <= 0)
+                return false;
+            if (pid === process.pid)
+                return true;
+            try {
+                process.kill(pid, 0);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        }),
+        now: deps.now ?? (() => Date.now()),
+        staleMs: deps.staleMs ?? DEFAULT_BOOT_LOCK_STALE_MS,
+        sleep: deps.sleep ?? ((ms) => new Promise(r => setTimeout(r, ms))),
+        portUp: deps.portUp ?? defaultPortUp,
+        waitTimeoutMs: deps.waitTimeoutMs ?? DEFAULT_BOOT_LOCK_STALE_MS,
+        pollMs: deps.pollMs ?? 3_000,
+        pid: deps.pid ?? process.pid,
+    };
+}
+function parseLock(raw) {
+    if (!raw)
+        return undefined;
+    try {
+        const j = JSON.parse(raw);
+        if (typeof j?.pid === 'number' && typeof j?.ts === 'number')
+            return { pid: j.pid, ts: j.ts };
+    }
+    catch { }
+    return undefined;
+}
+/** Take the boot lock, or return undefined when another live boot owns it. */
+export function acquireBootLock(deps = {}) {
+    const d = resolved(deps);
+    const body = JSON.stringify({ pid: d.pid, ts: d.now() });
+    const take = () => d.createExclusive(d.lockPath, body) ? { path: d.lockPath, release: () => d.remove(d.lockPath) } : undefined;
+    const first = take();
+    if (first)
+        return first;
+    const existing = parseLock(d.readLock(d.lockPath));
+    const stale = existing === undefined || !d.pidAlive(existing.pid) || d.now() - existing.ts > d.staleMs;
+    if (!stale)
+        return undefined;
+    d.remove(d.lockPath);
+    return take();
+}
+/**
+ * Release the lock only when `pid` still owns it. A boot that lost the race (or
+ * whose stale lock was taken over) must never delete the winner's lock file.
+ */
+export function releaseBootLock(pid, deps = {}) {
+    const d = resolved(deps);
+    const existing = parseLock(d.readLock(d.lockPath));
+    if (existing === undefined || existing.pid !== pid)
+        return false;
+    d.remove(d.lockPath);
+    return true;
+}
+async function defaultPortUp() {
+    try {
+        const ctrl = new AbortController();
+        const t = setTimeout(() => ctrl.abort(), 2000);
+        try {
+            // Any HTTP answer (200/303/401) means the boot is serving.
+            await fetch('http://127.0.0.1:3080/', { signal: ctrl.signal });
+            return true;
+        }
+        finally {
+            clearTimeout(t);
+        }
+    }
+    catch {
+        return false;
+    }
+}
+/** Poll the port until it answers or the boot budget expires. */
+export async function waitForPort(deps = {}) {
+    const d = resolved(deps);
+    const deadline = d.now() + d.waitTimeoutMs;
+    for (;;) {
+        try {
+            if (await d.portUp())
+                return true;
+        }
+        catch { }
+        if (d.now() >= deadline)
+            return false;
+        await d.sleep(d.pollMs);
+    }
+}
+/**
+ * Run `fn` under the boot lock, then hold the lock until the port answers (or
+ * the boot budget expires). Returns `{ acquired: false }` — without running
+ * `fn` — when another boot already owns the lock.
+ */
+export async function withBootLock(fn, deps = {}) {
+    const lock = acquireBootLock(deps);
+    if (!lock)
+        return { acquired: false };
+    try {
+        const value = await fn();
+        await waitForPort(deps);
+        return { acquired: true, value };
+    }
+    finally {
+        lock.release();
+    }
+}

package/lib/cli.d.ts

@@ -1,14 +1,31 @@
+export interface RestoreResult {
+    /** Snapshot id that was restored. */
+    target: string;
+    /** Files (and symlinks) restored into the live DSH home. */
+    restored: number;
+    /** Entries that were not restored, each with a reason. Never silent. */
+    skipped: Array<{
+        path: string;
+        reason: string;
+    }>;
+}
 /**
  * Copy a chosen LKG snapshot back into the DSH home. Recent snapshots are
  * tried newest-first, skipping any that still carry a failing plugin so a
- * broken bundle is not restored. `sessions/` is deliberately NOT restored —
- * session logs are append-only truth and rolling them back to a snapshot
- * would drop every turn recorded after that snapshot.
- * @returns the rolled-back snapshot id.
+ * broken bundle is not restored. `sessions/` and every other runtime-data entry
+ * is deliberately NOT restored (D1) — session logs are append-only truth and
+ * rolling them back to a snapshot would drop every turn recorded after that
+ * snapshot.
+ *
+ * Never throws for a per-entry failure: the failures are collected into
+ * `skipped` and the caller reports them (D2/D4). The only throw left is "there
+ * is no snapshot at all", which the caller must know about.
+ *
+ * @returns the restore summary (snapshot id + what was/was not restored).
  */
 export declare function rollbackLKG(opts: {
     dshHome: string;
     lkgRoot: string;
     failingPlugin?: string;
-}): Promise<string>;
+}): Promise<RestoreResult>;
 export declare function runCli(args: string[]): Promise<void>;

package/lib/cli.js

@@ -1,18 +1,93 @@
 import { Supervisor } from './supervisor.js';
 import { pollHealth } from './health-poller.js';
-import { writeLKG, verifyLKG } from './snapshot.js';
+import { writeLKG, verifyLKG, isLkgExcluded, failureReason } from './snapshot.js';
 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, readRestartRequest, clearPlannedRestart } from './restart-guards.js';
+import { resolveHarnessRoot } from './paths.js';
+import { isSelfCopyError, checkPlannedRestart, readRestartRequest, clearPlannedRestart } from './restart-guards.js';
+import { readSupervisorConfig } from './config.js';
+/**
+ * Make a destination (recursively) writable before overwriting it (D3).
+ *
+ * `fs.cpSync` copies into an existing destination file with
+ * `O_WRONLY|O_CREAT|O_TRUNC`, so a mode-`0400` object fails with EACCES and
+ * aborts the whole restore — the exact 2026-09-13 failure
+ * (`EACCES, Permission denied '.../attachments/v1/objects/f8'`). Only entries
+ * that actually lack the needed bit are chmod-ed, so a healthy tree costs
+ * stats, not a chmod per file.
+ */
+function makeWritable(target) {
+    let st;
+    try {
+        st = fs.lstatSync(target);
+    }
+    catch {
+        return;
+    }
+    if (st.isSymbolicLink())
+        return;
+    if (st.isDirectory()) {
+        if ((st.mode & 0o300) !== 0o300) {
+            try {
+                fs.chmodSync(target, st.mode | 0o300);
+            }
+            catch { }
+        }
+        let names = [];
+        try {
+            names = fs.readdirSync(target);
+        }
+        catch {
+            return;
+        }
+        for (const name of names)
+            makeWritable(path.join(target, name));
+        return;
+    }
+    if ((st.mode & 0o200) === 0) {
+        try {
+            fs.chmodSync(target, st.mode | 0o200);
+        }
+        catch { }
+    }
+}
+/** Files (and symlinks) a restore of this source entry would write. */
+function countRestorable(srcPath) {
+    try {
+        const st = fs.lstatSync(srcPath);
+        if (st.isDirectory())
+            return walkFiles(srcPath).length;
+        return 1;
+    }
+    catch {
+        return 0;
+    }
+}
+function walkFiles(dir, base = dir) {
+    const out = [];
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory())
+            out.push(...walkFiles(full, base));
+        else if (entry.isFile())
+            out.push(path.relative(base, full));
+    }
+    return out;
+}
 /**
  * Copy a chosen LKG snapshot back into the DSH home. Recent snapshots are
  * tried newest-first, skipping any that still carry a failing plugin so a
- * broken bundle is not restored. `sessions/` is deliberately NOT restored —
- * session logs are append-only truth and rolling them back to a snapshot
- * would drop every turn recorded after that snapshot.
- * @returns the rolled-back snapshot id.
+ * broken bundle is not restored. `sessions/` and every other runtime-data entry
+ * is deliberately NOT restored (D1) — session logs are append-only truth and
+ * rolling them back to a snapshot would drop every turn recorded after that
+ * snapshot.
+ *
+ * Never throws for a per-entry failure: the failures are collected into
+ * `skipped` and the caller reports them (D2/D4). The only throw left is "there
+ * is no snapshot at all", which the caller must know about.
+ *
+ * @returns the restore summary (snapshot id + what was/was not restored).
  */
 export async function rollbackLKG(opts) {
     const { dshHome, lkgRoot, failingPlugin } = opts;
@@ -49,11 +124,16 @@ export async function rollbackLKG(opts) {
     }
     const target = chosen ?? entries[entries.length - 1];
     const src = path.join(lkgRoot, target);
+    const skipped = [];
+    let restored = 0;
     for (const entry of fs.readdirSync(src)) {
         if (entry === 'manifest.json')
             continue;
-        if (entry === 'sessions') {
-            console.log('[supervisor] rollback keeps live sessions (append-only truth) — skipping sessions/');
+        if (isLkgExcluded(entry)) {
+            // Legacy snapshots (taken before D1) still carry runtime data. Restoring
+            // a stale sessions/ over live sessions can lose a log, and a 0400
+            // attachment blob is what aborted this very path — report, never restore.
+            skipped.push({ path: entry, reason: 'runtime data excluded from the LKG scope (not required to boot)' });
             continue;
         }
         const srcPath = path.join(src, entry);
@@ -65,15 +145,17 @@ export async function rollbackLKG(opts) {
                     continue;
             }
             catch { }
+            makeWritable(destPath);
             fs.cpSync(srcPath, destPath, { recursive: true, force: true });
+            restored += countRestorable(srcPath);
         }
         catch (e) {
             if (isSelfCopyError(String(e?.message ?? '')))
                 continue;
-            throw e;
+            skipped.push({ path: entry, reason: failureReason(e) });
         }
     }
-    return target;
+    return { target, restored, skipped };
 }
 export async function runCli(args) {
     const cmd = args[2] ?? '--help';
@@ -86,9 +168,14 @@ Commands:
   logs       Tail supervisor reports
   rollback --to <ts>  Rollback to LKG <ts>
   resume [--within <dur>]  List interrupted sessions (filter by time, e.g. 5m, 30s, 1h)
+  boot-guard acquire|release --pid <pid>  Take/release boot.lock + boot-boundary (used by the safe-restart script)
 `);
         return;
     }
+    if (cmd === 'boot-guard') {
+        const { runBootGuardCli } = await import('./boot-guard.js');
+        process.exit(runBootGuardCli(args.slice(3)));
+    }
     if (cmd === 'status') {
         const health = await pollHealth();
         console.log(`up: ${health.up}, httpCode: ${health.httpCode}, error: ${health.error ?? 'none'}`);
@@ -186,8 +273,16 @@ Commands:
                         failingPlugin = m[0].replace(/^@ddtcorex\//, '');
                 }
                 catch { }
-                const target = await rollbackLKG({ dshHome, lkgRoot, failingPlugin });
-                console.log(`[supervisor] rolled back to ${target}${failingPlugin ? ` (avoiding ${failingPlugin})` : ''}`);
+                const res = await rollbackLKG({ dshHome, lkgRoot, failingPlugin });
+                console.log(`[supervisor] rolled back to ${res.target} — ${res.restored} file(s) restored${failingPlugin ? ` (avoiding ${failingPlugin})` : ''}`);
+                // D4: a partial restore is surfaced loudly, never silently.
+                if (res.skipped.length) {
+                    console.log(`[supervisor] ROLLBACK PARTIAL: ${res.skipped.length} entr(ies) not restored`);
+                    for (const s of res.skipped.slice(0, 10))
+                        console.log(`[supervisor]   skipped ${s.path}: ${s.reason}`);
+                    if (res.skipped.length > 10)
+                        console.log(`[supervisor]   … ${res.skipped.length - 10} more`);
+                }
                 // Reconcile node_modules from restored package.json (critical for link: deps)
                 try {
                     execSync('pnpm --dir ~/.dsh/profiles/web install --silent', { timeout: 30000, stdio: 'pipe' });
@@ -196,52 +291,23 @@ Commands:
                 catch (e) {
                     console.log(`[supervisor] pnpm install failed: ${e?.message ?? String(e)}`);
                 }
+                return res;
             },
             restartWeb: async () => {
-                const { execSync } = await import('node:child_process');
-                // Single-owner: mark planned restart 30s before any systemctl/nohup
-                // so pollHealth + tick suppress the transient down (no double restart).
+                // One implementation of the single-boot restart: marker (TTL = boot
+                // budget) → boot.lock → serialized systemd start → direct-node nohup
+                // only on hosts where the unit does not exist (D4/D5).
+                const { performSingleBootRestart, DEFAULT_BOOT_GRACE_MS } = await import('./restart-web.js');
+                let grace = DEFAULT_BOOT_GRACE_MS;
                 try {
-                    writePlannedRestart(30000);
+                    const cfg = await readSupervisorConfig();
+                    if (typeof cfg.bootGraceMs === 'number' && cfg.bootGraceMs > 0)
+                        grace = cfg.bootGraceMs;
                 }
                 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(buildKillStalePortsCommand(), { timeout: 5000, stdio: 'pipe' });
-                }
-                catch { }
-                // Prefer systemd — if dsh-web.service is installed, restart/start it
-                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' });
-                    console.log('[supervisor] restarted dsh-web via systemd');
-                    return;
-                }
-                catch { }
-                // Check if unit exists but not active — try start
-                try {
-                    execSync('systemctl --user start dsh-web.service', { timeout: 15000, stdio: 'pipe' });
-                    console.log('[supervisor] started dsh-web via systemd (fallback)');
-                    return;
-                }
-                catch { }
-                // Last fallback: detached direct node (portable — sources nvm directly, falls back to system node)
-                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)');
-                }
-                catch (e) {
-                    throw new Error(`restartWeb failed: ${e?.message ?? String(e)}`);
-                }
+                const res = await performSingleBootRestart({ bootGraceMs: grace });
+                if (!res.restarted)
+                    console.log(`[supervisor] restart skipped: ${res.reason ?? 'boot lock held'}`);
             },
             notify: async (msg) => console.log(`[notify] ${msg}`),
             isPlannedRestartActive: () => checkPlannedRestart(),

package/lib/health-poller.d.ts

@@ -4,8 +4,17 @@ export interface HealthState {
     error?: string;
     degraded?: boolean;
     logTail?: string;
+    /** Boot verdict for the unit start this poll observed (see bootFreshness). */
+    bootPhase?: BootFreshness;
 }
+/**
+ * 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 declare function getActiveEnterMs(): number | undefined;
+/** @deprecated kept for callers; identical to getActiveEnterMs(). */
 export declare function getActiveEnterWallMs(): number | undefined;
 export interface PollHealthOpts {
     fetch?: () => Promise<{
@@ -16,8 +25,66 @@ export interface PollHealthOpts {
     logTail?: () => Promise<string>;
     url?: string;
     timeoutMs?: number;
-    /** injectable for tests — overrides systemctl lookup */
+    /** injectable for tests — overrides the systemctl lookup */
     getActiveEnterMs?: () => number | undefined;
+    /** Wall-clock epoch ms of the current dsh-web unit start (see bootFreshness). */
+    activeEnterAtMs?: number;
+    /** Boot budget in ms; a younger boot without its own success marker is 'booting'. */
+    bootGraceMs?: number;
 }
+export type BootFreshness = 'unknown' | 'booting' | 'settled';
+/**
+ * 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 declare function bootFreshness(opts: {
+    activeEnterAtMs?: number;
+    now: number;
+    bootGraceMs: number;
+    /**
+     * Did THIS poll receive a serving response (200/401)?
+     *
+     * Deliberately not "the log shows `dsh web: http`": that line is printed the
+     * moment the raw webserver binds, seconds into a boot that can take ~90s to
+     * finish loading the plugin tree. Crediting it as proof ended the grace while
+     * the proxy in front was still coming up, so probes that hung during the rest
+     * of the boot were judged as crashes — the 2026-09-13 restart loop.
+     */
+    probeSucceeded: boolean;
+}): BootFreshness;
+/**
+ * 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 declare function classifyFetchFailure(err: unknown): 'refused' | 'timeout' | 'other';
+export declare const SUCCESS_MARKER = "dsh web: http";
+/** Index of the last boot-boundary line in the tail, or -1 when it predates the tail. */
+export declare function lastBootBoundaryIndex(lines: string[]): number;
+/** Index of the last "dsh web: http" success marker (`lowerLines` must be lower-cased). */
+export declare function lastSuccessMarkerIndex(lowerLines: string[]): number;
+/** Wall-clock ms parsed from a boot-boundary line, or undefined when unparseable. */
+export declare function parseBootBoundaryMs(line: string): number | undefined;
 export declare function pollHealth(opts?: PollHealthOpts): Promise<HealthState>;
 export declare function collectLogTail(): Promise<string>;