@ddtcorex/dsh-maestro-supervisor 0.7.0 → 0.7.1

package/lib/intents.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Durable self-restart intent sidecar written by `dsh_web_restart`
+ * (`~/.dsh/.supervisor/intents/<sessionId>.json`, mode 600). Consumed by
+ * auto-resume so a session that requested the restart is resumed with a
+ * contextual message instead of the generic "outcome unknown" recovery text.
+ */
+export interface RestartIntent {
+    ts: number;
+    sessionId?: string;
+    reason?: string;
+}
+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;

package/lib/intents.js

@@ -0,0 +1,27 @@
+import { existsSync, readFileSync, unlinkSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+export function intentsDir() {
+    return join(homedir(), '.dsh', '.supervisor', 'intents');
+}
+export function intentPath(sessionId) {
+    const safe = sessionId.replace(/[^A-Za-z0-9._-]/g, '_');
+    return join(intentsDir(), `${safe}.json`);
+}
+export function readIntent(sessionId) {
+    try {
+        const p = intentPath(sessionId);
+        if (!existsSync(p))
+            return undefined;
+        return JSON.parse(readFileSync(p, 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+}
+export function consumeIntent(sessionId) {
+    try {
+        unlinkSync(intentPath(sessionId));
+    }
+    catch { }
+}

package/lib/plugin.d.ts

@@ -6,7 +6,8 @@
  * 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", "skills"];
+import type { RestartIntent } from './intents.js';
+export declare const inject: readonly ["sessions", "agents", "connection", "tools", "skills"];
 export interface SupervisorPluginConfig {
     autoResumeWithin?: number | string;
     autoResumeEnabled?: boolean;
@@ -17,7 +18,10 @@ export declare function runAutoResume(ctx: any, opts?: {
     resumeInterrupted?: typeof resumeInterrupted;
     config?: SupervisorPluginConfig;
 }): Promise<void>;
-export declare function resumeInterrupted(ctx: any, ids: string[]): Promise<string[]>;
+export declare function resumeInterrupted(ctx: any, ids: string[], deps?: {
+    readIntent?: (id: string) => RestartIntent | undefined;
+    consumeIntent?: (id: string) => void;
+}): Promise<string[]>;
 export declare function createResumeRpcHandler(ctx: any, opts?: {
     resumeInterrupted?: typeof resumeInterrupted;
     config?: SupervisorPluginConfig;

package/lib/plugin.js

@@ -10,11 +10,12 @@ 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';
+import { readIntent, consumeIntent } from './intents.js';
 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'];
+export const inject = ['sessions', 'agents', 'connection', 'tools', 'skills'];
 function parseDuration(s) {
     if (!s)
         return undefined;
@@ -171,7 +172,9 @@ export async function runAutoResume(ctx, opts = {}) {
         catch { }
     }
 }
-export async function resumeInterrupted(ctx, ids) {
+export async function resumeInterrupted(ctx, ids, deps = {}) {
+    const doReadIntent = deps.readIntent ?? readIntent;
+    const doConsumeIntent = deps.consumeIntent ?? consumeIntent;
     const resumed = [];
     for (const id of ids) {
         try {
@@ -246,15 +249,31 @@ export async function resumeInterrupted(ctx, ids) {
             // model to verify external state before retrying. A bare "continue" made
             // the model reply with text instead of re-issuing bash, leaving the
             // session stuck after every crash (36646045..., 31ae53a2...).
-            const resumeMessage = 'The previous turn was interrupted by a crash and the harness has synthesized a tool result with TOOL_OUTCOME_UNKNOWN / TOOL_NOT_STARTED. ' +
+            const idleMessage = 'The previous turn was interrupted by a crash and the harness has synthesized a tool result with TOOL_OUTCOME_UNKNOWN / TOOL_NOT_STARTED. ' +
                 'Outcome of the last tool call is unknown — it may or may not have had side effects. ' +
                 'Verify external state with bash (e.g., ls, cat, git status) before retrying. ' +
                 'Retry only if the operation is read-only or idempotent; if it may have side effects, verify first or ask the user. ' +
                 'Then continue the original task from where it was interrupted — re-issue the next bash/tool call that the plan requires.';
+            // A session that requested the dsh web restart has a durable intent
+            // sidecar (written by dsh_web_restart): resume it with a contextual
+            // message instead of the generic "outcome unknown" recovery prompt, then
+            // consume the sidecar so it cannot re-trigger on a later resume.
+            let resumeMessage = idleMessage;
+            try {
+                const intent = doReadIntent(sessionId);
+                if (intent)
+                    resumeMessage = `You requested a dsh web restart${intent.reason ? ` (reason: ${intent.reason})` : ''} and it completed. Do NOT call dsh_web_restart again. Verify current state if needed, then continue the original task.`;
+            }
+            catch { }
             agent.followup(createUserMessage({
                 content: [{ type: 'text', text: resumeMessage }],
                 source: { kind: 'user' },
             }));
+            try {
+                if (resumeMessage !== idleMessage)
+                    doConsumeIntent(sessionId);
+            }
+            catch { }
             resumed.push(id);
             ctx.logger?.info?.(`[supervisor] auto-resume: sent recovery continue for ${id}`);
         }

package/lib/restart-tool.d.ts

@@ -30,16 +30,29 @@ export declare function dryBootVerify(harnessRoot: string, opts?: {
     ok: boolean;
     detail: string;
 }>;
+/**
+ * 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 declare function dryBootFailureDetail(tail: string, exitCode: number): 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
+ * 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. plugin-lib drift — any `@ddtcorex` plugin `lib/` file newer than the
+ *   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

package/lib/restart-tool.js

@@ -66,7 +66,9 @@ export async function dryBootVerify(harnessRoot, opts = {}) {
         }
         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})`) };
+        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)}` };
@@ -87,11 +89,34 @@ export async function dryBootVerify(harnessRoot, opts = {}) {
     }
 }
 /**
- * Whether the live plugin tree differs from the latest LKG snapshot. Two
+ * 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. plugin-lib drift — any `@ddtcorex` plugin `lib/` file newer than the
+ *   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
@@ -122,6 +147,17 @@ export function isPluginTreeChanged(harnessRoot, lkgDir = join(homedir(), '.dsh/
             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

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

@@ -5,21 +5,69 @@
  * 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.
+ * 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 pids holding listening sockets (`ss -tlnp`) so `kill <pid>` of a
- * live host process is caught even when the command names no tool.
+ * 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[];

package/lib/self-kill-guard.js

@@ -12,14 +12,91 @@ const require = createRequire(import.meta.url);
 // 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.
+ * 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)) {
@@ -34,23 +111,52 @@ export function isSelfKillCommand(cmd, livePids) {
         && !/^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 pids holding listening sockets (`ss -tlnp`) so `kill <pid>` of a
- * live host process is caught even when the command names no tool.
+ * 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 ?? (() => {
-        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 [];
-        }
-    });
+    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.

package/package.json

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