@ddtcorex/dsh-maestro-supervisor 0.6.8 → 0.7.1

package/lib/restart-tool.js

@@ -0,0 +1,277 @@
+/**
+ * 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);
+        if (code === 0 && !loadErr)
+            return { ok: true, detail: 'dry-boot ok' };
+        return { ok: false, detail: dryBootFailureDetail(tail, 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 { }
+    }
+}
+/**
+ * Classify a failed dry-boot's log tail into a precise one-line detail. The
+ * most common operator-actionable failure is an EADDRINUSE — the candidate
+ * collided with the live dsh web tree on :3000/:3080 or with another process
+ * on the ephemeral 9000-9999 port — so name the colliding port instead of
+ * reporting a generic boot failure. Plugin-tree load errors keep their stable
+ * codes (the caller's refused message reads `dry-boot failed — restart
+ * refused. <detail>`).
+ */
+export function dryBootFailureDetail(tail, exitCode) {
+    const addrInUse = /EADDRINUSE[^]*?:(\d+)/.exec(tail);
+    if (addrInUse) {
+        const port = addrInUse[1];
+        return `dry-boot failed: port ${port} already in use (EADDRINUSE) — the live dsh web tree or another process holds it`;
+    }
+    const loadErr = /ERR_MODULE_NOT_FOUND|assertChannel|must declare output|failed to apply loader entry/.exec(tail);
+    if (loadErr)
+        return `dry-boot failed: ${loadErr[0]}`;
+    return `dry-boot failed (exit ${exitCode})`;
+}
+/**
+ * Whether the live plugin tree differs from the latest LKG snapshot. Three
+ * signals are combined:
+ *
+ *   1. manifest drift — the live profile's web `package.json` text vs baseline;
+ *   2. cordis patch drift — the live profile's web `cordis.patch.yml` text vs
+ *      baseline (a patch-only config edit changes the boot-time row wiring
+ *      without touching the manifest — the manifest check alone misses it);
+ *   3. 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;
+        // cordis.patch.yml — compare only when at least one side has it (profiles
+        // without a patch are the baseline; a patch appearing on either side alone
+        // is drift). The text compare keeps the check cheap and hermetic.
+        const lkgPatch = join(lkgHome, 'cordis.patch.yml');
+        const livePatch = join(live, 'cordis.patch.yml');
+        if (existsSync(lkgPatch) || existsSync(livePatch)) {
+            if (!existsSync(lkgPatch) || !existsSync(livePatch))
+                return true;
+            if (readFileSync(livePatch, 'utf8') !== readFileSync(lkgPatch, '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,74 @@
+/**
+ * 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.
+ */
+/**
+ * The dsh web MainThread owns both ports (3000 = gitlab-webhook, 3080 = web).
+ * Only listeners on these ports can be dsh web; every other listening process
+ * on the host (mysql, sshd, nginx, redis, ...) is explicitly NOT protected.
+ */
+export declare const DSH_WEB_PORTS: number[];
+export type TreeBoundaryKind = 'none' | 'launcher' | 'service-manager';
+/**
+ * Boundary classification for the ancestor walk — mirrors
+ * `skills/dsh-safe-restart/scripts/restart-dsh-web.sh`'s `resolve_tree()`:
+ * the walk stops at `pnpm` (the launcher — everything above it is the
+ * launching shell, not dsh web) and never walks into a `systemd --user`
+ * manager (it owns every user unit on the box). `launcher` pids stay in the
+ * forest; `service-manager` pids are never included.
+ */
+export declare function treeBoundaryKind(commandLine: string): TreeBoundaryKind;
+/** Convenience boolean form of {@link treeBoundaryKind}. */
+export declare function isTreeBoundary(commandLine: string): boolean;
+export interface ProcessRow {
+    pid: number;
+    ppid: number;
+}
+/**
+ * Resolve the pids that belong to the dsh web process forest. `listeners` are
+ * the pids owning the dsh-web ports (already narrowed by the caller). A pid is
+ * protected iff its upward ancestor chain reaches the forest before pid 1:
+ *
+ *   - the forest roots are the listeners plus every ancestor up to the
+ *     `launcher` boundary (pnpm stays inside the forest; systemd --user and
+ *     the launching shell stay out);
+ *   - the descendant closure then protects the whole owned subtree — the dsh
+ *     web node processes AND their bash-tool/browser children — while never
+ *     climbing into unrelated ancestors.
+ *
+ * `boundary(pid)` classifies the command line of a walked pid; it is only
+ * invoked for the handful of listener + ancestor pids, never for the full
+ * table.
+ */
+export declare function resolveDshWebTreePids(listeners: number[], rows: ProcessRow[], boundary?: (pid: number) => TreeBoundaryKind): number[];
+/**
+ * Whether a shell command is a self-kill. `livePids` are the pids of the dsh
+ * web process forest; 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;
+/**
+ * Live pids of the dsh web OWN forest: pids owning the dsh-web ports
+ * (3000/3080) plus their ancestor chain up to the pnpm/systemd boundary and
+ * the owned subtree. A kill of an unrelated listener (mysql/sshd/nginx) is
+ * therefore allowed — before this scoping the guard denied `kill <pid>` of ANY
+ * pid holding a listening socket as a "restart dsh web".
+ */
+export declare function dshWebTreeLivePids(): number[];
+/**
+ * Build a `tools/pre-execute` waterfall listener: deny matching
+ * bash/shell/exec commands, otherwise delegate to `next()`. Live pids default
+ * to the dsh web process forest (see `dshWebTreeLivePids`) so `kill <pid>` of
+ * a live host process is caught even when the command names no tool, while a
+ * kill of an unrelated service is not.
+ */
+export declare function makePreExecuteGuard(opts?: {
+    livePids?: () => number[];
+}): (exec: any, next: () => Promise<any>) => Promise<any>;

package/lib/self-kill-guard.js

@@ -0,0 +1,169 @@
+/**
+ * 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;
+/**
+ * The dsh web MainThread owns both ports (3000 = gitlab-webhook, 3080 = web).
+ * Only listeners on these ports can be dsh web; every other listening process
+ * on the host (mysql, sshd, nginx, redis, ...) is explicitly NOT protected.
+ */
+export const DSH_WEB_PORTS = [3000, 3080];
+/**
+ * Boundary classification for the ancestor walk — mirrors
+ * `skills/dsh-safe-restart/scripts/restart-dsh-web.sh`'s `resolve_tree()`:
+ * the walk stops at `pnpm` (the launcher — everything above it is the
+ * launching shell, not dsh web) and never walks into a `systemd --user`
+ * manager (it owns every user unit on the box). `launcher` pids stay in the
+ * forest; `service-manager` pids are never included.
+ */
+export function treeBoundaryKind(commandLine) {
+    if (commandLine.includes('pnpm'))
+        return 'launcher';
+    if (commandLine.includes('systemd --user'))
+        return 'service-manager';
+    return 'none';
+}
+/** Convenience boolean form of {@link treeBoundaryKind}. */
+export function isTreeBoundary(commandLine) {
+    return treeBoundaryKind(commandLine) !== 'none';
+}
+/**
+ * Resolve the pids that belong to the dsh web process forest. `listeners` are
+ * the pids owning the dsh-web ports (already narrowed by the caller). A pid is
+ * protected iff its upward ancestor chain reaches the forest before pid 1:
+ *
+ *   - the forest roots are the listeners plus every ancestor up to the
+ *     `launcher` boundary (pnpm stays inside the forest; systemd --user and
+ *     the launching shell stay out);
+ *   - the descendant closure then protects the whole owned subtree — the dsh
+ *     web node processes AND their bash-tool/browser children — while never
+ *     climbing into unrelated ancestors.
+ *
+ * `boundary(pid)` classifies the command line of a walked pid; it is only
+ * invoked for the handful of listener + ancestor pids, never for the full
+ * table.
+ */
+export function resolveDshWebTreePids(listeners, rows, boundary = () => 'launcher') {
+    const byPid = new Map(rows.map(r => [r.pid, r]));
+    const roots = new Set();
+    for (const pid of listeners) {
+        let cur = pid;
+        for (let depth = 0; cur && cur !== 1 && depth < 100 && !roots.has(cur); depth++) {
+            const row = byPid.get(cur);
+            if (!row)
+                break;
+            const kind = boundary(cur);
+            if (kind === 'service-manager')
+                break; // never climb into systemd --user
+            roots.add(cur);
+            if (kind === 'launcher')
+                break; // pnpm is the ceiling of the forest
+            if (row.ppid === cur || row.ppid <= 0)
+                break;
+            cur = row.ppid;
+        }
+    }
+    const protectedSet = new Set(roots);
+    for (const row of rows) {
+        let cur = row.pid;
+        for (let depth = 0; cur && cur !== 1 && depth < 100; depth++) {
+            if (roots.has(cur)) {
+                protectedSet.add(row.pid);
+                break;
+            }
+            const next = byPid.get(cur);
+            if (!next || next.ppid === cur || next.ppid <= 0)
+                break;
+            cur = next.ppid;
+        }
+    }
+    return [...protectedSet].sort((a, b) => a - b);
+}
+/**
+ * Whether a shell command is a self-kill. `livePids` are the pids of the dsh
+ * web process forest; 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);
+}
+/**
+ * Live pids of the dsh web OWN forest: pids owning the dsh-web ports
+ * (3000/3080) plus their ancestor chain up to the pnpm/systemd boundary and
+ * the owned subtree. A kill of an unrelated listener (mysql/sshd/nginx) is
+ * therefore allowed — before this scoping the guard denied `kill <pid>` of ANY
+ * pid holding a listening socket as a "restart dsh web".
+ */
+export function dshWebTreeLivePids() {
+    try {
+        const { execSync } = require('node:child_process');
+        const filter = DSH_WEB_PORTS.map(p => `sport = :${p}`).join(' or ');
+        const out = execSync(`ss -tlnp '( ${filter} )' 2>/dev/null | sed -n 's/.*pid=\\([0-9]*\\).*/\\1/p' | sort -u`, { encoding: 'utf8' });
+        const listeners = out.trim().split('\n').filter(Boolean).map(Number);
+        if (listeners.length === 0)
+            return [];
+        const psOut = execSync(`ps -eo pid=,ppid=`, { encoding: 'utf8' });
+        const rows = psOut.trim().split('\n')
+            .map(line => line.trim().split(/\s+/))
+            .filter(p => p.length >= 2 && /^\d+$/.test(p[0]) && /^\d+$/.test(p[1]))
+            .map(([pid, ppid]) => ({ pid: Number(pid), ppid: Number(ppid) }));
+        // Command lines are only fetched for the walked listener/ancestor pids
+        // (a handful of subprocess calls), never for the whole process table.
+        const boundary = (pid) => {
+            try {
+                const args = execSync(`ps -o args= -p ${pid}`, { encoding: 'utf8' });
+                return treeBoundaryKind(args);
+            }
+            catch {
+                return 'launcher'; // gone or unreadable → stop walking right here
+            }
+        };
+        return resolveDshWebTreePids(listeners, rows, boundary);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Build a `tools/pre-execute` waterfall listener: deny matching
+ * bash/shell/exec commands, otherwise delegate to `next()`. Live pids default
+ * to the dsh web process forest (see `dshWebTreeLivePids`) so `kill <pid>` of
+ * a live host process is caught even when the command names no tool, while a
+ * kill of an unrelated service is not.
+ */
+export function makePreExecuteGuard(opts = {}) {
+    const livePids = opts.livePids ?? dshWebTreeLivePids;
+    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>;
+};