@ddtcorex/dsh-maestro-supervisor 0.6.8 → 0.7.0

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.8",
+  "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"
   ],

package/skills/dsh-safe-restart/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: dsh-safe-restart
+description: Use before updating any dsh-maestro-* client bundle or DSH Web asset, or before reloading the running dsh web host process; validate first and perform a user-approved host restart through the bundled guarded recipe. In-session agents use the `dsh_web_restart` tool; hand off to a human only if the tool is unavailable.
+compatibility: dsh
+---
+
+# Safe DSH Web Restart
+
+## Purpose
+
+One `dsh web` process serves both the live Web UI on port 3080 and the
+GitLab-webhook service on port 3000. A host restart drops the live socket and
+the in-flight turn, although sessions rehydrate from the append-only log when
+the browser reconnects. Treat a restart as disruptive: validate first and get
+explicit user consent before a real swap.
+
+## Classify the change before touching the live process
+
+- **Static asset in `apps/web/dist/`** — patch the asset and verify served
+  bytes with `curl`; no restart.
+- **Client plugin bundle** (client JavaScript, CSS, slots, React) — run that
+  package's `build:client`, confirm a bundle marker, then refresh the browser;
+  no host restart.
+- **Host Node library, `cordis.patch.yml`, or profile plugin composition** —
+  validate a candidate and restart only after the user says to do so.
+
+## Required preflight for a host restart
+
+1. Run relevant package tests and build steps, then check the output really
+   carries the expected marker.
+2. Dry-boot the candidate on an ephemeral port with an isolated `DSH_HOME`.
+   Keep the live process and its sessions/settings untouched. If the review
+   webhook conflicts on port 3000, exclude that provider for the candidate or
+   run a no-server composition check instead.
+3. Verify HTTP 200 and the new marker on the candidate. Retain last-known-good
+   assets until the real swap has passed post-swap checks.
+4. Ask for explicit consent and timing. “restart đi” is consent; silence is
+   not.
+
+## Run the bundled helper only after consent
+
+The skill loader provides this directory as the skill resource base. Substitute
+that real path for `<skill-resource-base>`; never use a copied, machine-specific
+path from documentation.
+
+```bash
+# Safe inspection only: resolves the serving tree but changes nothing.
+bash <skill-resource-base>/scripts/restart-dsh-web.sh \
+  --repo /path/to/deepseek-harness --dry-run
+```
+
+Run the `dsh_web_restart` tool instead of executing the helper — the helper is
+for external agents and humans. In-session agents must never run it from their
+own turn (see "Never do these" below).
+
+`--repo` may be replaced by `DSH_REPO`; `--log` or `DSH_RESTART_LOG` changes
+the append-only log destination. The helper refuses a real swap without
+`--confirm`, dynamically resolves listeners rather than trusting saved PIDs,
+and refuses to launch if ports are still occupied. `--dry-run` never runs
+`kill` or `setsid`.
+
+## Post-swap checks
+
+Do not read the top of an old append-only log as liveness evidence. Instead:
+
+1. Confirm exactly one healthy listener tree owns ports 3000 and 3080 with
+   `ss -tlnp`.
+2. Confirm HTTP 200 from port 3080.
+3. Check served bytes contain the **new**, unique marker; or make a fresh
+   browser/Playwright probe for the changed UI. Shared third-party markers are
+   not sufficient proof.
+4. If a marker or live behaviour is wrong, restore the retained last-known-good
+   assets and relaunch with the same guarded process.
+
+## Never do these
+
+- Kill the process from an inline agent shell; the killing action can terminate
+  that shell before it relaunches DSH.
+- **Never invoke this skill from inside a DSH chat session's agent turn.** The agent itself runs inside `dsh web`; killing `dsh web` from its own turn interrupts that turn (`interrupted` in the append-only log) and the `setsid nohup` relaunch never completes from the killed shell. If you are an agent, run the `dsh_web_restart` tool instead — it performs the swap from the safe side of the tree. Print the exact `setsid nohup ... --confirm` command only when the tool is unavailable, and only for the human to run in their own terminal; do not execute it yourself.
+- Restart for a client-only or static change.
+- Hard-code a PID or a local developer's workspace path.
+- Treat a 200 response alone as proof that a rebuilt plugin was loaded.
+
+## Agent handoff (required when you are an agent)
+
+If you are running inside `dsh web` (any `dsh-*` skill, `maestro-*` skill, or subagent), you **must not** execute the helper or the restart yourself:
+
+1. Run all preflight checks (`--dry-run`, `pnpm verify`, marker grep) and report the results.
+2. Run the `dsh_web_restart` tool instead of executing the helper — the helper is for external agents and humans.
+3. If the tool reports it is unavailable, print the exact detached `setsid nohup ... --confirm` command for the human to run; then wait for explicit human confirmation in a new terminal. The interrupted turn will rehydrate from the log when the browser reconnects — no data is lost.