@ddtcorex/dsh-maestro-supervisor 0.6.8 → 0.7.0

package/lib/cli.d.ts

@@ -1 +1,14 @@
+/**
+ * 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.
+ */
+export declare function rollbackLKG(opts: {
+    dshHome: string;
+    lkgRoot: string;
+    failingPlugin?: string;
+}): Promise<string>;
 export declare function runCli(args: string[]): Promise<void>;

package/lib/cli.js

@@ -5,7 +5,76 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as os from 'node:os';
 import { resolveHarnessRoot, resolveDeepseekHarnessDir } from './paths.js';
-import { buildKillStalePortsCommand, isSelfCopyError, checkPlannedRestart, writePlannedRestart } from './restart-guards.js';
+import { buildKillStalePortsCommand, isSelfCopyError, checkPlannedRestart, writePlannedRestart, readRestartRequest, clearPlannedRestart } from './restart-guards.js';
+/**
+ * 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.
+ */
+export async function rollbackLKG(opts) {
+    const { dshHome, lkgRoot, failingPlugin } = opts;
+    const entries = fs.existsSync(lkgRoot) ? fs.readdirSync(lkgRoot).sort() : [];
+    if (!entries.length)
+        throw new Error('no LKG to rollback to');
+    const candidates = [...entries].reverse().slice(0, 3);
+    let chosen;
+    for (const cand of candidates) {
+        if (!failingPlugin) {
+            chosen = cand;
+            break;
+        }
+        try {
+            const pkgPath = path.join(lkgRoot, cand, 'profiles/web/package.json');
+            if (!fs.existsSync(pkgPath)) {
+                chosen = cand;
+                break;
+            }
+            const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+            const bundles = pkg?.dsh?.profile?.bundles ?? [];
+            const deps = pkg?.dependencies ?? {};
+            const hasFailing = bundles.some((b) => b.includes(failingPlugin)) || Object.keys(deps).some(k => k.includes(failingPlugin));
+            if (!hasFailing) {
+                chosen = cand;
+                break;
+            }
+            console.log(`[supervisor] skipping LKG ${cand} still contains failing plugin ${failingPlugin}`);
+        }
+        catch {
+            chosen = cand;
+            break;
+        }
+    }
+    const target = chosen ?? entries[entries.length - 1];
+    const src = path.join(lkgRoot, target);
+    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/');
+            continue;
+        }
+        const srcPath = path.join(src, entry);
+        const destPath = path.join(dshHome, entry);
+        try {
+            // Skip if src and dest are the same file (e.g. symlink to same target like ~/.dsh/AGENTS.md)
+            try {
+                if (fs.existsSync(srcPath) && fs.existsSync(destPath) && fs.realpathSync(srcPath) === fs.realpathSync(destPath))
+                    continue;
+            }
+            catch { }
+            fs.cpSync(srcPath, destPath, { recursive: true, force: true });
+        }
+        catch (e) {
+            if (isSelfCopyError(String(e?.message ?? '')))
+                continue;
+            throw e;
+        }
+    }
+    return target;
+}
 export async function runCli(args) {
     const cmd = args[2] ?? '--help';
     if (cmd === '--help' || cmd === '-h' || cmd === 'help') {
@@ -108,10 +177,6 @@ Commands:
             },
             rollback: async () => {
                 const { execSync } = await import('node:child_process');
-                const entries = fs.existsSync(lkgRoot) ? fs.readdirSync(lkgRoot).sort() : [];
-                if (!entries.length)
-                    throw new Error('no LKG to rollback to');
-                // Try newest to oldest (up to 3) to find a clean LKG for plugin failures
                 // Extract failing plugin from current log tail if possible
                 let failingPlugin;
                 try {
@@ -121,56 +186,7 @@ Commands:
                         failingPlugin = m[0].replace(/^@ddtcorex\//, '');
                 }
                 catch { }
-                const candidates = [...entries].reverse().slice(0, 3);
-                let chosen;
-                for (const cand of candidates) {
-                    if (!failingPlugin) {
-                        chosen = cand;
-                        break;
-                    }
-                    try {
-                        const pkgPath = path.join(lkgRoot, cand, 'profiles/web/package.json');
-                        if (!fs.existsSync(pkgPath)) {
-                            chosen = cand;
-                            break;
-                        }
-                        const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
-                        const bundles = pkg?.dsh?.profile?.bundles ?? [];
-                        const deps = pkg?.dependencies ?? {};
-                        const hasFailing = bundles.some((b) => b.includes(failingPlugin)) || Object.keys(deps).some(k => k.includes(failingPlugin));
-                        if (!hasFailing) {
-                            chosen = cand;
-                            break;
-                        }
-                        console.log(`[supervisor] skipping LKG ${cand} still contains failing plugin ${failingPlugin}`);
-                    }
-                    catch {
-                        chosen = cand;
-                        break;
-                    }
-                }
-                const target = chosen ?? entries[entries.length - 1];
-                const src = path.join(lkgRoot, target);
-                for (const entry of fs.readdirSync(src)) {
-                    if (entry === 'manifest.json')
-                        continue;
-                    const srcPath = path.join(src, entry);
-                    const destPath = path.join(dshHome, entry);
-                    try {
-                        // Skip if src and dest are the same file (e.g. symlink to same target like ~/.dsh/AGENTS.md)
-                        try {
-                            if (fs.existsSync(srcPath) && fs.existsSync(destPath) && fs.realpathSync(srcPath) === fs.realpathSync(destPath))
-                                continue;
-                        }
-                        catch { }
-                        fs.cpSync(srcPath, destPath, { recursive: true, force: true });
-                    }
-                    catch (e) {
-                        if (isSelfCopyError(String(e?.message ?? '')))
-                            continue;
-                        throw e;
-                    }
-                }
+                const target = await rollbackLKG({ dshHome, lkgRoot, failingPlugin });
                 console.log(`[supervisor] rolled back to ${target}${failingPlugin ? ` (avoiding ${failingPlugin})` : ''}`);
                 // Reconcile node_modules from restored package.json (critical for link: deps)
                 try {
@@ -229,6 +245,22 @@ Commands:
             },
             notify: async (msg) => console.log(`[notify] ${msg}`),
             isPlannedRestartActive: () => checkPlannedRestart(),
+            // dsh_web_restart marker ownership: the daemon acts on the marker. After
+            // the restart, scan recent session logs for torn tails (an in-flight
+            // session truncated by the restart) and report; the marker is cleared in
+            // the supervisor's own finally block and again here as a safety net.
+            readRestartRequest: () => readRestartRequest(),
+            onRestartRequestHandled: async () => {
+                const { scanSessions } = await import('./scan.js');
+                const res = await scanSessions(path.join(os.homedir(), '.dsh'), { withinMs: 10 * 60 * 1000 }).catch(() => ({ scanned: 0, torn: [] }));
+                if (res.torn.length) {
+                    console.log(`[supervisor] post-self-restart scan: ${res.torn.length} torn session log(s)`);
+                }
+                else {
+                    console.log('[supervisor] post-self-restart scan: clean');
+                }
+                void clearPlannedRestart();
+            },
         });
         await supervisor.start();
         // keep process alive

package/lib/plugin.d.ts

@@ -6,7 +6,7 @@
  * and web restart; this plugin handles the in-process resume.
  */
 import { findInterrupted as defaultFindInterrupted, findDanglingOpenTurns as defaultFindDanglingOpenTurns } from './resume.js';
-export declare const inject: readonly ["sessions", "agents", "connection"];
+export declare const inject: readonly ["sessions", "agents", "connection", "skills"];
 export interface SupervisorPluginConfig {
     autoResumeWithin?: number | string;
     autoResumeEnabled?: boolean;

package/lib/plugin.js

@@ -8,8 +8,13 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as os from 'node:os';
+import { fileURLToPath } from 'node:url';
 import { findInterrupted as defaultFindInterrupted, findDanglingOpenTurns as defaultFindDanglingOpenTurns } from './resume.js';
-export const inject = ['sessions', 'agents', 'connection'];
+import { makeSkillProvider } from './skill-provider.js';
+import { registerRestartTool } from './restart-tool.js';
+import { makePreExecuteGuard } from './self-kill-guard.js';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+export const inject = ['sessions', 'agents', 'connection', 'skills'];
 function parseDuration(s) {
     if (!s)
         return undefined;
@@ -280,6 +285,25 @@ export function createResumeRpcHandler(ctx, opts = {}) {
         return { ok: true, value: { resumed: await resume(ctx, ids) } };
     };
 }
+/** Resolve the package-root skills/ dir regardless of module layout. The built
+ * host lib is flat (lib/plugin.js → ../skills), but under vitest the same
+ * module loads from src/host/ (→ ../../skills). Walking to the nearest
+ * package.json yields the same package-root skills/ in both layouts. */
+function resolveSkillsDir(fromDir) {
+    let dir = fromDir;
+    for (let i = 0; i < 6; i++) {
+        try {
+            if (fs.existsSync(path.join(dir, 'package.json')))
+                return path.join(dir, 'skills');
+        }
+        catch { }
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return path.join(fromDir, '..', 'skills');
+}
 function ensureSystemdKeepalive(ctx) {
     // Best-effort: ensure dsh-web-keepalive.service exists and is enabled, and linger is on.
     // This is the user-level auto-fix for the 11:42:58 crash where manager session 97
@@ -365,6 +389,36 @@ export function apply(ctx, config = {}) {
             ensureSystemdKeepalive(ctx);
         }
         catch { }
+        try {
+            const skills = ctx.get?.('skills');
+            if (skills?.registerProvider) {
+                ctx.effect(() => {
+                    let unregister;
+                    try {
+                        // Package-root skills/ is resolved at runtime by walking to the
+                        // nearest package.json (robust to lib/ vs src/host/ layouts).
+                        unregister = skills.registerProvider(() => makeSkillProvider(resolveSkillsDir(__dirname)));
+                    }
+                    catch (e) {
+                        ctx.logger?.warn?.(`[supervisor] skill provider failed: ${e?.message ?? String(e)}`);
+                    }
+                    return () => { try {
+                        unregister?.();
+                    }
+                    catch { } };
+                }, 'supervisor:skill');
+            }
+        }
+        catch { }
+        try {
+            ctx.effect(() => registerRestartTool(ctx), 'supervisor:restart-tool');
+        }
+        catch (e) {
+            try {
+                ctx.logger?.warn?.(`[supervisor] restart tool effect failed: ${e?.message ?? String(e)}`);
+            }
+            catch { }
+        }
         ctx.effect(() => {
             let disposed = false;
             let timer = null;
@@ -400,6 +454,24 @@ export function apply(ctx, config = {}) {
                 }
             };
         }, 'supervisor:auto-resume');
+        try {
+            // Deny bash/shell self-kill commands in-tree; the safe restart path is
+            // dsh_web_restart (supervisor daemon owns the actual restart).
+            const guard = makePreExecuteGuard();
+            ctx.effect(() => {
+                const un = ctx.on?.('tools/pre-execute', guard) ?? null;
+                return () => { try {
+                    un?.();
+                }
+                catch { } };
+            }, 'supervisor:self-kill-guard');
+        }
+        catch (e) {
+            try {
+                ctx.logger?.warn?.(`[supervisor] self-kill guard effect failed: ${e?.message ?? String(e)}`);
+            }
+            catch { }
+        }
     }
     catch (e) {
         try {

package/lib/restart-guards.d.ts

@@ -6,3 +6,14 @@ export declare function plannedRestartPath(): string;
 export declare function writePlannedRestart(ttlMs?: number): void;
 export declare function checkPlannedRestart(markerPath?: string): boolean;
 export declare function clearPlannedRestart(): void;
+export interface RestartRequest {
+    ts: number;
+    ttl: number;
+    callerSessionId?: string;
+    reason?: string;
+}
+export declare function writeRestartRequest(caller: {
+    callerSessionId?: string;
+    reason?: string;
+}, ttlMs?: number): void;
+export declare function readRestartRequest(): RestartRequest | undefined;

package/lib/restart-guards.js

@@ -92,3 +92,26 @@ export function clearPlannedRestart() {
     }
     catch { }
 }
+export function writeRestartRequest(caller, ttlMs = 180_000) {
+    const p = plannedRestartPath();
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    const body = { ts: Date.now(), ttl: ttlMs, ...caller };
+    fs.writeFileSync(p, JSON.stringify(body), { mode: 0o600 });
+    try {
+        fs.chmodSync(p, 0o600);
+    }
+    catch { }
+}
+export function readRestartRequest() {
+    try {
+        const raw = fs.readFileSync(plannedRestartPath(), 'utf8');
+        const j = JSON.parse(raw);
+        if (typeof j.ts === 'number' && typeof j.ttl === 'number') {
+            if (Date.now() - j.ts >= j.ttl)
+                return undefined;
+            return { ts: j.ts, ttl: j.ttl, callerSessionId: j.callerSessionId, reason: j.reason };
+        }
+    }
+    catch { }
+    return undefined;
+}

package/lib/restart-tool.d.ts

@@ -0,0 +1,70 @@
+/**
+ * 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 { 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 declare function dryBootVerify(harnessRoot: string, opts?: {
+    timeoutMs?: number;
+}): Promise<{
+    ok: boolean;
+    detail: string;
+}>;
+/** Minimal file metadata the drift check reads; injectable for deterministic tests. */
+export interface FileStat {
+    mtimeMs: number;
+}
+/**
+ * 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 declare function isPluginTreeChanged(harnessRoot: string, lkgDir?: string, opts?: {
+    statFile?: (p: string) => FileStat;
+}): boolean;
+/**
+ * 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 declare function registerRestartTool(ctx: any, deps?: {
+    sessionIdOf?: (exec: any) => string | undefined;
+    dryBoot?: typeof dryBootVerify;
+    writeRestartRequest?: typeof writeRestartRequest;
+    harnessRoot?: string;
+}): () => void;

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 {};