@ddtcorex/dsh-maestro-supervisor 0.6.7 → 0.7.0

package/lib/restart-tool.js

@@ -0,0 +1,241 @@
+/**
+ * dsh_web_restart tool — the safe restart path for the model running inside
+ * dsh web. Scheduling a restart through this tool instead of a raw kill keeps
+ * the restart inside the supervisor's ownership loop:
+ *
+ *   1. dry-boot gate — if the plugin tree changed since the latest LKG, boot a
+ *      copy of the live profile on an ephemeral DSH_HOME first and only
+ *      schedule when that boot serves HTTP.
+ *   2. intent sidecar — record the caller session + reason under
+ *      ~/.dsh/.supervisor/intents/ for attribution.
+ *   3. hand-off — write the restart-request marker (planned-restart.json with
+ *      callerSessionId) that the supervisor daemon owns and acts on
+ *      (out-of-band). This tool NEVER restarts the host in-tree.
+ */
+import { join } from 'node:path';
+import { mkdtempSync, rmSync, cpSync, existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { tmpdir, homedir } from 'node:os';
+import { spawn } from 'node:child_process';
+import { createRequire } from 'node:module';
+import { writeRestartRequest } from './restart-guards.js';
+/**
+ * Boot a copy of the live web profile on an isolated DSH_HOME and verify the
+ * plugin tree loads and serves. Returns ok + a one-line detail for the tool
+ * message. The spawned tree is killed (best-effort) and the temp home removed.
+ * Unit tests mock this (never spawn a real node boot in tests).
+ *
+ * NOTE (bin.ts finding): the `web` alias already implies `--profile web`, and
+ * the web app's own commander program (no allowUnknownOption) rejects a stray
+ * `--profile` in its inner args — so the spawn passes only `web --no-open
+ * --port <port>`.
+ */
+export async function dryBootVerify(harnessRoot, opts = {}) {
+    const timeoutMs = opts.timeoutMs ?? 60_000;
+    const home = homedir();
+    const liveProfile = join(home, '.dsh', 'profiles', 'web');
+    if (!existsSync(liveProfile))
+        return { ok: true, detail: 'skipped (no live web profile)' };
+    const tmpHome = mkdtempSync(join(tmpdir(), 'dsh-dryboot-'));
+    const logs = [];
+    let child = null;
+    try {
+        cpSync(liveProfile, join(tmpHome, 'profiles', 'web'), { recursive: true, preserveTimestamps: true });
+        const port = String(9000 + Math.floor(Math.random() * 1000));
+        const url = `http://127.0.0.1:${port}/`;
+        child = spawn('node', ['--import', 'tsx/esm', 'apps/cli/src/bin.ts', 'web', '--no-open', '--port', port], {
+            cwd: harnessRoot, env: { ...process.env, DSH_HOME: tmpHome }, stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        child.stdout?.on('data', (d) => logs.push(d.toString()));
+        child.stderr?.on('data', (d) => logs.push(d.toString()));
+        const deadline = Date.now() + timeoutMs;
+        let code = -1;
+        while (Date.now() < deadline) {
+            if (child.exitCode !== null) {
+                code = child.exitCode;
+                break;
+            }
+            try {
+                const r = await fetch(url);
+                if (r.status === 200 || r.status === 401) {
+                    code = 0;
+                    break;
+                }
+            }
+            catch { }
+            await new Promise(r => setTimeout(r, 500));
+        }
+        const tail = logs.join('').slice(-3000);
+        const loadErr = /ERR_MODULE_NOT_FOUND|assertChannel|must declare output|failed to apply loader entry/.exec(tail);
+        return { ok: code === 0 && !loadErr, detail: loadErr ? loadErr[0] : (code === 0 ? 'dry-boot ok' : `dry-boot failed (exit ${code})`) };
+    }
+    catch (e) {
+        return { ok: false, detail: `dry-boot error: ${e?.message ?? String(e)}` };
+    }
+    finally {
+        // Kill on every exit path — a successful boot included. The dry boot only
+        // exists to verify the tree; leaving the child up would orphan a dsh web
+        // on the ephemeral port whose temp DSH_HOME is removed below, and a stale
+        // orphan could later answer a port collision with a false-positive 200.
+        try {
+            child?.kill('SIGKILL');
+        }
+        catch { }
+        try {
+            rmSync(tmpHome, { recursive: true, force: true });
+        }
+        catch { }
+    }
+}
+/**
+ * Whether the live plugin tree differs from the latest LKG snapshot. Two
+ * signals are combined:
+ *
+ *   1. manifest drift — the live profile's web `package.json` text vs baseline;
+ *   2. plugin-lib drift — any `@ddtcorex` plugin `lib/` file newer than the
+ *      snapshot moment. Link-installed plugins resolve to the same workspace
+ *      files in both live and LKG, so the stored copies cannot be compared
+ *      byte-wise; the snapshot itself is the meaningful baseline and a rebuilt
+ *      `lib/` bumps a file past it even when the manifest text is unchanged.
+ *      writeLKG writes `manifest.json` LAST, so its FILE mtime is the
+ *      authoritative snapshot moment; the snapshot dir mtime is only a
+ *      fallback for legacy snapshots without a manifest.
+ *
+ * `statFile` (default `statSync`) reads the metadata so tests can inject a
+ * controlled reader instead of relying on filesystem utimes (which CI runners
+ * do not reliably reflect). No LKG baseline, a missing file on either side, or
+ * any stat/read error means "changed" — the caller falls back to the dry-boot
+ * gate.
+ */
+export function isPluginTreeChanged(harnessRoot, lkgDir = join(homedir(), '.dsh/.supervisor/lkg'), opts = {}) {
+    void harnessRoot;
+    const statFile = opts.statFile ?? ((p) => statSync(p));
+    try {
+        const entries = existsSync(lkgDir) ? readdirSync(lkgDir).sort() : [];
+        const latest = entries[entries.length - 1];
+        if (!latest)
+            return true; // no baseline → assume changed
+        const lkgHome = join(lkgDir, latest, 'profiles', 'web');
+        const live = join(homedir(), '.dsh', 'profiles', 'web');
+        const lkgManifest = join(lkgHome, 'package.json');
+        const liveManifest = join(live, 'package.json');
+        if (!existsSync(lkgManifest) || !existsSync(liveManifest))
+            return true;
+        if (readFileSync(liveManifest, 'utf8') !== readFileSync(lkgManifest, 'utf8'))
+            return true;
+        const snapshotManifest = join(lkgDir, latest, 'manifest.json');
+        const baseline = existsSync(snapshotManifest)
+            ? statFile(snapshotManifest).mtimeMs
+            : statFile(join(lkgDir, latest)).mtimeMs;
+        const livePlugins = join(live, 'node_modules', '@ddtcorex');
+        if (existsSync(livePlugins)) {
+            for (const name of readdirSync(livePlugins)) {
+                const libDir = join(livePlugins, name, 'lib');
+                if (!existsSync(libDir))
+                    continue;
+                if (newestFileMtime(libDir, statFile) > baseline)
+                    return true;
+            }
+        }
+        return false;
+    }
+    catch {
+        return true;
+    }
+}
+/** Newest mtime under a directory; recursion threads the injected stat reader. */
+function newestFileMtime(dir, statFile) {
+    let newest = 0;
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        const p = join(dir, entry.name);
+        if (entry.isDirectory())
+            newest = Math.max(newest, newestFileMtime(p, statFile));
+        else
+            newest = Math.max(newest, statFile(p).mtimeMs);
+    }
+    return newest;
+}
+function currentSessionId(exec, fallback) {
+    // dsh-tools dispatch hands a ToolRunContext — the exec itself has no
+    // sessionId/session/caller fields; session identity lives on the agent
+    // (exec.agent.id is the branded SessionId, exec.agent.session.id also
+    // exists). Probe those first so production dispatches are identifiable.
+    return exec?.agent?.id ?? exec?.agent?.session?.id ?? exec?.sessionId ?? exec?.session?.id ?? exec?.caller?.sessionId ?? fallback?.(exec);
+}
+/**
+ * Register the dsh_web_restart tool. Registration is fail-safe (warns, never
+ * throws) and the returned function disposes the registration. `deps` are
+ * injectable for tests.
+ */
+export function registerRestartTool(ctx, deps = {}) {
+    const doDryBoot = deps.dryBoot ?? dryBootVerify;
+    const doWrite = deps.writeRestartRequest ?? writeRestartRequest;
+    const doSessionId = deps.sessionIdOf ?? currentSessionId;
+    let dispose;
+    try {
+        dispose = ctx.tools.register({
+            name: 'dsh_web_restart',
+            description: 'Schedule a safe restart of the dsh web host. Verifies the plugin tree first (dry-boot), records an intent for the calling session, and hands the restart to the supervisor daemon (out-of-band). Never restarts in-tree itself.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    reason: { type: 'string', description: 'Why the restart is happening (recorded in the intent)' },
+                    pluginChanged: { type: 'boolean', description: 'Override for the auto-detected plugin-tree change check' },
+                },
+                additionalProperties: false,
+            },
+            output: {
+                schema: { type: 'object', additionalProperties: true, properties: { ok: { type: 'boolean' }, detail: { type: 'string' } } },
+                render: (_args, value) => [{ type: 'text', text: value.detail }],
+            },
+            execute: async (args, exec) => {
+                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));
+                if (changed) {
+                    const gate = await doDryBoot(harnessRoot);
+                    if (!gate.ok)
+                        return { ok: false, detail: `dry-boot failed — restart refused. ${gate.detail}` };
+                }
+                const callerSessionId = doSessionId(exec);
+                if (!callerSessionId) {
+                    // The daemon's grace branch keys on callerSessionId — without it the
+                    // marker would be written but no restart would ever be supervised.
+                    return { ok: false, detail: 'cannot identify the calling session — restart not scheduled' };
+                }
+                doWrite({ callerSessionId, reason: typeof args.reason === 'string' ? args.reason : undefined }, 180_000);
+                writeIntentSidecar(callerSessionId, args.reason);
+                return { ok: true, detail: `restart scheduled (≈30s) — caller ${callerSessionId}` };
+            },
+        });
+    }
+    catch (e) {
+        try {
+            ctx.logger?.warn?.(`[supervisor] dsh_web_restart tool failed: ${e?.message ?? String(e)}`);
+        }
+        catch { }
+    }
+    return () => { try {
+        if (typeof dispose === 'function')
+            dispose();
+    }
+    catch { } };
+}
+function writeIntentSidecar(sessionId, reason) {
+    try {
+        if (!sessionId)
+            return;
+        const dir = join(homedir(), '.dsh/.supervisor/intents');
+        const require = createRequire(import.meta.url);
+        const { mkdirSync, writeFileSync, chmodSync } = require('node:fs');
+        mkdirSync(dir, { recursive: true });
+        // Flatten slash-namespaced ids ('proj/abc' → 'proj_abc') so the sidecar is
+        // a single file under intents/ and never needs a nested intents/proj/ dir.
+        const safeId = sessionId.replace(/[^A-Za-z0-9._-]/g, '_');
+        writeFileSync(join(dir, `${safeId}.json`), JSON.stringify({ ts: Date.now(), sessionId, reason: reason ?? '' }), 'utf8');
+        try {
+            chmodSync(join(dir, `${safeId}.json`), 0o600);
+        }
+        catch { }
+    }
+    catch { }
+}

package/lib/scan.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Post-restart session scan: walk recent session logs under
+ * <dshHome>/sessions/<project>/<session>/ and flag torn tails (a zstd frame
+ * that fails to decode, or a plain-text log that is unreadable). Runs after
+ * an intentional dsh-web restart so the supervisor can report whether any
+ * in-flight session log was left truncated by the restart.
+ */
+interface ScanOptions {
+    withinMs?: number;
+}
+/**
+ * Scan session logs whose mtime falls within the window. A file whose decode
+ * fails (torn zstd frame or unreadable plain text) is reported as torn. A
+ * missing sessions root yields an empty scan, never an error.
+ */
+export declare function scanSessions(dshHome: string, opts?: ScanOptions): Promise<{
+    scanned: number;
+    torn: string[];
+}>;
+export {};

package/lib/scan.js

@@ -0,0 +1,71 @@
+/**
+ * Post-restart session scan: walk recent session logs under
+ * <dshHome>/sessions/<project>/<session>/ and flag torn tails (a zstd frame
+ * that fails to decode, or a plain-text log that is unreadable). Runs after
+ * an intentional dsh-web restart so the supervisor can report whether any
+ * in-flight session log was left truncated by the restart.
+ */
+import { readdirSync, statSync } from 'node:fs';
+import { join, extname, basename } from 'node:path';
+import { execFileSync } from 'node:child_process';
+async function decodeOk(file) {
+    try {
+        if (extname(file) === '.zstd') {
+            execFileSync('zstd', ['-d', '-c', file], { encoding: 'utf8', maxBuffer: 64 * 1024 * 1024, timeout: 30_000 });
+        }
+        else {
+            const { readFileSync } = await import('node:fs');
+            readFileSync(file, 'utf8');
+        }
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Scan session logs whose mtime falls within the window. A file whose decode
+ * fails (torn zstd frame or unreadable plain text) is reported as torn. A
+ * missing sessions root yields an empty scan, never an error.
+ */
+export async function scanSessions(dshHome, opts = {}) {
+    const sessionsRoot = join(dshHome, 'sessions');
+    const now = Date.now();
+    const withinMs = opts.withinMs ?? 10 * 60 * 1000;
+    const files = [];
+    try {
+        for (const proj of readdirSync(sessionsRoot)) {
+            const projDir = join(sessionsRoot, proj);
+            if (!statSync(projDir).isDirectory())
+                continue;
+            for (const sess of readdirSync(projDir)) {
+                const sessDir = join(projDir, sess);
+                if (!statSync(sessDir).isDirectory())
+                    continue;
+                for (const f of readdirSync(sessDir)) {
+                    const name = basename(f);
+                    if (!name.endsWith('.zstd') && !name.endsWith('.jsonl'))
+                        continue;
+                    const fp = join(sessDir, f);
+                    let mtime = 0;
+                    try {
+                        mtime = statSync(fp).mtimeMs;
+                    }
+                    catch {
+                        continue;
+                    }
+                    if (now - mtime > withinMs)
+                        continue;
+                    files.push(fp);
+                }
+            }
+        }
+    }
+    catch { /* sessions root absent */ }
+    const torn = [];
+    for (const f of files) {
+        if (!(await decodeOk(f)))
+            torn.push(f);
+    }
+    return { scanned: files.length, torn };
+}

package/lib/self-kill-guard.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Self-kill guard for `tools/pre-execute`: deny bash/shell commands that would
+ * kill or restart the very dsh web process the agent is running inside. The
+ * model must route restarts through the supervisor's dsh_web_restart tool, not
+ * by killing the host.
+ */
+/**
+ * Whether a shell command is a self-kill. `livePids` are the pids currently
+ * holding listening sockets; a `kill <pid>` whose pid is one of ours is a
+ * self-kill regardless of anything else in the command. The kill parser accepts
+ * flag forms (`kill -9 <pid>`, `kill -TERM <pid>`). A command that is
+ * essentially JUST a `kill <unrelated-pid>` is allowed (idempotent cleanups
+ * are common), as are kill attempts whose output reports "not found"/"done" —
+ * but any compound that chains a restart/kill after it (or before the end)
+ * stays denied.
+ */
+export declare function isSelfKillCommand(cmd: string, livePids: number[]): boolean;
+/**
+ * Build a `tools/pre-execute` waterfall listener: deny matching
+ * bash/shell/exec commands, otherwise delegate to `next()`. Live pids default
+ * to the pids holding listening sockets (`ss -tlnp`) so `kill <pid>` of a
+ * live host process is caught even when the command names no tool.
+ */
+export declare function makePreExecuteGuard(opts?: {
+    livePids?: () => number[];
+}): (exec: any, next: () => Promise<any>) => Promise<any>;

package/lib/self-kill-guard.js

@@ -0,0 +1,63 @@
+/**
+ * Self-kill guard for `tools/pre-execute`: deny bash/shell commands that would
+ * kill or restart the very dsh web process the agent is running inside. The
+ * model must route restarts through the supervisor's dsh_web_restart tool, not
+ * by killing the host.
+ */
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+// Patterns that restart/stop/start or kill dsh web (systemctl --user units,
+// pkill/killall over the dsh tree, killing holders of :3080, and the
+// dsh-safe-web-update helper itself). The bare `kill\s+` alternative is
+// narrowed below so a kill of an unrelated pid is not denied as a self-kill.
+const SELF_KILL_RE = /(systemctl\s+--?user\s+.*(restart|stop|start).*dsh-web|pkill\s+.*dsh|killall\s+.*dsh|ss\s+.*3080.*kill|restart-dsh-web|kill\s+)/i;
+/**
+ * Whether a shell command is a self-kill. `livePids` are the pids currently
+ * holding listening sockets; a `kill <pid>` whose pid is one of ours is a
+ * self-kill regardless of anything else in the command. The kill parser accepts
+ * flag forms (`kill -9 <pid>`, `kill -TERM <pid>`). A command that is
+ * essentially JUST a `kill <unrelated-pid>` is allowed (idempotent cleanups
+ * are common), as are kill attempts whose output reports "not found"/"done" —
+ * but any compound that chains a restart/kill after it (or before the end)
+ * stays denied.
+ */
+export function isSelfKillCommand(cmd, livePids) {
+    if (/kill\s+(?:-\S+\s+)?(\d+)/i.test(cmd)) {
+        const pid = Number(cmd.match(/kill\s+(?:-\S+\s+)?(\d+)/i)?.[1]);
+        if (livePids.includes(pid))
+            return true;
+    }
+    return SELF_KILL_RE.test(cmd)
+        // Exclude only a command that is JUST `kill [flags] <unrelated pid>` —
+        // anchored end-to-end so `kill 1234 && systemctl restart dsh-web` cannot
+        // whitelist the compound through its prefix.
+        && !/^kill\s+(?:-\S+\s+)?\d+\s*$/i.test(cmd.trim())
+        && !/kill\s+(?:-\S+\s+)?(\d+)\s+.*(not found|done)/i.test(cmd);
+}
+/**
+ * Build a `tools/pre-execute` waterfall listener: deny matching
+ * bash/shell/exec commands, otherwise delegate to `next()`. Live pids default
+ * to the pids holding listening sockets (`ss -tlnp`) so `kill <pid>` of a
+ * live host process is caught even when the command names no tool.
+ */
+export function makePreExecuteGuard(opts = {}) {
+    const livePids = opts.livePids ?? (() => {
+        try {
+            const { execSync } = require('node:child_process');
+            const out = execSync(`ss -tlnp 2>/dev/null | grep -oP 'pid=\\K[0-9]+' | sort -u`, { encoding: 'utf8' });
+            return out.trim().split('\n').filter(Boolean).map(Number);
+        }
+        catch {
+            return [];
+        }
+    });
+    return async (exec, next) => {
+        // dsh-tools hands the frozen ToolExecution (name + arguments); the guard
+        // also accepts the `args` shape for tests/embedded hosts.
+        const cmd = String(exec?.args?.command ?? exec?.args?.input ?? exec?.arguments?.command ?? exec?.arguments?.input ?? '');
+        if ((exec?.name === 'bash' || exec?.name === 'shell' || exec?.name === 'exec') && isSelfKillCommand(cmd, livePids())) {
+            return { kind: 'deny', reason: 'DENIED — this command restarts the dsh web process you are running inside. Use the dsh_web_restart tool (supervisor) for a safe restart.' };
+        }
+        return next();
+    };
+}

package/lib/skill-provider.d.ts

@@ -0,0 +1,6 @@
+import type { SkillCandidate, SkillDefinition, SkillLookupOptions } from '@deepseek-ai/dsh-skill';
+export declare function makeSkillProvider(skillsDir: string): {
+    name: string;
+    list(_options: SkillLookupOptions): Promise<SkillCandidate[]>;
+    get(candidate: SkillCandidate, _options: SkillLookupOptions): Promise<SkillDefinition | undefined>;
+};

package/lib/skill-provider.js

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

package/lib/supervisor.d.ts

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

package/lib/supervisor.js

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

package/package.json

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