@ddtcorex/dsh-maestro-supervisor 0.8.0 → 0.8.2

package/lib/restart-tool.d.ts

@@ -12,7 +12,7 @@
  *      callerSessionId) that the supervisor daemon owns and acts on
  *      (out-of-band). This tool NEVER restarts the host in-tree.
  */
-import { writeRestartRequest } from './restart-guards.js';
+import { writeRestartRequest, readRestartRequest } from './restart-guards.js';
 /**
  * Copy a live profile tree for an isolated dry-boot. A naive recursive copy
  * breaks `link:` installs: their node_modules entries are relative symlinks
@@ -115,6 +115,7 @@ export declare function registerRestartTool(ctx: any, deps?: {
     sessionIdOf?: (exec: any) => string | undefined;
     dryBoot?: typeof dryBootVerify;
     writeRestartRequest?: typeof writeRestartRequest;
+    readRestartRequest?: typeof readRestartRequest;
     harnessRoot?: string;
     gcReaders?: GcReaders;
     killPid?: (pid: number, sig: string) => void;

package/lib/restart-tool.js

@@ -17,7 +17,7 @@ import { mkdtempSync, rmSync, cpSync, existsSync, readFileSync, readdirSync, sta
 import { tmpdir, homedir } from 'node:os';
 import { spawn, execFileSync } from 'node:child_process';
 import { createRequire } from 'node:module';
-import { writeRestartRequest } from './restart-guards.js';
+import { writeRestartRequest, readRestartRequest } from './restart-guards.js';
 import { intentPath, readIntent, readRestartOutcome } from './intents.js';
 /**
  * Copy a live profile tree for an isolated dry-boot. A naive recursive copy
@@ -306,6 +306,7 @@ function currentSessionId(exec, fallback) {
 export function registerRestartTool(ctx, deps = {}) {
     const doDryBoot = deps.dryBoot ?? dryBootVerify;
     const doWrite = deps.writeRestartRequest ?? writeRestartRequest;
+    const doRead = deps.readRestartRequest ?? readRestartRequest;
     const doSessionId = deps.sessionIdOf ?? currentSessionId;
     let dispose;
     let disposeDryboot;
@@ -328,6 +329,23 @@ export function registerRestartTool(ctx, deps = {}) {
                 render: (_args, value) => [{ type: 'text', text: value.detail }],
             },
             execute: async (args, exec) => {
+                // Serialize: a fresh restart-request marker means a restart is
+                // already in flight (another session, the daemon, or an earlier
+                // call of this tool). Scheduling another one overlaps the ~90s
+                // SIGTERM stop and crash-loops on EADDRINUSE — refuse fast, before
+                // the dry-boot gate, and point at the status tool instead.
+                let inflight;
+                try {
+                    inflight = doRead();
+                }
+                catch {
+                    inflight = undefined;
+                }
+                if (inflight !== undefined) {
+                    const by = inflight.callerSessionId ?? 'unknown session';
+                    const why = inflight.reason ? `: ${inflight.reason.slice(0, 120)}` : '';
+                    return { ok: false, detail: `restart already in progress (requested by ${by}${why}) — check dsh_web_restart_status instead of scheduling another` };
+                }
                 const harnessRoot = deps.harnessRoot ?? (await import('./paths.js')).resolveDeepseekHarnessDir();
                 const lkgDir = join(homedir(), '.dsh/.supervisor/lkg');
                 const changed = args.pluginChanged === true || (args.pluginChanged !== false && isPluginTreeChanged(harnessRoot, lkgDir));

package/lib/restart-web.d.ts

@@ -0,0 +1,26 @@
+import { type BootLockDeps } from './boot-lock.js';
+/** Boot budget: how long a boot may take before its failures are judged. */
+export declare const DEFAULT_BOOT_GRACE_MS = 180000;
+export interface RestartWebDeps {
+    exec?: (cmd: string, opts?: {
+        timeout?: number;
+    }) => void;
+    writeMarker?: (ttlMs?: number) => void;
+    serializedRestart?: () => Promise<void>;
+    startViaSystemd?: () => void;
+    spawnNohup?: () => void | Promise<void>;
+    unitExists?: () => boolean;
+    bootGraceMs?: number;
+    lock?: BootLockDeps;
+}
+export interface RestartWebResult {
+    restarted: boolean;
+    reason?: string;
+}
+/**
+ * The single implementation of a supervised dsh web restart. Single-flight:
+ * boot.lock is held from before the marker is written until the port answers,
+ * so a racing tick or a second rollback skips instead of producing the second
+ * systemd start that turned the incident's log tail toxic (2026-09-13).
+ */
+export declare function performSingleBootRestart(deps?: RestartWebDeps): Promise<RestartWebResult>;

package/lib/restart-web.js

@@ -0,0 +1,58 @@
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { buildKillStalePortsCommand, writePlannedRestart } from './restart-guards.js';
+import { serializedSystemdRestart, shouldUseNohupFallback, systemdUnitExists } from './restart-exec.js';
+import { withBootLock } from './boot-lock.js';
+import { resolveDeepseekHarnessDir } from './paths.js';
+/** Boot budget: how long a boot may take before its failures are judged. */
+export const DEFAULT_BOOT_GRACE_MS = 180_000;
+/**
+ * The single implementation of a supervised dsh web restart. Single-flight:
+ * boot.lock is held from before the marker is written until the port answers,
+ * so a racing tick or a second rollback skips instead of producing the second
+ * systemd start that turned the incident's log tail toxic (2026-09-13).
+ */
+export async function performSingleBootRestart(deps = {}) {
+    const grace = deps.bootGraceMs ?? DEFAULT_BOOT_GRACE_MS;
+    const outcome = await withBootLock(async () => {
+        // Marker first, and inside the lock: every poll during the boot must know a
+        // restart is in flight, and the TTL is the boot budget — not 30 s (D5).
+        ;
+        (deps.writeMarker ?? writePlannedRestart)(grace);
+        const { execSync } = await import('node:child_process');
+        const exec = deps.exec ?? ((cmd, opts) => {
+            execSync(cmd, { timeout: opts?.timeout ?? 15_000, stdio: 'pipe' });
+        });
+        // A stale MainThread holding :3080/:3082 survives an EADDRINUSE crash with
+        // http 200 still served, so the new start would lose the race.
+        try {
+            exec(buildKillStalePortsCommand(), { timeout: 5000 });
+        }
+        catch { }
+        try {
+            await (deps.serializedRestart ?? (() => serializedSystemdRestart()))();
+            return;
+        }
+        catch { }
+        try {
+            ;
+            (deps.startViaSystemd ?? (() => exec('systemctl --user start dsh-web.service', { timeout: 15_000 })))();
+            return;
+        }
+        catch { }
+        const unitExists = (deps.unitExists ?? systemdUnitExists)();
+        if (!shouldUseNohupFallback(unitExists)) {
+            throw new Error('systemd manages dsh-web.service but start failed — refusing the direct-node fallback (it would create a second boot)');
+        }
+        await (deps.spawnNohup ?? defaultNohup)();
+    }, deps.lock ?? {});
+    if (!outcome.acquired)
+        return { restarted: false, reason: 'another boot already holds boot.lock' };
+    return { restarted: true };
+}
+async function defaultNohup() {
+    const { execSync } = await import('node:child_process');
+    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 });
+}

package/lib/resume.d.ts

@@ -6,6 +6,16 @@ export interface FindInterruptedOpts {
     withinMs?: number;
     sinceMs?: number;
 }
+/**
+ * Resolve the readable session log inside one session directory across
+ * format generations. `session.v3.jsonl.zstd` is the current successor;
+ * `session.jsonl.zstd` / `session.jsonl` remain for committed older
+ * generations (migrations never move or delete them). Prefer v3 when
+ * present — live sessions persist there, and a scan that only knows the
+ * old names silently skips every current session (2026-09-11: auto-resume
+ * found nothing after a restart, so no recovery continue was triggered).
+ */
+export declare function resolveSessionLogPath(dir: string): string | undefined;
 export declare function findInterrupted(dshHome?: string, opts?: FindInterruptedOpts): Promise<ResumeResult>;
 /**
  * Detect sessions whose raw log ends with a `turn/start` that has no

package/lib/resume.js

@@ -1,6 +1,27 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as os from 'node:os';
+/**
+ * Resolve the readable session log inside one session directory across
+ * format generations. `session.v3.jsonl.zstd` is the current successor;
+ * `session.jsonl.zstd` / `session.jsonl` remain for committed older
+ * generations (migrations never move or delete them). Prefer v3 when
+ * present — live sessions persist there, and a scan that only knows the
+ * old names silently skips every current session (2026-09-11: auto-resume
+ * found nothing after a restart, so no recovery continue was triggered).
+ */
+export function resolveSessionLogPath(dir) {
+    const v3 = path.join(dir, 'session.v3.jsonl.zstd');
+    if (fs.existsSync(v3))
+        return v3;
+    const zstd = path.join(dir, 'session.jsonl.zstd');
+    if (fs.existsSync(zstd))
+        return zstd;
+    const jsonl = path.join(dir, 'session.jsonl');
+    if (fs.existsSync(jsonl))
+        return jsonl;
+    return undefined;
+}
 /**
  * Read the last ~100 lines of one session's raw log, applying the mtime
  * pre-filter before any (potentially expensive) zstd decompression: a
@@ -13,27 +34,26 @@ import * as os from 'node:os';
  * @returns `undefined` when the session has no log file, or is filtered
  *   out by `sinceMs` — callers must treat that the same as "nothing found".
  */
-async function readSessionTailLines(zstdPath, jsonlPath, sinceMs) {
+async function readSessionTailLines(logPath, sinceMs) {
+    if (logPath === undefined)
+        return undefined;
     if (sinceMs !== undefined) {
         try {
-            const statPath = fs.existsSync(zstdPath) ? zstdPath : (fs.existsSync(jsonlPath) ? jsonlPath : undefined);
-            if (statPath) {
-                const mtimeMs = fs.statSync(statPath).mtimeMs;
-                if (mtimeMs < sinceMs)
-                    return undefined;
-            }
+            if (fs.statSync(logPath).mtimeMs < sinceMs)
+                return undefined;
         }
         catch { }
     }
-    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 | tail -100`, { encoding: 'utf-8' });
+        const out = execSync(`zstd -d -c ${JSON.stringify(logPath)} 2>/dev/null | tail -100`, { encoding: 'utf-8' });
         return out.split('\n').filter(Boolean);
     }
-    if (fs.existsSync(jsonlPath)) {
-        const content = fs.readFileSync(jsonlPath, 'utf-8');
+    try {
+        const content = fs.readFileSync(logPath, 'utf-8');
         return content.trim().split('\n').slice(-100);
     }
+    catch { }
     return undefined;
 }
 export async function findInterrupted(dshHome, opts) {
@@ -55,10 +75,9 @@ export async function findInterrupted(dshHome, opts) {
                 if (!s.isDirectory())
                     continue;
                 scanned++;
-                const zstdPath = path.join(groupPath, s.name, 'session.jsonl.zstd');
-                const jsonlPath = path.join(groupPath, s.name, 'session.jsonl');
+                const logPath = resolveSessionLogPath(path.join(groupPath, s.name));
                 try {
-                    const lines = await readSessionTailLines(zstdPath, jsonlPath, sinceMs);
+                    const lines = await readSessionTailLines(logPath, sinceMs);
                     if (lines === undefined)
                         continue;
                     let found = false;
@@ -103,31 +122,30 @@ export async function findInterrupted(dshHome, opts) {
  * The mtime pre-filter ensures this full decompression runs only for
  * recent sessions (within 5m, typically 1-2 files), not for all 425.
  */
-async function readSessionAllLines(zstdPath, jsonlPath, sinceMs) {
+async function readSessionAllLines(logPath, sinceMs) {
+    if (logPath === undefined)
+        return undefined;
     if (sinceMs !== undefined) {
         try {
-            const statPath = fs.existsSync(zstdPath) ? zstdPath : (fs.existsSync(jsonlPath) ? jsonlPath : undefined);
-            if (statPath) {
-                const mtimeMs = fs.statSync(statPath).mtimeMs;
-                if (mtimeMs < sinceMs)
-                    return undefined;
-            }
+            if (fs.statSync(logPath).mtimeMs < sinceMs)
+                return undefined;
         }
         catch { }
     }
-    if (fs.existsSync(zstdPath)) {
+    if (logPath.endsWith('.zstd')) {
         const { execSync } = await import('node:child_process');
         // maxBuffer must exceed the decompressed size of any real session log —
         // worker sessions decode to 8-23MB while execSync's default 1MB would
         // throw ENOBUFS and silently drop the session from every scan that needs
         // the full file (findDanglingOpenTurns). Use 64MB to leave headroom.
-        const out = execSync(`zstd -d -c ${JSON.stringify(zstdPath)} 2>/dev/null`, { encoding: 'utf-8', maxBuffer: 64 * 1024 * 1024 });
+        const out = execSync(`zstd -d -c ${JSON.stringify(logPath)} 2>/dev/null`, { encoding: 'utf-8', maxBuffer: 64 * 1024 * 1024 });
         return out.split('\n').filter(Boolean);
     }
-    if (fs.existsSync(jsonlPath)) {
-        const content = fs.readFileSync(jsonlPath, 'utf-8');
+    try {
+        const content = fs.readFileSync(logPath, 'utf-8');
         return content.trim().split('\n').filter(Boolean);
     }
+    catch { }
     return undefined;
 }
 /**
@@ -162,10 +180,9 @@ export async function findDanglingOpenTurns(dshHome, opts) {
                 if (!s.isDirectory())
                     continue;
                 scanned++;
-                const zstdPath = path.join(groupPath, s.name, 'session.jsonl.zstd');
-                const jsonlPath = path.join(groupPath, s.name, 'session.jsonl');
+                const logPath = resolveSessionLogPath(path.join(groupPath, s.name));
                 try {
-                    const lines = await readSessionAllLines(zstdPath, jsonlPath, sinceMs);
+                    const lines = await readSessionAllLines(logPath, sinceMs);
                     if (lines === undefined)
                         continue;
                     let openTurn;

package/lib/snapshot.d.ts

@@ -1,22 +1,59 @@
-interface ManifestEntry {
-    path: string;
-    sha256: string;
-}
-interface Manifest {
+export interface SnapshotResult {
     ts: string;
-    files: ManifestEntry[];
+    /** Files (and symlinks) copied into this snapshot. */
+    files: number;
+    /** Entries that could not be copied; the snapshot stays usable either way. */
+    skipped: Array<{
+        path: string;
+        reason: string;
+    }>;
 }
-export declare function writeLKG(dshHome: string, lkgRoot: string): Promise<{
-    ts: string;
-    manifest: Manifest;
-}>;
+export interface SnapshotDeps {
+    /**
+     * Copy one regular file, preserving `mode`. Injectable so a failing entry
+     * (the EACCES a read-only attachment object produces) can be table-tested
+     * without depending on the host's uid or filesystem quirks.
+     */
+    copyFile?: (src: string, dest: string, mode: number) => void;
+}
+/**
+ * DSH-home entries the last-known-good snapshot deliberately never copies.
+ *
+ * The LKG exists to recover a boot that fails while loading the plugin tree, so
+ * it holds boot **configuration**: `profiles/` (the plugin tree with its
+ * lockfile, `cordis.patch.yml` and sidecars), the per-plugin config directories
+ * and the settings documents. Everything below is runtime **data** — it is
+ * written continuously while `dsh web` runs, so restoring a snapshot of it can
+ * only lose newer state, and some of it is hostile to a bulk copy:
+ *
+ * - `sessions/` — append-only transcripts. Restoring a stale copy over live
+ *   sessions drops every turn recorded after the snapshot, i.e. the recovery
+ *   path would lose the log it is supposed to protect.
+ * - `attachments/` — content-addressed blobs stored mode `0400`. That read-only
+ *   bit is exactly what made the 2026-09-13 rollback abort with
+ *   `EACCES: Permission denied '.../attachments/v1/objects/f8'`.
+ * - `plugins-src/` — plugin source cache, re-fetched on demand (~400 MB host).
+ * - `.supervisor/` — the LKG root itself lives inside the DSH home, so copying
+ *   it would recurse into every retained snapshot.
+ *
+ * This list is data, not a heuristic: the copy loop and the restore loop both
+ * consult `isLkgExcluded()`, and the table test pins the rule.
+ */
+export declare const LKG_EXCLUDED_ENTRIES: readonly string[];
+/**
+ * True when a DSH-home-relative path must never enter (or leave) the LKG.
+ *
+ * The named entries match the first path segment; `*.log` matches by basename
+ * anywhere, because append-only logs are data at any depth and a restored stale
+ * `dsh-web.log` would poison the boot-boundary scan.
+ */
+export declare function isLkgExcluded(relPath: string): boolean;
+/** Human-readable, bounded reason for a per-entry copy failure. */
+export declare function failureReason(e: unknown): string;
+export declare function writeLKG(dshHome: string, lkgRoot: string, deps?: SnapshotDeps): Promise<SnapshotResult>;
 export declare function pruneByAge(root: string, maxAgeMs: number): Promise<void>;
 export declare function pruneBySize(root: string, maxBytes: number): Promise<void>;
 export declare function isDuplicateLKG(dshHome: string, lkgRoot: string): Promise<boolean>;
 export declare function verifyLKG(lkgPath: string): Promise<boolean>;
 export declare function rotateLKG(lkgRoot: string, keep?: number): Promise<void>;
-export declare function writeFailed(dshHome: string, failedRoot: string): Promise<{
-    ts: string;
-    manifest: Manifest;
-}>;
-export {};
+export declare function writeFailed(dshHome: string, failedRoot: string): Promise<SnapshotResult>;

package/lib/snapshot.js

@@ -1,6 +1,51 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as crypto from 'node:crypto';
+/**
+ * DSH-home entries the last-known-good snapshot deliberately never copies.
+ *
+ * The LKG exists to recover a boot that fails while loading the plugin tree, so
+ * it holds boot **configuration**: `profiles/` (the plugin tree with its
+ * lockfile, `cordis.patch.yml` and sidecars), the per-plugin config directories
+ * and the settings documents. Everything below is runtime **data** — it is
+ * written continuously while `dsh web` runs, so restoring a snapshot of it can
+ * only lose newer state, and some of it is hostile to a bulk copy:
+ *
+ * - `sessions/` — append-only transcripts. Restoring a stale copy over live
+ *   sessions drops every turn recorded after the snapshot, i.e. the recovery
+ *   path would lose the log it is supposed to protect.
+ * - `attachments/` — content-addressed blobs stored mode `0400`. That read-only
+ *   bit is exactly what made the 2026-09-13 rollback abort with
+ *   `EACCES: Permission denied '.../attachments/v1/objects/f8'`.
+ * - `plugins-src/` — plugin source cache, re-fetched on demand (~400 MB host).
+ * - `.supervisor/` — the LKG root itself lives inside the DSH home, so copying
+ *   it would recurse into every retained snapshot.
+ *
+ * This list is data, not a heuristic: the copy loop and the restore loop both
+ * consult `isLkgExcluded()`, and the table test pins the rule.
+ */
+export const LKG_EXCLUDED_ENTRIES = [
+    'sessions',
+    'attachments',
+    'plugins-src',
+    '.supervisor',
+];
+/**
+ * True when a DSH-home-relative path must never enter (or leave) the LKG.
+ *
+ * The named entries match the first path segment; `*.log` matches by basename
+ * anywhere, because append-only logs are data at any depth and a restored stale
+ * `dsh-web.log` would poison the boot-boundary scan.
+ */
+export function isLkgExcluded(relPath) {
+    const normalized = relPath.replace(/\\/g, '/').replace(/^\.\//, '').replace(/^\/+/, '');
+    const segments = normalized.split('/').filter(s => s.length > 0 && s !== '.');
+    if (!segments.length)
+        return false;
+    if (LKG_EXCLUDED_ENTRIES.includes(segments[0]))
+        return true;
+    return segments[segments.length - 1].endsWith('.log');
+}
 function sha256File(filePath) {
     const data = fs.readFileSync(filePath);
     return crypto.createHash('sha256').update(data).digest('hex');
@@ -16,7 +61,78 @@ function walkFiles(dir, base = dir) {
     }
     return out;
 }
-export async function writeLKG(dshHome, lkgRoot) {
+/** Human-readable, bounded reason for a per-entry copy failure. */
+export function failureReason(e) {
+    const err = e;
+    const code = typeof err?.code === 'string' && err.code ? `${err.code}: ` : '';
+    const message = typeof err?.message === 'string' ? err.message : String(e);
+    return `${code}${message}`.slice(0, 300);
+}
+/**
+ * Copy one snapshot entry, collecting — never throwing — per-entry failures
+ * (D2). `fs.cpSync` aborts the whole snapshot on the first unreadable object,
+ * which is precisely how one 0400 attachment file stopped the rollback that
+ * exists to rescue a broken boot.
+ */
+function copyEntry(state, src, dest, rel) {
+    if (isLkgExcluded(rel))
+        return;
+    let st;
+    try {
+        st = fs.lstatSync(src);
+    }
+    catch (e) {
+        state.skipped.push({ path: rel, reason: failureReason(e) });
+        return;
+    }
+    if (st.isDirectory()) {
+        let names;
+        try {
+            // Directory modes are replicated only in their permission-to-traverse
+            // sense: the snapshot itself must stay readable/removable even when the
+            // source directory is not (a 0000 source dir must not produce a snapshot
+            // that nothing — including retention — can delete).
+            fs.mkdirSync(dest, { recursive: true, mode: (st.mode & 0o7777) | 0o700 });
+            names = fs.readdirSync(src);
+        }
+        catch (e) {
+            state.skipped.push({ path: rel, reason: failureReason(e) });
+            return;
+        }
+        for (const name of names) {
+            copyEntry(state, path.join(src, name), path.join(dest, name), rel ? `${rel}/${name}` : name);
+        }
+        return;
+    }
+    if (st.isSymbolicLink()) {
+        try {
+            const link = fs.readlinkSync(src);
+            fs.mkdirSync(path.dirname(dest), { recursive: true });
+            try {
+                fs.unlinkSync(dest);
+            }
+            catch { }
+            fs.symlinkSync(link, dest);
+            state.copied++;
+        }
+        catch (e) {
+            state.skipped.push({ path: rel, reason: failureReason(e) });
+        }
+        return;
+    }
+    if (st.isFile()) {
+        try {
+            fs.mkdirSync(path.dirname(dest), { recursive: true });
+            state.copyFile(src, dest, st.mode & 0o7777);
+            state.copied++;
+        }
+        catch (e) {
+            state.skipped.push({ path: rel, reason: failureReason(e) });
+        }
+    }
+    // Sockets/FIFOs/devices are not boot configuration: ignored on purpose.
+}
+export async function writeLKG(dshHome, lkgRoot, deps = {}) {
     // Dedupe: skip snapshot if current state identical to latest LKG (prevents 5-min unconditional growth)
     try {
         if (await isDuplicateLKG(dshHome, lkgRoot)) {
@@ -31,36 +147,68 @@ export async function writeLKG(dshHome, lkgRoot) {
             const latest = entries[entries.length - 1];
             const manifestPath = path.join(lkgRoot, latest, 'manifest.json');
             const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
-            return { ts: latest, manifest };
+            return { ts: latest, files: manifest.files?.length ?? 0, skipped: [] };
         }
     }
     catch { }
     const ts = new Date().toISOString().replace(/[:.]/g, '-');
     const dest = path.join(lkgRoot, ts);
-    fs.mkdirSync(dest, { recursive: true });
-    // Copy DSH home contents (if exists, copy recursively) — skip .supervisor to avoid recursion
-    if (fs.existsSync(dshHome)) {
-        for (const entry of fs.readdirSync(dshHome)) {
-            if (entry === '.supervisor')
-                continue;
-            const src = path.join(dshHome, entry);
-            const dst = path.join(dest, entry);
-            fs.cpSync(src, dst, { recursive: true });
-        }
-    }
-    const files = fs.existsSync(dest) ? walkFiles(dest) : [];
+    try {
+        fs.mkdirSync(dest, { recursive: true });
+    }
+    catch (e) {
+        // No snapshot is better than an exception thrown into the rollback path.
+        return { ts, files: 0, skipped: [{ path: lkgRoot, reason: failureReason(e) }] };
+    }
+    const state = {
+        dshHome,
+        copyFile: deps.copyFile ?? ((src, dst, mode) => {
+            fs.copyFileSync(src, dst);
+            try {
+                fs.chmodSync(dst, mode);
+            }
+            catch { }
+        }),
+        copied: 0,
+        skipped: [],
+    };
+    // Copy only the boot configuration (D1), one entry at a time so a single
+    // unreadable file is recorded and skipped instead of aborting the snapshot (D2).
+    let topLevel = [];
+    try {
+        if (fs.existsSync(dshHome))
+            topLevel = fs.readdirSync(dshHome);
+    }
+    catch (e) {
+        state.skipped.push({ path: '.', reason: failureReason(e) });
+    }
+    for (const entry of topLevel) {
+        copyEntry(state, path.join(dshHome, entry), path.join(dest, entry), entry);
+    }
+    let fileList = [];
+    try {
+        fileList = fs.existsSync(dest) ? walkFiles(dest) : [];
+    }
+    catch (e) {
+        state.skipped.push({ path: 'manifest', reason: failureReason(e) });
+    }
     const manifest = {
         ts,
-        files: files
+        files: fileList
             .filter(f => f !== 'manifest.json')
             .map(f => ({ path: f, sha256: sha256File(path.join(dest, f)) })),
     };
-    fs.writeFileSync(path.join(dest, 'manifest.json'), JSON.stringify(manifest, null, 2));
+    try {
+        fs.writeFileSync(path.join(dest, 'manifest.json'), JSON.stringify(manifest, null, 2));
+    }
+    catch (e) {
+        state.skipped.push({ path: 'manifest.json', reason: failureReason(e) });
+    }
     // Retention: keep only 3 most recent, plus age (7d) and size (5GB) caps — prevents unbounded 40GB+ growth
     await rotateLKG(lkgRoot, 3).catch(() => { });
     await pruneByAge(lkgRoot, 7 * 24 * 60 * 60 * 1000).catch(() => { });
     await pruneBySize(lkgRoot, 5 * 1024 * 1024 * 1024).catch(() => { });
-    return { ts, manifest };
+    return { ts, files: state.copied, skipped: state.skipped };
 }
 export async function pruneByAge(root, maxAgeMs) {
     if (!fs.existsSync(root))
@@ -150,7 +298,9 @@ export async function isDuplicateLKG(dshHome, lkgRoot) {
             let newestFileMtime = 0;
             if (fs.existsSync(dshHome)) {
                 for (const entry of fs.readdirSync(dshHome)) {
-                    if (entry === '.supervisor')
+                    // Same scope as the copy loop: runtime data changes constantly and
+                    // must not defeat the dedupe for the configuration being snapshotted.
+                    if (isLkgExcluded(entry))
                         continue;
                     try {
                         const s = fs.statSync(path.join(dshHome, entry));

package/lib/supervisor.d.ts

@@ -1,16 +1,25 @@
-import type { HealthState } from './health-poller.js';
+import { type HealthState } from './health-poller.js';
 import type { RestartRequest } from './restart-guards.js';
 import { type RestartOutcome } from './intents.js';
 import { type MintCookieOpts } from './dsh-session.js';
+/** Partial-restore report a rollback may hand back (cli.ts wires RestoreResult). */
+export interface RollbackSummary {
+    target?: string;
+    restored?: number;
+    skipped?: Array<{
+        path: string;
+        reason: string;
+    }>;
+}
 export interface SupervisorDeps {
     pollHealth: () => Promise<HealthState>;
     writeLKG: () => Promise<{
         ts: string;
-        manifest: any;
+        manifest?: any;
     }>;
     writeFailed: () => Promise<{
         ts: string;
-        manifest: any;
+        manifest?: any;
     }>;
     writeReport: (opts: {
         ts: string;
@@ -19,12 +28,13 @@ export interface SupervisorDeps {
         logTail?: string;
         gitDiff?: string;
     }) => Promise<string>;
-    rollback: (ts?: string) => Promise<void>;
+    rollback: (ts?: string) => Promise<RollbackSummary | void>;
     restartWeb?: () => Promise<void>;
     notify: (msg: string) => Promise<void>;
     intervalMs?: number;
     debounceMs?: number;
     downThreshold?: number;
+    bootGraceMs?: number;
     getTime?: () => number;
     isPlannedRestartActive?: () => boolean | Promise<boolean>;
     writePlannedRestart?: (ttlMs?: number) => void;
@@ -91,9 +101,16 @@ export declare class Supervisor {
     private getEffectiveDownThreshold;
     private getEffectiveDegradedThreshold;
     private getEffectivePollTimeoutMs;
+    private getEffectiveBootGraceMs;
     private findInterruptedRecent;
     private collectGitDiff;
     private attemptAutoResume;
+    /**
+     * D4: a restore that could not put every entry back must be surfaced loudly.
+     * Without this, a half-restored tree reads exactly like a clean recovery in
+     * the log and in the operator's Telegram feed.
+     */
+    private reportRollbackResult;
     private handleDebugResult;
     tick(): Promise<void>;
     start(): Promise<void>;