@ddtcorex/dsh-maestro-supervisor 0.7.10 → 0.8.0

package/lib/intents.d.ts

@@ -13,3 +13,20 @@ export declare function intentsDir(): string;
 export declare function intentPath(sessionId: string): string;
 export declare function readIntent(sessionId: string): RestartIntent | undefined;
 export declare function consumeIntent(sessionId: string): void;
+/**
+ * Post-swap outcome written by the supervisor daemon after acting on a
+ * restart request (`<sessionId>.outcome.json`, mode 600, same dir). Read by
+ * `dsh_web_restart_status` so callers learn the new PID + HTTP status without
+ * hand-probing `ss`/`curl`.
+ */
+export interface RestartOutcome {
+    state: 'ok' | 'failed';
+    oldPid?: number;
+    newPid?: number;
+    httpStatus?: number;
+    swappedAt: number;
+    error?: string;
+}
+export declare function outcomePath(sessionId: string): string;
+export declare function writeRestartOutcome(sessionId: string, outcome: RestartOutcome): void;
+export declare function readRestartOutcome(sessionId: string): RestartOutcome | undefined;

package/lib/intents.js

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync, unlinkSync } from 'node:fs';
+import { existsSync, readFileSync, unlinkSync, mkdirSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { homedir } from 'node:os';
 export function intentsDir() {
@@ -25,3 +25,25 @@ export function consumeIntent(sessionId) {
     }
     catch { }
 }
+export function outcomePath(sessionId) {
+    const safe = sessionId.replace(/[^A-Za-z0-9._-]/g, '_');
+    return join(intentsDir(), `${safe}.outcome.json`);
+}
+export function writeRestartOutcome(sessionId, outcome) {
+    try {
+        mkdirSync(intentsDir(), { recursive: true });
+        writeFileSync(outcomePath(sessionId), JSON.stringify(outcome), { encoding: 'utf8', mode: 0o600 });
+    }
+    catch { }
+}
+export function readRestartOutcome(sessionId) {
+    try {
+        const p = outcomePath(sessionId);
+        if (!existsSync(p))
+            return undefined;
+        return JSON.parse(readFileSync(p, 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+}

package/lib/restart-guards.d.ts

@@ -11,9 +11,11 @@ export interface RestartRequest {
     ttl: number;
     callerSessionId?: string;
     reason?: string;
+    oldPid?: number;
 }
 export declare function writeRestartRequest(caller: {
     callerSessionId?: string;
     reason?: string;
+    oldPid?: number;
 }, ttlMs?: number): void;
 export declare function readRestartRequest(): RestartRequest | undefined;

package/lib/restart-guards.js

@@ -109,7 +109,7 @@ export function readRestartRequest() {
         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 };
+            return { ts: j.ts, ttl: j.ttl, callerSessionId: j.callerSessionId, reason: j.reason, oldPid: j.oldPid };
         }
     }
     catch { }

package/lib/restart-tool.d.ts

@@ -23,6 +23,32 @@ import { writeRestartRequest } from './restart-guards.js';
  * (the dry-boot must stay faithful, not fix the live tree).
  */
 export declare function copyProfileForDryBoot(srcDir: string, destDir: string): void;
+/**
+ * A dry-boot orphan candidate: a `dsh web` process rooted at a temp DSH_HOME
+ * with an ephemeral-port listener. Ports 3080/3081/3082 are the live tree and
+ * can never be candidates.
+ */
+export interface DryBootCandidate {
+    pid: number;
+    port: number;
+    dshHome: string;
+}
+export interface GcReaders {
+    readProc?: () => Array<{
+        pid: number;
+        cmd: string;
+        env: string;
+    }>;
+    ssPortsOf?: (pid: number) => number[];
+    selfPid?: number;
+}
+/**
+ * List dry-boot orphans: `dsh web` processes on a temp DSH_HOME holding an
+ * ephemeral 9000-9999 listener. Conjunctive fingerprint + absolute exclusions
+ * (self PID, live ports, real-home DSH_HOME) — a process is returned only when
+ * every signal agrees it is a disposable dry-boot.
+ */
+export declare function listDryBootCandidates(readers?: GcReaders): DryBootCandidate[];
 /**
  * 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
@@ -90,4 +116,6 @@ export declare function registerRestartTool(ctx: any, deps?: {
     dryBoot?: typeof dryBootVerify;
     writeRestartRequest?: typeof writeRestartRequest;
     harnessRoot?: string;
+    gcReaders?: GcReaders;
+    killPid?: (pid: number, sig: string) => void;
 }): () => void;

package/lib/restart-tool.js

@@ -15,9 +15,10 @@
 import { join, dirname, resolve } from 'node:path';
 import { mkdtempSync, rmSync, cpSync, existsSync, readFileSync, readdirSync, statSync, lstatSync, readlinkSync, symlinkSync, unlinkSync } from 'node:fs';
 import { tmpdir, homedir } from 'node:os';
-import { spawn } from 'node:child_process';
+import { spawn, execFileSync } from 'node:child_process';
 import { createRequire } from 'node:module';
 import { writeRestartRequest } from './restart-guards.js';
+import { intentPath, readIntent, readRestartOutcome } from './intents.js';
 /**
  * Copy a live profile tree for an isolated dry-boot. A naive recursive copy
  * breaks `link:` installs: their node_modules entries are relative symlinks
@@ -50,6 +51,74 @@ export function copyProfileForDryBoot(srcDir, destDir) {
     };
     repair(destDir, '');
 }
+const LIVE_PORTS = new Set([3080, 3081, 3082]);
+function defaultReadProc() {
+    const out = [];
+    let names = [];
+    try {
+        names = readdirSync('/proc');
+    }
+    catch {
+        return out;
+    }
+    for (const name of names) {
+        if (!/^\d+$/.test(name))
+            continue;
+        try {
+            const cmd = readFileSync(`/proc/${name}/cmdline`, 'utf8').replace(/\0/g, ' ');
+            const env = readFileSync(`/proc/${name}/environ`, 'utf8');
+            out.push({ pid: Number(name), cmd, env });
+        }
+        catch { /* process exited mid-scan — ignore */ }
+    }
+    return out;
+}
+function defaultSsPortsOf(pid) {
+    try {
+        const out = execFileSync('ss', ['-tlnp'], { encoding: 'utf8' });
+        const ports = [];
+        for (const line of out.split('\n')) {
+            if (!line.includes(`pid=${pid},`))
+                continue;
+            const m = /:(\d+)\s/.exec(line);
+            if (m)
+                ports.push(Number(m[1]));
+        }
+        return ports;
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * List dry-boot orphans: `dsh web` processes on a temp DSH_HOME holding an
+ * ephemeral 9000-9999 listener. Conjunctive fingerprint + absolute exclusions
+ * (self PID, live ports, real-home DSH_HOME) — a process is returned only when
+ * every signal agrees it is a disposable dry-boot.
+ */
+export function listDryBootCandidates(readers = {}) {
+    const readProc = readers.readProc ?? defaultReadProc;
+    const ssPortsOf = readers.ssPortsOf ?? defaultSsPortsOf;
+    const selfPid = readers.selfPid ?? process.pid;
+    const out = [];
+    for (const p of readProc()) {
+        if (p.pid === selfPid)
+            continue;
+        if (!/bin\.ts web/.test(p.cmd))
+            continue;
+        const home = /^DSH_HOME=([^\0]*)/m.exec(p.env)?.[1] ?? '';
+        if (!home.startsWith(join(tmpdir(), 'dsh-dryboot-')))
+            continue;
+        const ports = ssPortsOf(p.pid);
+        if (ports.some(port => LIVE_PORTS.has(port)))
+            continue;
+        const eph = ports.filter(port => port >= 9000 && port <= 9999);
+        if (eph.length === 0)
+            continue;
+        out.push({ pid: p.pid, port: eph[0], dshHome: home });
+    }
+    return out;
+}
 /**
  * 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
@@ -239,6 +308,9 @@ export function registerRestartTool(ctx, deps = {}) {
     const doWrite = deps.writeRestartRequest ?? writeRestartRequest;
     const doSessionId = deps.sessionIdOf ?? currentSessionId;
     let dispose;
+    let disposeDryboot;
+    let disposeGc;
+    let disposeStatus;
     try {
         dispose = ctx.tools.register({
             name: 'dsh_web_restart',
@@ -270,9 +342,9 @@ export function registerRestartTool(ctx, deps = {}) {
                     // 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);
+                doWrite({ callerSessionId, reason: typeof args.reason === 'string' ? args.reason : undefined, oldPid: process.pid }, 180_000);
                 writeIntentSidecar(callerSessionId, args.reason);
-                return { ok: true, detail: `restart scheduled (≈30s) — caller ${callerSessionId}` };
+                return { ok: true, detail: `restart scheduled (≈30s) — caller ${callerSessionId}`, oldPid: process.pid, intentPath: intentPath(callerSessionId) };
             },
         });
     }
@@ -282,11 +354,135 @@ export function registerRestartTool(ctx, deps = {}) {
         }
         catch { }
     }
-    return () => { try {
-        if (typeof dispose === 'function')
-            dispose();
+    try {
+        disposeDryboot = ctx.tools.register({
+            name: 'dsh_web_dryboot',
+            description: 'Validate the plugin tree by booting a copy of the live profile on an ephemeral port. Never schedules or performs a restart; temp home removed afterwards.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    timeoutMs: { type: 'number', description: 'Gate timeout in ms (default 60000).' },
+                },
+                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) => {
+                const harnessRoot = deps.harnessRoot ?? (await import('./paths.js')).resolveDeepseekHarnessDir();
+                const gate = await doDryBoot(harnessRoot, typeof args.timeoutMs === 'number' ? { timeoutMs: args.timeoutMs } : undefined);
+                return { ok: gate.ok, detail: gate.detail };
+            },
+        });
+    }
+    catch (e) {
+        try {
+            ctx.logger?.warn?.(`[supervisor] dsh_web_dryboot tool failed: ${e?.message ?? String(e)}`);
+        }
+        catch { }
+    }
+    try {
+        const doKill = deps.killPid ?? ((pid, sig) => process.kill(pid, sig));
+        disposeGc = ctx.tools.register({
+            name: 'dsh_web_gc',
+            description: 'Reap orphaned dry-boot dsh web processes (temp DSH_HOME + ephemeral port). Preview-first: returns candidates without killing unless confirm:true.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    confirm: { type: 'boolean', description: 'Actually SIGKILL the candidates and verify they are gone.' },
+                },
+                additionalProperties: false,
+            },
+            output: {
+                schema: { type: 'object', additionalProperties: true, properties: { killed: { type: 'array' }, candidates: { type: 'array' } } },
+                render: (_args, value) => [{ type: 'text', text: JSON.stringify(value) }],
+            },
+            execute: async (args) => {
+                // INVARIANT: kill only conjunctive-fingerprint dry-boots (temp DSH_HOME
+                // + ephemeral listener), never self / live ports / real-home processes.
+                // Preview is the default; killing requires explicit confirm:true.
+                const found = listDryBootCandidates(deps.gcReaders);
+                if (args.confirm !== true)
+                    return { killed: [], candidates: found };
+                const killed = [];
+                for (const c of found) {
+                    try {
+                        doKill(c.pid, 'SIGKILL');
+                    }
+                    catch { }
+                }
+                const remaining = listDryBootCandidates(deps.gcReaders);
+                const alive = new Set(remaining.map(c => c.pid));
+                for (const c of found) {
+                    if (!alive.has(c.pid))
+                        killed.push(c.pid);
+                }
+                return { killed, candidates: remaining };
+            },
+        });
+    }
+    catch (e) {
+        try {
+            ctx.logger?.warn?.(`[supervisor] dsh_web_gc tool failed: ${e?.message ?? String(e)}`);
+        }
+        catch { }
+    }
+    try {
+        disposeStatus = ctx.tools.register({
+            name: 'dsh_web_restart_status',
+            description: 'Read the outcome of the calling session\u2019s latest scheduled dsh web restart (pending until the daemon swaps and health-checks).',
+            parameters: {
+                type: 'object',
+                properties: {},
+                additionalProperties: false,
+            },
+            output: {
+                schema: { type: 'object', additionalProperties: true },
+                render: (_args, value) => [{ type: 'text', text: JSON.stringify(value) }],
+            },
+            execute: async (_args, exec) => {
+                const callerSessionId = doSessionId(exec);
+                if (!callerSessionId)
+                    return { state: 'none', detail: 'cannot identify the calling session' };
+                const outcome = readRestartOutcome(callerSessionId);
+                if (outcome)
+                    return { ...outcome };
+                const intent = readIntent(callerSessionId);
+                if (intent)
+                    return { state: 'pending', detail: 'restart scheduled, daemon has not reported back yet' };
+                return { state: 'none', detail: 'no restart scheduled for this session' };
+            },
+        });
     }
-    catch { } };
+    catch (e) {
+        try {
+            ctx.logger?.warn?.(`[supervisor] dsh_web_restart_status tool failed: ${e?.message ?? String(e)}`);
+        }
+        catch { }
+    }
+    return () => {
+        try {
+            if (typeof dispose === 'function')
+                dispose();
+        }
+        catch { }
+        try {
+            if (typeof disposeDryboot === 'function')
+                disposeDryboot();
+        }
+        catch { }
+        try {
+            if (typeof disposeGc === 'function')
+                disposeGc();
+        }
+        catch { }
+        try {
+            if (typeof disposeStatus === 'function')
+                disposeStatus();
+        }
+        catch { }
+    };
 }
 function writeIntentSidecar(sessionId, reason) {
     try {

package/lib/supervisor.d.ts

@@ -1,5 +1,6 @@
 import type { HealthState } from './health-poller.js';
 import type { RestartRequest } from './restart-guards.js';
+import { type RestartOutcome } from './intents.js';
 import { type MintCookieOpts } from './dsh-session.js';
 export interface SupervisorDeps {
     pollHealth: () => Promise<HealthState>;
@@ -45,7 +46,11 @@ export interface SupervisorDeps {
     }>;
     readRestartRequest?: () => RestartRequest | undefined;
     onRestartRequestHandled?: (req: RestartRequest) => void;
+    writeOutcome?: (sessionId: string, outcome: RestartOutcome) => void;
+    listenerPid?: (port: number) => number | undefined;
 }
+/** PID holding a 127.0.0.1 listener on the port, or undefined. Never throws. */
+export declare function defaultListenerPid(port: number): number | undefined;
 export declare function resumeViaRpc(ids: string[], fetchFn?: (url: string, init: RequestInit) => Promise<Response>, extraHeaders?: Record<string, string>): Promise<{
     resumed: string[];
 }>;

package/lib/supervisor.js

@@ -6,8 +6,23 @@ import * as os from 'node:os';
 import { resolveHarnessRoot } from './paths.js';
 import { readSupervisorConfig } from './config.js';
 import { writePlannedRestart as defaultWritePlannedRestart, checkPlannedRestart as defaultCheckPlannedRestart, clearPlannedRestart, PLANNED_RESTART_TTL_MS } from './restart-guards.js';
+import { writeRestartOutcome as defaultWriteOutcome } from './intents.js';
+import { execFileSync } from 'node:child_process';
 import { mintDshSessionCookie } from './dsh-session.js';
 import { buildKillStalePortsCommand } from './restart-guards.js';
+/** PID holding a 127.0.0.1 listener on the port, or undefined. Never throws. */
+export function defaultListenerPid(port) {
+    try {
+        const out = execFileSync('ss', ['-tlnp'], { encoding: 'utf8' });
+        for (const line of out.split('\n')) {
+            const m = new RegExp(`127\\.0\\.0\\.1:${port}\\s[^]*?pid=(\\d+)`).exec(line);
+            if (m)
+                return Number(m[1]);
+        }
+    }
+    catch { }
+    return undefined;
+}
 export async function resumeViaRpc(ids, fetchFn = globalThis.fetch, extraHeaders = {}) {
     const rpcId = crypto.randomUUID();
     const response = await fetchFn('http://127.0.0.1:3080/dsh-maestro-supervisor-resume/resume', {
@@ -359,6 +374,18 @@ export class Supervisor {
                     }
                     catch (e) {
                         await this.deps.notify(`self-restart dsh-web failed: ${e?.message ?? String(e)}`).catch(() => { });
+                        if (restartReq.callerSessionId) {
+                            try {
+                                ;
+                                (this.deps.writeOutcome ?? defaultWriteOutcome)(restartReq.callerSessionId, {
+                                    state: 'failed',
+                                    oldPid: restartReq.oldPid,
+                                    swappedAt: this.deps.getTime ? this.deps.getTime() : Date.now(),
+                                    error: e?.message ?? String(e),
+                                });
+                            }
+                            catch { }
+                        }
                     }
                     finally {
                         // Hold the marker and latch until health.up: clearing here would
@@ -506,6 +533,19 @@ export class Supervisor {
                         this.deps.onRestartRequestHandled?.(req);
                     }
                     catch { }
+                    if (req.callerSessionId) {
+                        try {
+                            const listen = this.deps.listenerPid ?? defaultListenerPid;
+                            (this.deps.writeOutcome ?? defaultWriteOutcome)(req.callerSessionId, {
+                                state: 'ok',
+                                oldPid: req.oldPid,
+                                newPid: listen(3082),
+                                httpStatus: health?.httpCode ?? 200,
+                                swappedAt: this.deps.getTime ? this.deps.getTime() : Date.now(),
+                            });
+                        }
+                        catch { }
+                    }
                 }
             }
             // Throttle LKG writes to at most once per 5 minutes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ddtcorex/dsh-maestro-supervisor",
-  "version": "0.7.10",
+  "version": "0.8.0",
   "description": "Supervisor daemon for DSH Web resilience — auto-detect crashes, rollback to LKG, report",
   "type": "module",
   "main": "./lib/index.js",

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

@@ -62,6 +62,36 @@ the append-only log destination. The helper refuses a real swap without
 and refuses to launch if ports are still occupied. `--dry-run` never runs
 `kill` or `setsid`.
 
+## In-session validation without restart
+
+In-session agents have three tools (same row as `dsh_web_restart`) that never
+touch the live process:
+
+- `dsh_web_dryboot` (`{ timeoutMs? }`) — boots a copy of the live profile on an
+  ephemeral port with an isolated `DSH_HOME` and returns `{ ok, detail }`.
+  Prefer this over hand-rolled `cp -r` + spawn: the copy repairs relative
+  `link:` symlinks and the child is always killed with the temp home removed.
+- `dsh_web_gc` (`{ confirm? }`) — lists orphaned dry-boot processes
+  (`DSH_HOME=/tmp/dsh-dryboot-*` + ephemeral listener, never self / live ports
+  / real-home processes). Default returns the preview list; `confirm:true`
+  SIGKILLs and verifies absence.
+- `dsh_web_restart_status` (no params) — reads the calling session's restart
+  outcome: `pending` until the daemon swaps, then `ok`/`failed` with
+  `oldPid`/`newPid`/`httpStatus`. `dsh_web_restart` itself now returns
+  `{ ok, detail, oldPid, intentPath }` — quote all four when reporting.
+
+Settings-staging rule: config-lib memoizes settings per process, so an
+out-of-band settings edit is invisible to the host until restart. Stage ALL
+such edits, then restart ONCE. Prefer in-host Settings UI saves — they are
+visible immediately with no restart at all.
+
+TLS note for plugin authors: Node/undici reads `NODE_EXTRA_CA_CERTS` from the
+birth environment only; assigning it at runtime is silently ignored. The
+durable path for a local CA (e.g. a Govard/Caddy dev CA) is a systemd user
+drop-in (`~/.config/systemd/user/dsh-web.service.d/*.conf` with
+`Environment=NODE_EXTRA_CA_CERTS=<path>`), followed by a daemon reload and a
+host restart.
+
 ## Post-swap checks
 
 Do not read the top of an old append-only log as liveness evidence. Instead: