@ddtcorex/dsh-maestro-supervisor 0.6.8 → 0.7.1

package/lib/cli.d.ts

@@ -1 +1,14 @@
+/**
+ * Copy a chosen LKG snapshot back into the DSH home. Recent snapshots are
+ * tried newest-first, skipping any that still carry a failing plugin so a
+ * broken bundle is not restored. `sessions/` is deliberately NOT restored —
+ * session logs are append-only truth and rolling them back to a snapshot
+ * would drop every turn recorded after that snapshot.
+ * @returns the rolled-back snapshot id.
+ */
+export declare function rollbackLKG(opts: {
+    dshHome: string;
+    lkgRoot: string;
+    failingPlugin?: string;
+}): Promise<string>;
 export declare function runCli(args: string[]): Promise<void>;

package/lib/cli.js

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

package/lib/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"];
+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

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

package/lib/restart-guards.d.ts

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

package/lib/restart-guards.js

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

package/lib/restart-tool.d.ts

@@ -0,0 +1,83 @@
+/**
+ * dsh_web_restart tool — the safe restart path for the model running inside
+ * dsh web. Scheduling a restart through this tool instead of a raw kill keeps
+ * the restart inside the supervisor's ownership loop:
+ *
+ *   1. dry-boot gate — if the plugin tree changed since the latest LKG, boot a
+ *      copy of the live profile on an ephemeral DSH_HOME first and only
+ *      schedule when that boot serves HTTP.
+ *   2. intent sidecar — record the caller session + reason under
+ *      ~/.dsh/.supervisor/intents/ for attribution.
+ *   3. hand-off — write the restart-request marker (planned-restart.json with
+ *      callerSessionId) that the supervisor daemon owns and acts on
+ *      (out-of-band). This tool NEVER restarts the host in-tree.
+ */
+import { writeRestartRequest } from './restart-guards.js';
+/**
+ * Boot a copy of the live web profile on an isolated DSH_HOME and verify the
+ * plugin tree loads and serves. Returns ok + a one-line detail for the tool
+ * message. The spawned tree is killed (best-effort) and the temp home removed.
+ * Unit tests mock this (never spawn a real node boot in tests).
+ *
+ * NOTE (bin.ts finding): the `web` alias already implies `--profile web`, and
+ * the web app's own commander program (no allowUnknownOption) rejects a stray
+ * `--profile` in its inner args — so the spawn passes only `web --no-open
+ * --port <port>`.
+ */
+export declare function dryBootVerify(harnessRoot: string, opts?: {
+    timeoutMs?: number;
+}): Promise<{
+    ok: boolean;
+    detail: string;
+}>;
+/**
+ * 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. 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 declare function isPluginTreeChanged(harnessRoot: string, lkgDir?: string, opts?: {
+    statFile?: (p: string) => FileStat;
+}): boolean;
+/**
+ * Register the dsh_web_restart tool. Registration is fail-safe (warns, never
+ * throws) and the returned function disposes the registration. `deps` are
+ * injectable for tests.
+ */
+export declare function registerRestartTool(ctx: any, deps?: {
+    sessionIdOf?: (exec: any) => string | undefined;
+    dryBoot?: typeof dryBootVerify;
+    writeRestartRequest?: typeof writeRestartRequest;
+    harnessRoot?: string;
+}): () => void;