@1e0zj/dsh-plugin-mall 0.4.7 → 0.4.14

package/src/cli.js

@@ -26,6 +26,7 @@
 
 import { spawn } from "node:child_process";
 import {
+  createWriteStream,
   existsSync,
   lstatSync,
   mkdirSync,
@@ -34,9 +35,12 @@ import {
   realpathSync,
   rmSync,
   symlinkSync,
+  unlinkSync,
   writeFileSync,
 } from "node:fs";
 import { tmpdir } from "node:os";
+import { EventEmitter } from "node:events";
+import { Writable } from "node:stream";
 import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import {
@@ -57,12 +61,13 @@ import {
   resolveDshHome,
   rollbackPendingSnapshot,
   validateInstalledProfile,
+  validatePendingProfile,
   validateRemoveCompletion,
 } from "./guard.js";
 // github.js imports node builtins only — the host-independence of this CLI is
 // preserved (it must keep working when the dsh host itself is broken).
 import { npmPackageInfo } from "./github.js";
-import { createRestartHelperReadyMessage } from "./restart-protocol.js";
+import { createRestartHelperReadyMessage, quoteCmdArg, RESTART_PLAN_TYPE, validateRestartPlanPayload, writeRestartHelperReadyFile } from "./restart-protocol.js";
 
 /**
  * Pin a bare package name to name@latest: pnpm's minimumReleaseAge policy
@@ -98,6 +103,17 @@ export async function announceRestartHelperReady(awaitExitPid, send = process.se
   return true;
 }
 
+/**
+ * File-channel announcement for the visible-console restart: `cmd /c start`
+ * gives this process no IPC link back to the Web Host, so the same handshake
+ * message is published as a file instead. Unlike announceRestartHelperReady,
+ * a missing channel is impossible here — a failed write rejects and the launch
+ * fails closed rather than letting the Web parent time out blind.
+ */
+export async function announceRestartHandoffViaFile(plan, awaitExitPid) {
+  await writeRestartHelperReadyFile(plan.readyFile, { awaitExitPid, guardPid: process.pid });
+}
+
 // ── small helpers ────────────────────────────────────────────────────────────
 
 // Same shell-metacharacter blocklist as installer.assertSafeSpec. The install
@@ -487,7 +503,7 @@ async function cmdAdd({ spec, profile, home, acceptWarnings }) {
   //    rolled back immediately; otherwise the marker stays pending and the next
   //    dsh startup (or `guard recover`) commits it once the plugin actually
   //    loads.
-  const validation = validateInstalledProfile(profileDir);
+  const validation = validatePendingProfile(profileDir);
   if (result.exitCode === 0 && validation.ok) {
     console.log(`[guard] installed ${spec} into profile "${profile}".`);
     console.log("Restart dsh to load it. On the next startup — or via `node src/cli.js guard recover` — the pending snapshot is committed once the profile proves loadable; if dsh fails to boot, the same command rolls it back.");
@@ -581,7 +597,7 @@ async function cmdRemove({
 
   let validation;
   try {
-    validation = validateInstalledProfile(profileDir);
+    validation = validatePendingProfile(profileDir);
   } catch (error) {
     rollbackAndThrow(`remove completed but static profile validation threw: ${error.message}`);
   }
@@ -600,26 +616,9 @@ async function cmdRemove({
 
 const DEFAULT_GRACE_MS = 10000;
 
-// cmd.exe metacharacters. Rather than "escaping" these for a cmd round trip
-// (cmd's quoting rules are famously inconsistent), the launch wrapper refuses
-// them outright — a dsh invocation never needs them.
-const CMD_METACHAR_RE = /[&|<>^%!\r\n]/;
-
-/**
- * Quote one token for a %ComSpec% /d /s /c command line. Follows the MSVCRT /
- * CommandLineToArgvW rules (backslashes before a quote or the closing quote are
- * doubled, quotes become \") and rejects cmd metacharacters instead of trying
- * to escape them. The command after `--` is never concatenated unquoted.
- */
-function quoteCmdArg(token) {
-  const value = String(token ?? "");
-  if (value.length === 0) return '""';
-  if (CMD_METACHAR_RE.test(value)) {
-    throw new Error(`cannot quote safely for cmd.exe (shell metacharacter present): ${JSON.stringify(value)}`);
-  }
-  const escaped = value.replace(/(\\*)"/g, "$1$1\\\"").replace(/(\\+)$/, "$1$1");
-  return `"${escaped}"`;
-}
+// quoteCmdArg/CMD_METACHAR_RE live in restart-protocol.js: the Web plugin needs
+// the same strict quoting to build the `cmd /c start` line for a visible
+// restart, so the rules must never drift between the two call sites.
 
 /** Case-insensitive env lookup (Windows env keys are case-insensitive). */
 function envValue(name) {
@@ -674,9 +673,12 @@ const delay = (ms) => new Promise((resolvePromise) => { setTimeout(resolvePromis
  * and named itself. It can still be recycled in principle; the bounded wait
  * and the refusal on timeout keep that from turning into a hang.
  *
- * @returns true when the process is gone, false on timeout.
+ * `shouldAbort` (the Ctrl+C watcher's flag) cuts the wait short: the caller
+ * reads it and refuses the launch instead of outwaiting a cancelled restart.
+ *
+ * @returns true when the process is gone, false on timeout or abort.
  */
-async function waitForProcessExit(pid, timeoutMs, pollMs = 100) {
+async function waitForProcessExit(pid, timeoutMs, pollMs = 100, shouldAbort = undefined) {
   const target = Number(pid);
   if (!Number.isInteger(target) || target <= 0) return true; // nothing to wait for
   const deadline = Date.now() + timeoutMs;
@@ -687,6 +689,7 @@ async function waitForProcessExit(pid, timeoutMs, pollMs = 100) {
       if (error?.code === "ESRCH") return true;
       if (error?.code !== "EPERM") return true; // unprobeable: do not block the restart on it
     }
+    if (shouldAbort !== undefined && shouldAbort()) return false;
     if (Date.now() >= deadline) return false;
     await delay(pollMs);
   }
@@ -744,6 +747,283 @@ function forwardSignals(child) {
   };
 }
 
+// ── tee runner (visible-console restart) ─────────────────────────────────────
+
+/**
+ * The tee pipes the child's stdout away from the console, so color/TTY
+ * detection inside dsh would dim itself. Nudge it back unless the user opted
+ * out with NO_COLOR.
+ */
+function teeEnv(base) {
+  if (base.NO_COLOR !== undefined) return base;
+  return { ...base, FORCE_COLOR: "1" };
+}
+
+/**
+ * The visible-console spawn: stdout/stderr are piped to the tee runner, and
+ * stdin is deliberately NOT the console. A live test showed why: dsh (or a
+ * component inside it) calls setRawMode on an inherited TTY stdin, and raw
+ * mode clears ENABLE_PROCESSED_INPUT console-wide — from then on a real
+ * Ctrl+C never becomes a CTRL_C_EVENT and NOTHING on the console (guard
+ * included) can receive it. With stdin ignored, no TTY ever reaches the
+ * child, processed input stays on, and Ctrl+C reaches every attached process
+ * — which is how the guard's interrupt handling works at all. The wrapped
+ * command is a web host; it has no use for window stdin.
+ */
+function spawnTeeCommand(command, args, { cwd }) {
+  const resolved = process.platform === "win32" ? resolveWindowsCommand(command) : command;
+  // Mark the chain: the wrapped dsh has a PIPE for stdout (the tee), so the
+  // "interactive terminal" signal is gone even though it lives in a console
+  // window. The env flag lets its own restarts stay visible.
+  const env = { ...teeEnv(process.env), DSH_PLUGIN_MALL_VISIBLE_CONSOLE: "1" };
+  const stdio = ["ignore", "pipe", "pipe"];
+  if (process.platform === "win32" && /\.(?:cmd|bat)$/i.test(resolved)) {
+    const comspec = process.env.ComSpec ?? "cmd.exe";
+    const line = [resolved, ...args].map(quoteCmdArg).join(" ");
+    return spawn(comspec, ["/d", "/s", "/c", `"${line}"`], { shell: false, stdio, cwd, env, windowsVerbatimArguments: true, windowsHide: false });
+  }
+  return spawn(resolved, args, { shell: false, stdio, cwd, env, windowsHide: false });
+}
+
+function defaultOpenTeeLog(logPath) {
+  mkdirSync(dirname(logPath), { recursive: true });
+  return createWriteStream(logPath, { flags: "a" });
+}
+
+/**
+ * Tee runner for the visible-console restart: everything the wrapped command
+ * prints is mirrored to BOTH this guard's console (the window `cmd /c start`
+ * allocated) and the restart log. A log that cannot be opened, or that fails
+ * mid-run, only costs the log — the window keeps showing output and the
+ * child's exit code is untouched.
+ *
+ * Backpressure: while EITHER target is saturated BOTH source pipes stay
+ * paused (pausing just one would leave the other free to keep filling the
+ * saturated target); each target resumes the pair once it drains.
+ */
+function createTeeRunner({ logPath, cwd, _stdout = process.stdout, _openLog = defaultOpenTeeLog }) {
+  let logStream;
+  let broken = false;
+  try {
+    logStream = _openLog(logPath);
+  } catch (error) {
+    broken = true;
+    _stdout.write(`[guard] warning: cannot open restart log ${logPath} (${error.message}) — continuing without it\n`);
+  }
+  let consoleSaturated = false;
+  let logSaturated = false;
+  let paused = false;
+  const activeStreams = new Set();
+  const onConsoleDrain = () => { consoleSaturated = false; maybeResume(); };
+  const onLogDrain = () => { logSaturated = false; maybeResume(); };
+  _stdout.on("drain", onConsoleDrain);
+  if (logStream !== undefined) {
+    logStream.on("drain", onLogDrain);
+    logStream.on("error", (error) => {
+      if (broken) return;
+      broken = true;
+      _stdout.write(`[guard] warning: restart log ${logPath} failed (${error.message}) — continuing without it\n`);
+      // A failed stream never drains. Clear the log-side backpressure or the
+      // paused source pipes stay paused forever and the wrapped dsh hangs.
+      logSaturated = false;
+      maybeResume();
+    });
+  }
+  function maybeResume() {
+    if (!paused || consoleSaturated || logSaturated) return;
+    paused = false;
+    for (const stream of activeStreams) stream.resume();
+  }
+  function onData(chunk) {
+    const consoleOk = _stdout.write(chunk);
+    const logOk = broken || logStream === undefined ? true : logStream.write(chunk);
+    if (consoleOk && logOk) return;
+    if (!consoleOk) consoleSaturated = true;
+    if (!logOk) logSaturated = true;
+    if (!paused) {
+      paused = true;
+      for (const stream of activeStreams) stream.pause();
+    }
+  }
+  let closed = false;
+  return {
+    get broken() { return broken; },
+    spawn(command, args) { return spawnTeeCommand(command, args, { cwd }); },
+    attach(child) {
+      const streams = [child.stdout, child.stderr].filter((stream) => stream !== null && stream !== undefined);
+      for (const stream of streams) {
+        activeStreams.add(stream);
+        stream.on("data", onData);
+      }
+      return () => {
+        for (const stream of streams) {
+          stream.removeListener("data", onData);
+          activeStreams.delete(stream);
+        }
+        maybeResume();
+      };
+    },
+    // tee waits for `close`, not `exit`: the pipes still carry in-flight
+    // output after exit, and ending the log before they drain would lose it.
+    waitFor(child) {
+      return new Promise((resolvePromise) => {
+        child.once("error", (error) => resolvePromise({ error }));
+        child.once("close", (code, signal) => resolvePromise({ code, signal }));
+      });
+    },
+    // Guard's own [guard] lines share the same two targets. The classic IO
+    // path routes by level (stdout/stderr); in a console window both land on
+    // the same screen, so the tee keeps a single stream.
+    say(text) {
+      const line = `${text}\n`;
+      _stdout.write(line);
+      if (!broken && logStream !== undefined) logStream.write(line);
+    },
+    async close() {
+      if (closed) return;
+      closed = true;
+      _stdout.removeListener("drain", onConsoleDrain);
+      if (logStream === undefined) return;
+      logStream.removeListener("drain", onLogDrain);
+      await new Promise((resolvePromise) => {
+        try {
+          logStream.end(() => resolvePromise());
+        } catch {
+          resolvePromise();
+        }
+      });
+    },
+  };
+}
+
+/** The launch IO every run shares: spawn, attach signals, wait for exit. */
+const classicIO = {
+  spawn: spawnCommand,
+  attach: (child) => forwardSignals(child),
+  waitFor: waitForExit,
+  say: (text, level) => { console[level === "error" ? "error" : "log"](text); },
+};
+
+// ── console Ctrl handling (visible restart, Windows) ─────────────────────────
+
+// NTSTATUS 0xC000013A: how a console process exits when it honored
+// CTRL_C_EVENT. Depending on the libuv version Node reports it as exit code
+// or maps it to SIGINT — both spellings are honored below.
+const STATUS_CONTROL_C_EXIT = 3221225786;
+
+/**
+ * Tear down the whole process TREE of a wrapped command that ignored its
+ * Ctrl+C. TerminateProcess (child.kill) does not cascade: dsh's graceful
+ * shutdown can hang on in-flight jobs, and even a killed dsh leaves its
+ * grandchildren (pnpm, job subprocesses) as orphans still attached to the
+ * console — which is exactly the "window will not close" a user sees after
+ * pressing Ctrl+C. taskkill /T /F tears the tree down in one step, the same
+ * escalation the official dsh-subprocess-local applies for console-wide
+ * teardown. The pid is always our own child's integer pid, never a string.
+ */
+function defaultKillProcessTree(pid) {
+  if (process.platform !== "win32") {
+    try { process.kill(pid, "SIGKILL"); } catch { /* already gone */ }
+    return;
+  }
+  const killer = spawn(process.env.ComSpec ?? "cmd.exe", ["/d", "/s", "/c", `taskkill /PID ${pid} /T /F >nul 2>&1`], { shell: false, stdio: "ignore", windowsHide: true });
+  killer.once("error", () => {
+    try { process.kill(pid); } catch { /* already gone */ }
+  });
+}
+
+/**
+ * Ctrl+C on a console reaches every attached process: the wrapped dsh gets
+ * the event directly. This watcher's job is only on the GUARD's side —
+ *
+ *  - keep it alive (a Node process without a SIGINT handler exits at once,
+ *    orphaning nothing but losing the log flush and the exit-code report);
+ *  - remember the run was interrupted. On Windows a killed child reports
+ *    code 1 / no signal, which probation would otherwise read as "the
+ *    pending install crashed dsh" and roll back a perfectly good install;
+ *  - escalate: if the child has not quit on its own within forceGraceMs,
+ *    terminate the whole tree so the listening port is released AND the
+ *    console window can actually close; a second Ctrl+C escalates at once;
+ *  - SIGHUP (the window's close button): the OS is about to kill the whole
+ *    console unconditionally — hold the handler open only so the normal
+ *    cleanup path (log close) can finish before that lands.
+ */
+function createInterruptWatcher({ forceGraceMs = 5000, _killTree = defaultKillProcessTree } = {}) {
+  let interrupted = false;
+  let child;
+  let forceTimer;
+  const abortListeners = new Set();
+  const terminate = () => {
+    if (child === undefined) return;
+    try {
+      _killTree(child.pid);
+    } catch {
+      try { child.kill(); } catch { /* already gone */ }
+    }
+  };
+  const signal = () => {
+    for (const listener of abortListeners) {
+      try { listener(); } catch { /* best effort */ }
+    }
+    if (interrupted) {
+      terminate();
+      return;
+    }
+    interrupted = true;
+    if (child !== undefined) armForceKill();
+  };
+  function armForceKill() {
+    if (forceTimer !== undefined || child === undefined) return;
+    forceTimer = setTimeout(terminate, forceGraceMs);
+    if (typeof forceTimer.unref === "function") forceTimer.unref();
+  }
+  const onHup = () => { /* see the doc comment: let cleanup run, OS decides */ };
+  process.on("SIGINT", signal);
+  process.on("SIGBREAK", signal);
+  process.on("SIGHUP", onHup);
+  return {
+    interrupted: () => interrupted,
+    noteChild(nextChild) {
+      child = nextChild;
+      if (interrupted) armForceKill(); // defensive: a spawn after a cancel
+    },
+    onAbort(listener) { abortListeners.add(listener); },
+    offAbort(listener) { abortListeners.delete(listener); },
+    unlisten() {
+      process.removeListener("SIGINT", signal);
+      process.removeListener("SIGBREAK", signal);
+      process.removeListener("SIGHUP", onHup);
+      if (forceTimer !== undefined) clearTimeout(forceTimer);
+    },
+  };
+}
+
+/** Sleep for inspection pauses; any further Ctrl+C (via the watcher) ends it. */
+function waitForSignalOrTimeout(ms, watcher) {
+  return new Promise((resolvePromise) => {
+    const timer = setTimeout(finish, ms);
+    const onAbort = () => { finish(); };
+    function finish() {
+      clearTimeout(timer);
+      if (watcher !== undefined) watcher.offAbort(onAbort);
+      resolvePromise();
+    }
+    if (watcher !== undefined) watcher.onAbort(onAbort);
+  });
+}
+
+/**
+ * Was the wrapped command interrupted from outside rather than crashed?
+ * POSIX says SIGINT/SIGTERM; Windows says "killed" (code 1, no signal) or
+ * STATUS_CONTROL_C_EXIT — there the watcher's flag is the reliable spelling
+ * and the NTSTATUS is belt-and-braces.
+ */
+function isInterruptedOutcome(outcome, watcher) {
+  if (outcome.signal === "SIGINT" || outcome.signal === "SIGTERM") return true;
+  if (outcome.code === STATUS_CONTROL_C_EXIT) return true;
+  return watcher !== undefined && watcher.interrupted();
+}
+
 function waitForExit(child) {
   return new Promise((resolvePromise) => {
     child.on("error", (error) => resolvePromise({ error }));
@@ -759,15 +1039,26 @@ function exitCodeOf(result) {
   return 1;
 }
 
-/** Run the command once with no probation; resolve with its exit result. */
-async function runPlain(command, args) {
-  const child = spawnCommand(command, args);
-  const unforward = forwardSignals(child);
-  const result = await waitForExit(child);
-  unforward();
+/**
+ * Run the wrapped command once and resolve with its exit result. Every launch
+ * mode routes through here — the plain terminal, the detached background
+ * restart, and the tee'd visible console — so probation's rollback-and-restart
+ * keeps whatever IO the launch started with (the retried dsh must be teed
+ * exactly like the first one).
+ */
+async function runCommand(command, args, io = classicIO) {
+  const child = io.spawn(command, args);
+  const cleanup = io.attach(child);
+  const result = await io.waitFor(child);
+  if (typeof cleanup === "function") await cleanup();
   return result;
 }
 
+/** Run the command once with no probation; resolve with its exit result. */
+async function runPlain(command, args, io = classicIO) {
+  return runCommand(command, args, io);
+}
+
 /**
  * Commit the pending snapshot once startup probation passes. A commit failure
  * is a warning, not a launch failure — the process is already running and
@@ -778,7 +1069,7 @@ async function runPlain(command, args) {
  * Roll it back to the pre-install snapshot instead (a rollback failure keeps
  * the marker for the next attempt, same as recoverProfile).
  */
-function commitLaunchSnapshot(profileDir) {
+function commitLaunchSnapshot(profileDir, say = (text, level) => { console[level === "error" ? "error" : "log"](text); }) {
   try {
     let pending;
     try {
@@ -788,13 +1079,13 @@ function commitLaunchSnapshot(profileDir) {
     }
     if (pending !== undefined && pendingApprovalPaused(pending) !== undefined) {
       rollbackPendingSnapshot(profileDir);
-      console.log(`[guard] startup probation passed, but the install was abandoned at the approval gate — profile rolled back for ${profileDir}`);
+      say(`[guard] startup probation passed, but the install was abandoned at the approval gate — profile rolled back for ${profileDir}`);
       return;
     }
     commitPendingSnapshot(profileDir);
-    console.log(`[guard] startup probation passed — pending snapshot committed for ${profileDir}`);
+    say(`[guard] startup probation passed — pending snapshot committed for ${profileDir}`);
   } catch (error) {
-    console.error(`[guard] warning: could not commit the pending snapshot for ${profileDir}: ${error.message} — the marker stays pending`);
+    say(`[guard] warning: could not commit the pending snapshot for ${profileDir}: ${error.message} — the marker stays pending`, "error");
   }
 }
 
@@ -804,10 +1095,10 @@ function commitLaunchSnapshot(profileDir) {
  * means it stayed alive through it (the snapshot is committed at that point)
  * and the wrapper kept waiting for it.
  */
-async function runProbation({ profileDir, command, args, graceMs }) {
-  const child = spawnCommand(command, args);
-  const unforward = forwardSignals(child);
-  const exited = waitForExit(child);
+async function runProbation({ profileDir, command, args, graceMs, io = classicIO }) {
+  const child = io.spawn(command, args);
+  const cleanup = io.attach(child);
+  const exited = io.waitFor(child);
   let timer;
   const grace = new Promise((resolvePromise) => { timer = setTimeout(() => resolvePromise("grace"), graceMs); });
   const first = await Promise.race([
@@ -816,12 +1107,12 @@ async function runProbation({ profileDir, command, args, graceMs }) {
   ]);
   clearTimeout(timer);
   if (first.phase === "before-grace") {
-    unforward();
+    if (typeof cleanup === "function") await cleanup();
     return first;
   }
-  commitLaunchSnapshot(profileDir);
+  commitLaunchSnapshot(profileDir, io.say);
   const result = await exited;
-  unforward();
+  if (typeof cleanup === "function") await cleanup();
   return { phase: "after-grace", ...result };
 }
 
@@ -889,6 +1180,60 @@ function markerLooksValid(marker, profileDir, home) {
   return true;
 }
 
+/**
+ * Read and validate a restart plan file, then consume it. The plan is the
+ * visible-restart launch source: `cmd /c start` cannot carry the wrapped
+ * argv, so the Web Host writes it to a nonce-named JSON file and this CLI
+ * reads it back — never through a shell string. A plan that fails validation
+ * (or does not parse) is refused and LEFT ON DISK for diagnosis; only a
+ * successfully loaded plan is deleted. Residue is inert: the file name is
+ * unique per request.
+ */
+function loadRestartPlan(planFile) {
+  let raw;
+  try {
+    raw = readFileSync(planFile, "utf8");
+  } catch (error) {
+    throw new Error(`cannot read restart plan ${planFile}: ${error.message}`);
+  }
+  let value;
+  try {
+    value = JSON.parse(raw);
+  } catch (error) {
+    throw new Error(`restart plan ${planFile} is not valid JSON (${error.message}) — file left for inspection`);
+  }
+  const verdict = validateRestartPlanPayload(value);
+  if (!verdict.ok) {
+    throw new Error(`${verdict.error} — in ${planFile} (file left for inspection)`);
+  }
+  try { unlinkSync(planFile); } catch { /* nonce-named residue is inert */ }
+  return verdict.plan;
+}
+
+/**
+ * Resolve what `guard launch` should run from the parsed CLI. Two exclusive
+ * sources: the classic `--profile … -- command argv` form, or a `--plan-file`
+ * that carries all three. Anything overlapping the plan form is a usage error
+ * — two sources for the same fact is how they drift apart.
+ */
+function resolveLaunchInvocation(parsed) {
+  if (parsed.planFile !== undefined) {
+    if (parsed.profile !== undefined || parsed.awaitExit !== undefined || parsed.commandArgv.length !== 0) {
+      throw usageError("--plan-file carries --profile, --await-exit and the wrapped command; do not pass them separately (see --help)");
+    }
+    const plan = loadRestartPlan(parsed.planFile);
+    return { profile: plan.profile, commandArgv: [plan.command, ...plan.args], awaitExitPid: plan.awaitExitPid, plan };
+  }
+  if (parsed.profile === undefined) throw usageError("launch needs --profile <name> (see --help)");
+  if (parsed.commandArgv.length === 0) throw usageError("launch needs a command after `--` (see --help)");
+  let awaitExitPid;
+  if (parsed.awaitExit !== undefined) {
+    awaitExitPid = Number(parsed.awaitExit);
+    if (!Number.isInteger(awaitExitPid) || awaitExitPid <= 0) throw usageError(`--await-exit must be a positive process id, got ${JSON.stringify(parsed.awaitExit)}`);
+  }
+  return { profile: parsed.profile, commandArgv: parsed.commandArgv, awaitExitPid };
+}
+
 /**
  * `guard launch`: start dsh (or any command) wrapped in startup probation for
  * the profile's pending install, if one exists.
@@ -909,12 +1254,31 @@ async function cmdLaunch({
   graceMs,
   commandArgv,
   awaitExitPid,
+  plan,
+  tee,
+  interrupt,
   _waitForExit = waitForProcessExit,
-  _onAwaitExit = announceRestartHelperReady,
+  _onAwaitExit = plan === undefined ? announceRestartHelperReady : (pid) => announceRestartHandoffViaFile(plan, pid),
 }) {
   const profileDir = profileDirOf(home, profile);
   const grace = graceMs ?? DEFAULT_GRACE_MS;
   const [command, ...args] = commandArgv;
+  // The visible-console launch passes its tee runner: spawns pipe through it,
+  // [guard] lines are mirrored to the window and the log, and probation's
+  // retry-once reuses the same tee. The classic launch keeps classicIO — its
+  // console.log/console.error split (stdout vs stderr) is unchanged behavior.
+  const io = tee ?? classicIO;
+  const say = io.say;
+  // The Ctrl watcher needs to know the live child (second Ctrl+C escalates
+  // to a kill) — wrap attach so every spawn, probation's retry included,
+  // registers it.
+  const watchedIO = interrupt === undefined ? io : {
+    ...io,
+    attach(child) {
+      interrupt.noteChild(child);
+      return io.attach(child);
+    },
+  };
 
   // A restart hands us the pid of the host that is on its way out. Starting
   // the successor while it still holds the listening port is not a race worth
@@ -928,12 +1292,30 @@ async function cmdLaunch({
   if (awaitExitPid !== undefined) {
     // This is the exact handoff boundary: arguments and profile are valid, and
     // the helper is about to block on the outgoing Host. The Web parent waits
-    // for this IPC acknowledgement before it allows itself to exit.
+    // for this acknowledgement — over IPC on the background path, or through
+    // the ready file on the visible-console path — before it allows itself to
+    // exit. A failed announcement rejects here and nothing starts.
+    if (tee !== undefined) tee.say(`[guard] waiting for outgoing dsh (pid ${awaitExitPid}) to exit — close this window to cancel…`);
     await _onAwaitExit(awaitExitPid);
-    if (!await _waitForExit(awaitExitPid, AWAIT_EXIT_TIMEOUT_MS)) {
+    const gone = await _waitForExit(awaitExitPid, AWAIT_EXIT_TIMEOUT_MS, 100, interrupt === undefined ? undefined : interrupt.interrupted);
+    if (!gone) {
+      if (interrupt !== undefined && interrupt.interrupted()) {
+        throw new Error(`interrupted while waiting for the outgoing dsh (pid ${awaitExitPid}) — no successor was started`);
+      }
       throw new Error(`process ${awaitExitPid} was still running after ${AWAIT_EXIT_TIMEOUT_MS}ms — refusing to start a second host that would collide with it on the listening port (the old one is still up; nothing was changed)`);
     }
     await delay(PORT_SETTLE_MS);
+    // Cancel sentinel: the Web parent cannot kill this guard (cmd /c start
+    // hid the pid), so on a handoff it gave up waiting for it drops
+    // <readyFile>.cancel. A slow guard waking up here must not start a second
+    // successor next to the retry's one — that port collision is exactly what
+    // probation would misread as a bad install. The sweep never touches a
+    // fresh sentinel (it may belong to a guard that has not woken yet);
+    // consuming it here deletes it so it does not linger.
+    if (plan !== undefined && existsSync(`${plan.readyFile}.cancel`)) {
+      try { unlinkSync(`${plan.readyFile}.cancel`); } catch { /* best effort */ }
+      throw new Error("this restart was cancelled by the Web parent (the handoff timed out) — not starting a successor");
+    }
   }
   // Mirrors guard.js pendingPath(): <home>/guard/pending-<profile>.json.
   const markerPath = join(home, "guard", `pending-${profile}.json`);
@@ -946,7 +1328,7 @@ async function cmdLaunch({
     }
     let validation;
     try {
-      validation = validateInstalledProfile(profileDir);
+      validation = validatePendingProfile(profileDir, marker);
     } catch (error) {
       throw new Error(`static validation of profile "${profile}" failed — refusing to launch: ${error.message}`);
     }
@@ -961,29 +1343,32 @@ async function cmdLaunch({
       } catch (error) {
         throw new Error(`profile "${profile}" failed static validation and rollback failed — refusing to launch: ${error.message}`);
       }
-      console.error(`[guard] profile "${profile}" failed static validation — rolled back before launch:`);
-      for (const entry of [...validation.issues, ...removeValidation.issues]) console.error(renderIssue(entry));
+      say(`[guard] profile "${profile}" failed static validation — rolled back before launch:`, "error");
+      for (const entry of [...validation.issues, ...removeValidation.issues]) say(renderIssue(entry), "error");
     } else {
       pending = true;
     }
   }
 
   if (!pending) {
-    const result = await runPlain(command, args);
-    if (result.error !== undefined) console.error(`[guard] failed to start ${command}: ${result.error.message}`);
+    const result = await runPlain(command, args, watchedIO);
+    if (result.error !== undefined) say(`[guard] failed to start ${command}: ${result.error.message}`, "error");
+    if (isInterruptedOutcome(result, interrupt)) return result.signal === "SIGTERM" ? 143 : 130;
     return exitCodeOf(result);
   }
 
-  const outcome = await runProbation({ profileDir, command, args, graceMs: grace });
+  const outcome = await runProbation({ profileDir, command, args, graceMs: grace, io: watchedIO });
   if (outcome.phase === "after-grace") return exitCodeOf(outcome);
-  if (outcome.signal === "SIGINT" || outcome.signal === "SIGTERM") {
-    // Interrupted from outside (Ctrl+C / service stop): not an install failure —
-    // leave the marker pending for the next launch, propagate the convention.
-    return exitCodeOf(outcome);
+  if (isInterruptedOutcome(outcome, interrupt)) {
+    // Interrupted from outside (Ctrl+C / service stop): not an install
+    // failure — leave the marker pending for the next launch and keep the
+    // 130/143 convention. This check precedes the exit-0 commit on purpose:
+    // a dsh that exits 0 after a Ctrl+C has proven nothing about loading.
+    return outcome.signal === "SIGTERM" ? 143 : 130;
   }
   if (outcome.error === undefined && outcome.code === 0) {
     // One-shot command that finished successfully inside the grace window.
-    commitLaunchSnapshot(profileDir);
+    commitLaunchSnapshot(profileDir, say);
     return 0;
   }
 
@@ -998,9 +1383,10 @@ async function cmdLaunch({
   } catch (error) {
     throw new Error(`the command ${why} within the grace period, but rollback failed — refusing to restart: ${error.message}`);
   }
-  console.error(`[guard] the command ${why} within the ${grace}ms grace period — profile "${profile}" rolled back, restarting once with the restored state`);
-  const retry = await runPlain(command, args);
-  if (retry.error !== undefined) console.error(`[guard] failed to restart ${command}: ${retry.error.message}`);
+  say(`[guard] the command ${why} within the ${grace}ms grace period — profile "${profile}" rolled back, restarting once with the restored state`, "error");
+  const retry = await runPlain(command, args, watchedIO);
+  if (retry.error !== undefined) say(`[guard] failed to restart ${command}: ${retry.error.message}`, "error");
+  if (isInterruptedOutcome(retry, interrupt)) return retry.signal === "SIGTERM" ? 143 : 130;
   return exitCodeOf(retry);
 }
 
@@ -1016,6 +1402,7 @@ Usage:
   node src/cli.js guard add <spec> --profile <name> [--home <dir>] [--accept-warnings]
   node src/cli.js guard remove <package> --profile <name> [--home <dir>]
   node src/cli.js guard launch --profile <name> [--home <dir>] [--grace-ms <ms>] [--await-exit <pid>] -- <command> [args...]
+  node src/cli.js guard launch --plan-file <path> [--home <dir>] [--grace-ms <ms>]
   node src/cli.js guard self-test
 
 Commands:
@@ -1043,7 +1430,11 @@ Commands:
               period rolls the profile back and restarts the exact command once
               with the restored state (never loops). A corrupt or legacy (pre-v2)
               marker fails closed: the command is not launched and nothing is
-              deleted.
+              deleted. --plan-file loads the wrapped command from a restart
+              plan JSON instead of \`--\` (it carries --profile, --await-exit
+              and the command itself; passing those alongside is a usage
+              error) and is consumed on load — an invalid plan is refused and
+              left on disk for inspection.
   self-test   run offline fixtures (no network, no pnpm/dsh).
 
 Exit codes: 0 ok, 1 blocked/rolled back/failed, 2 usage error; launch preserves
@@ -1056,7 +1447,7 @@ function parseArgs(argv) {
   if (args[0] === "guard") args.shift(); // `node cli.js guard recover` / `node cli.js recover`
   let command = args.shift() ?? "help";
   if (command === "--help" || command === "-h") command = "help"; // `cli.js --help`
-  const opts = { home: undefined, profile: undefined, graceMs: undefined, awaitExit: undefined, acceptWarnings: false, positionals: [], commandArgv: [] };
+  const opts = { home: undefined, profile: undefined, graceMs: undefined, awaitExit: undefined, planFile: undefined, acceptWarnings: false, positionals: [], commandArgv: [] };
   for (let index = 0; index < args.length; index++) {
     const arg = args[index];
     if (arg === "--") { opts.commandArgv = args.slice(index + 1); break; } // launch: the wrapped command, verbatim
@@ -1070,6 +1461,8 @@ function parseArgs(argv) {
     if (arg.startsWith("--grace-ms=")) { opts.graceMs = arg.slice("--grace-ms=".length); continue; }
     if (arg === "--await-exit") { opts.awaitExit = args[++index]; continue; }
     if (arg.startsWith("--await-exit=")) { opts.awaitExit = arg.slice("--await-exit=".length); continue; }
+    if (arg === "--plan-file") { opts.planFile = args[++index]; continue; }
+    if (arg.startsWith("--plan-file=")) { opts.planFile = arg.slice("--plan-file=".length); continue; }
     if (arg === "--all") { opts.all = true; continue; }
     if (arg.startsWith("-")) throw new Error(`unknown option ${JSON.stringify(arg)}`);
     opts.positionals.push(arg);
@@ -1094,6 +1487,13 @@ async function main(argv) {
     return;
   }
   const home = parsed.home !== undefined ? resolve(parsed.home) : resolveDshHome();
+  // The visible-restart tee outlives cmdLaunch: main's catch can still write
+  // the failure into the restart log (the window would otherwise flash away)
+  // before the log is closed and flushed. The Ctrl watcher belongs to the
+  // same lifetime — Windows only, so every other platform's signal behavior
+  // stays exactly as it was.
+  let launchTee;
+  let launchInterrupt;
   try {
     switch (parsed.command) {
       case "validate": {
@@ -1133,19 +1533,17 @@ async function main(argv) {
         return;
       }
       case "launch": {
-        if (parsed.profile === undefined) throw usageError("launch needs --profile <name> (see --help)");
-        if (parsed.commandArgv.length === 0) throw usageError("launch needs a command after `--` (see --help)");
         let graceMs;
         if (parsed.graceMs !== undefined) {
           graceMs = Number(parsed.graceMs);
           if (!Number.isFinite(graceMs) || graceMs < 0) throw usageError(`--grace-ms must be a non-negative number, got ${JSON.stringify(parsed.graceMs)}`);
         }
-        let awaitExitPid;
-        if (parsed.awaitExit !== undefined) {
-          awaitExitPid = Number(parsed.awaitExit);
-          if (!Number.isInteger(awaitExitPid) || awaitExitPid <= 0) throw usageError(`--await-exit must be a positive process id, got ${JSON.stringify(parsed.awaitExit)}`);
+        const invocation = resolveLaunchInvocation(parsed);
+        if (invocation.plan !== undefined) {
+          launchTee = createTeeRunner({ logPath: invocation.plan.logPath, cwd: invocation.plan.cwd });
+          if (process.platform === "win32") launchInterrupt = createInterruptWatcher();
         }
-        process.exitCode = await cmdLaunch({ profile: parsed.profile, home, graceMs, commandArgv: parsed.commandArgv, awaitExitPid });
+        process.exitCode = await cmdLaunch({ ...invocation, home, graceMs, tee: launchTee, interrupt: launchInterrupt });
         return;
       }
       case "self-test": {
@@ -1156,8 +1554,19 @@ async function main(argv) {
         throw usageError(`unknown command ${JSON.stringify(parsed.command)} (see --help)`);
     }
   } catch (error) {
+    if (launchTee !== undefined) launchTee.say(`error: ${error.message}`, "error");
     console.error(`error: ${error.message}`);
     process.exitCode = error instanceof UsageError ? 2 : 1;
+    // A visible window that vanishes takes its diagnosis with it: hold it
+    // briefly so the error can be read (a working console signal cuts the
+    // wait short).
+    if (launchTee !== undefined) {
+      launchTee.say("[guard] this window closes in 10s so the error above can be read…");
+      await waitForSignalOrTimeout(10000, launchInterrupt);
+    }
+  } finally {
+    if (launchInterrupt !== undefined) launchInterrupt.unlisten();
+    if (launchTee !== undefined) await launchTee.close();
   }
 }
 
@@ -1229,6 +1638,88 @@ async function selfTest() {
       }
     }
 
+    // --plan-file: the visible-restart launch source. Parsing accepts both
+    // forms; resolution treats the plan as the single source of truth, drinks
+    // it on load, and refuses to mix it with --profile/--await-exit/`--`.
+    {
+      const p7 = parseArgs(["launch", "--plan-file", "C:/r/plan.json"]);
+      if (p7.planFile !== "C:/r/plan.json") throw new Error("parseArgs --plan-file fixture failed");
+      const p8 = parseArgs(["launch", "--plan-file=C:/r/plan.json"]);
+      if (p8.planFile !== "C:/r/plan.json") throw new Error("parseArgs --plan-file= fixture failed");
+
+      const planDir = join(root, "restart-plans");
+      mkdirSync(planDir, { recursive: true });
+      const writePlan = (name, overrides = {}) => {
+        const path = join(planDir, name);
+        writeFileSync(path, JSON.stringify({
+          version: 1,
+          type: RESTART_PLAN_TYPE,
+          profile: "web",
+          awaitExitPid: 4321,
+          logPath: join(planDir, "restart-web.log"),
+          readyFile: join(planDir, "ready.json"),
+          cwd: root,
+          command: process.execPath,
+          args: ["-e", "process.exit(0)"],
+          ...overrides,
+        }));
+        return path;
+      };
+
+      const goodPath = writePlan("good.json");
+      const invocation = resolveLaunchInvocation({ planFile: goodPath, commandArgv: [] });
+      if (invocation.profile !== "web" || invocation.awaitExitPid !== 4321) throw new Error("plan invocation must carry the plan's profile and pid");
+      if (invocation.commandArgv[0] !== process.execPath || invocation.commandArgv[2] !== "process.exit(0)") throw new Error("plan invocation must derive the wrapped command from the plan");
+      if (existsSync(goodPath)) throw new Error("a successfully loaded plan must be consumed (deleted)");
+
+      for (const [name, overrides] of [["bad-args.json", { args: [] }], ["bad-version.json", { version: 2 }]]) {
+        const badPath = writePlan(name, overrides);
+        let refused = false;
+        try {
+          resolveLaunchInvocation({ planFile: badPath, commandArgv: [] });
+        } catch (error) {
+          refused = !(error instanceof UsageError) && /restart plan/.test(error.message);
+        }
+        if (!refused) throw new Error(`an invalid plan (${name}) must fail closed`);
+        if (!existsSync(badPath)) throw new Error(`an invalid plan (${name}) must be left on disk for inspection`);
+      }
+      const notJsonPath = join(planDir, "not-json.json");
+      writeFileSync(notJsonPath, "{ half-written");
+      let notJsonRefused = false;
+      try {
+        resolveLaunchInvocation({ planFile: notJsonPath, commandArgv: [] });
+      } catch (error) {
+        notJsonRefused = /not valid JSON/.test(error.message);
+      }
+      if (!notJsonRefused || !existsSync(notJsonPath)) throw new Error("unparseable plan JSON must be refused and preserved");
+      let missingRefused = false;
+      try {
+        resolveLaunchInvocation({ planFile: join(planDir, "nope.json"), commandArgv: [] });
+      } catch (error) {
+        missingRefused = /cannot read restart plan/.test(error.message);
+      }
+      if (!missingRefused) throw new Error("a missing plan file must fail with a clear error");
+
+      for (const extra of [{ profile: "web" }, { awaitExit: "4321" }, { commandArgv: ["dsh"] }]) {
+        let usageErrorSeen = false;
+        try {
+          resolveLaunchInvocation({ planFile: writePlan("exclusive.json"), commandArgv: [], ...extra });
+        } catch (error) {
+          usageErrorSeen = error instanceof UsageError;
+        }
+        if (!usageErrorSeen) throw new Error(`--plan-file with ${JSON.stringify(Object.keys(extra))} must be a usage error`);
+      }
+      const classic = resolveLaunchInvocation({ profile: "web", commandArgv: ["dsh"], awaitExit: undefined, planFile: undefined });
+      if (classic.profile !== "web" || classic.commandArgv.join(" ") !== "dsh" || classic.plan !== undefined) throw new Error("the classic launch form must resolve unchanged");
+      let classicUsage = false;
+      try {
+        resolveLaunchInvocation({ profile: undefined, commandArgv: [], awaitExit: undefined, planFile: undefined });
+      } catch (error) {
+        classicUsage = error instanceof UsageError;
+      }
+      if (!classicUsage) throw new Error("classic launch without --profile must stay a usage error");
+    }
+
     // `--await-exit`: the successor must not start while the outgoing host is
     // still holding the port. A pid that never goes away is refused outright —
     // starting anyway is what costs the user their install, because the failed
@@ -1278,6 +1769,85 @@ async function selfTest() {
       if (!await waitForProcessExit(undefined, 500, 20)) throw new Error("waitForProcessExit must not block on a missing pid");
     }
 
+    // --plan-file launch mode: the handoff announcement moves to the ready
+    // file (there is no IPC channel under `cmd /c start`) while everything
+    // else — waiting for the outgoing pid, running the wrapped command —
+    // behaves exactly like the classic form. An announcement that cannot be
+    // written must reject the launch: the Web parent would otherwise time out
+    // blind while no successor ever started.
+    {
+      const p = join(root, "profiles", "plan-launch");
+      mkdirSync(p, { recursive: true });
+      writeFileSync(join(p, "package.json"), JSON.stringify({ dependencies: {} }));
+      writeFileSync(join(p, "cordis.patch.yml"), "[]\n");
+      const planDir = join(root, "restart-plans-live");
+      mkdirSync(planDir, { recursive: true });
+      const readyOut = join(planDir, "ready-out.json");
+      const plan = {
+        version: 1,
+        type: RESTART_PLAN_TYPE,
+        profile: "plan-launch",
+        awaitExitPid: 8642,
+        logPath: join(planDir, "restart-plan-launch.log"),
+        readyFile: readyOut,
+        cwd: root,
+        command: process.execPath,
+        args: ["-e", "process.exit(0)"],
+      };
+      const code = await cmdLaunch({
+        profile: plan.profile,
+        home: root,
+        commandArgv: [plan.command, ...plan.args],
+        awaitExitPid: plan.awaitExitPid,
+        plan,
+        _waitForExit: async () => true,
+      });
+      if (code !== 0) throw new Error("a plan-file launch must run the wrapped command");
+      if (!existsSync(readyOut)) throw new Error("plan-file launch must publish the ready file before waiting");
+      const readyPayload = JSON.parse(readFileSync(readyOut, "utf8"));
+      if (readyPayload.type !== "@1e0zj/dsh-plugin-mall:restart-helper-ready"
+        || readyPayload.protocol !== 1 || readyPayload.awaitExitPid !== plan.awaitExitPid
+        || readyPayload.guardPid !== process.pid) {
+        throw new Error("the ready file must carry the helper-ready message with this guard's pid");
+      }
+
+      const badPlan = { ...plan, readyFile: join(planDir, "no-such-dir", "ready.json") };
+      let announceFailed = false;
+      try {
+        await cmdLaunch({
+          profile: badPlan.profile,
+          home: root,
+          commandArgv: [badPlan.command, ...badPlan.args],
+          awaitExitPid: badPlan.awaitExitPid,
+          plan: badPlan,
+          _waitForExit: async () => true,
+        });
+      } catch {
+        announceFailed = true;
+      }
+      if (!announceFailed) throw new Error("a ready-file write failure must reject the launch (fail closed)");
+
+      // Cancel sentinel: a guard the Web parent gave up on must not start a
+      // successor after its await-exit wait ends — the retry's guard will.
+      // Consuming the sentinel deletes it, so it does not linger.
+      writeFileSync(`${readyOut}.cancel`, "cancelled (fixture)\n");
+      let cancelled = false;
+      try {
+        await cmdLaunch({
+          profile: plan.profile,
+          home: root,
+          commandArgv: [plan.command, ...plan.args],
+          awaitExitPid: plan.awaitExitPid,
+          plan,
+          _waitForExit: async () => true,
+        });
+      } catch (error) {
+        cancelled = /cancelled by the Web parent/.test(error.message);
+      }
+      if (!cancelled) throw new Error("a cancelled handoff must refuse to start a successor after the wait");
+      if (existsSync(`${readyOut}.cancel`)) throw new Error("consuming the cancel sentinel must delete it");
+    }
+
     // hideChildConsole: inherit the console we have, never create one we do
     // not. Getting this backwards is visible either way — a stray blank window
     // after every restart, or an interactive `guard launch` that has lost its
@@ -1297,6 +1867,296 @@ async function selfTest() {
       }
     }
 
+    // Tee runner (visible restart): the wrapped command's output must reach
+    // BOTH the console target and the log byte-for-byte, the exit code must
+    // pass through, everything must be flushed before close() settles, a
+    // broken log must not change the outcome, and backpressure must not lose
+    // data. Classic IO keeps its exact behavior (existing fixtures above).
+    {
+      const teeDir = join(root, "tee");
+      mkdirSync(teeDir, { recursive: true });
+
+      // Do not call process.exit() after the large write: on Linux that
+      // truncates the CHILD's pipe before the tee can ever read it (the exact
+      // false failure was 146176/628890 bytes in both destinations). Setting
+      // exitCode preserves the nonzero result while Node drains stdout first.
+      const generate = "const lines = []; for (let i = 0; i < 20000; i++) lines.push('line-' + i + '-' + 'x'.repeat(20)); process.stdout.write(lines.join('\\n') + '\\n'); process.exitCode = 7;";
+      const expected = `${Array.from({ length: 20000 }, (_, index) => `line-${index}-${"x".repeat(20)}`).join("\n")}\n`;
+      const fastChunks = [];
+      const fastOut = new Writable({
+        write(chunk, encoding, callback) { fastChunks.push(Buffer.from(chunk)); callback(); },
+      });
+      const runner = createTeeRunner({ logPath: join(teeDir, "restart-tee.log"), cwd: root, _stdout: fastOut });
+      const child = runner.spawn(process.execPath, ["-e", generate]);
+      // stdin must NOT be the console: an inherited TTY stdin lets the wrapped
+      // dsh flip the console into raw mode, which kills Ctrl+C for EVERYONE
+      // attached (live-verified: consoleMode was 0x0000 in the first test).
+      if (child.stdin !== null) throw new Error("the tee'd child must not own the console stdin");
+      const cleanup = runner.attach(child);
+      const result = await runner.waitFor(child);
+      if (typeof cleanup === "function") await cleanup();
+      await runner.close();
+      if (result.code !== 7) throw new Error("tee must preserve the child's exit code");
+      const logged = readFileSync(join(teeDir, "restart-tee.log"), "utf8");
+      const seen = Buffer.concat(fastChunks).toString("utf8");
+      if (logged !== expected || seen !== expected) throw new Error(`tee must be byte-identical on both targets (log ${logged.length}, console ${seen.length}, expected ${expected.length})`);
+      if (runner.broken) throw new Error("a healthy tee log must not be marked broken");
+
+      const errRunner = createTeeRunner({
+        logPath: join(teeDir, "restart-err.log"),
+        cwd: root,
+        _stdout: new Writable({ write(chunk, encoding, callback) { callback(); } }),
+      });
+      const errChild = errRunner.spawn(process.execPath, ["-e", "process.stderr.write('ERR-OUT\\n'); process.stdout.write('OUT\\n'); process.exit(0)"]);
+      const errCleanup = errRunner.attach(errChild);
+      await errRunner.waitFor(errChild);
+      if (typeof errCleanup === "function") await errCleanup();
+      await errRunner.close();
+      const errLogged = readFileSync(join(teeDir, "restart-err.log"), "utf8");
+      if (!errLogged.includes("ERR-OUT") || !errLogged.includes("OUT")) throw new Error("tee must mirror stderr as well as stdout");
+
+      // The tee'd child must carry the visible-chain flag: its own restart
+      // decision depends on it (stdout is a pipe here, the TTY is gone).
+      const chainRunner = createTeeRunner({
+        logPath: join(teeDir, "chain.log"),
+        cwd: root,
+        _stdout: new Writable({ write(chunk, encoding, callback) { callback(); } }),
+      });
+      const chainChild = chainRunner.spawn(process.execPath, ["-e", "console.log(process.env.DSH_PLUGIN_MALL_VISIBLE_CONSOLE ?? 'unset')"]);
+      const chainCleanup = chainRunner.attach(chainChild);
+      await chainRunner.waitFor(chainChild);
+      if (typeof chainCleanup === "function") await chainCleanup();
+      await chainRunner.close();
+      if (!readFileSync(join(teeDir, "chain.log"), "utf8").includes("1")) throw new Error("the tee'd child must inherit DSH_PLUGIN_MALL_VISIBLE_CONSOLE=1");
+
+      const consoleChunks = [];
+      const captureOut = new Writable({
+        write(chunk, encoding, callback) { consoleChunks.push(Buffer.from(chunk)); callback(); },
+      });
+      const brokenRunner = createTeeRunner({
+        logPath: join(teeDir, "never.log"),
+        cwd: root,
+        _stdout: captureOut,
+        _openLog: () => { throw new Error("disk on fire"); },
+      });
+      const brokenChild = brokenRunner.spawn(process.execPath, ["-e", "process.stdout.write('STILL-HERE\\n'); process.exit(5)"]);
+      const brokenCleanup = brokenRunner.attach(brokenChild);
+      const brokenResult = await brokenRunner.waitFor(brokenChild);
+      if (typeof brokenCleanup === "function") await brokenCleanup();
+      await brokenRunner.close();
+      const consoleText = Buffer.concat(consoleChunks).toString("utf8");
+      if (brokenResult.code !== 5 || !brokenRunner.broken) throw new Error("a failed log must be console-only and must not affect the child");
+      if (!consoleText.includes("STILL-HERE") || !consoleText.includes("disk on fire")) throw new Error("a failed log must warn on the console and keep showing output");
+
+      // A log that fails WHILE SATURATED must release the backpressure: a
+      // dead stream never drains, and the paused source pipes would otherwise
+      // stay paused forever — the wrapped dsh would hang mid-output.
+      {
+        let errorSink = null;
+        const evilLog = new EventEmitter();
+        evilLog.write = () => false; // always saturated, never drains
+        const recoverChunks = [];
+        const recoverOut = new Writable({
+          write(chunk, encoding, callback) { recoverChunks.push(Buffer.from(chunk)); callback(); },
+        });
+        const recoverRunner = createTeeRunner({
+          logPath: join(teeDir, "evil.log"),
+          cwd: root,
+          _stdout: recoverOut,
+          _openLog: () => {
+            errorSink = evilLog;
+            return evilLog;
+          },
+        });
+        const recoverChild = recoverRunner.spawn(process.execPath, ["-e", `
+          process.stdout.write('BEFORE-ERROR\\n');
+          setTimeout(() => { process.stdout.write('AFTER-ERROR\\n'); process.exit(3); }, 700);
+        `]);
+        const recoverCleanup = recoverRunner.attach(recoverChild);
+        // The first data block saturates the log and pauses the pipes; only
+        // THEN does the log fail — the second block can only arrive if the
+        // error path released the backpressure and resumed them.
+        recoverChild.stdout.once("data", () => {
+          setImmediate(() => { evilLog.emit("error", new Error("ENOSPC: log disk full")); });
+        });
+        const recoverResult = await recoverRunner.waitFor(recoverChild);
+        if (typeof recoverCleanup === "function") await recoverCleanup();
+        await recoverRunner.close();
+        const recoverText = Buffer.concat(recoverChunks).toString("utf8");
+        if (recoverResult.code !== 3 || !recoverRunner.broken) throw new Error("a mid-run log failure must not affect the child");
+        if (!recoverText.includes("BEFORE-ERROR") || !recoverText.includes("AFTER-ERROR")) throw new Error("a mid-run log failure must resume the paused pipes — output after the error must still arrive");
+      }
+
+      // The slow target is a plain EventEmitter, not a Writable: _write is a
+      // serialization point (queued writes never run once the releaser stops),
+      // which would lose TAIL bytes here and misblame the tee. write() always
+      // reports saturated, every drain is hand-released — the strictest
+      // pause/resume cycle the runner can be put through.
+      const slowChunks = [];
+      const pendingDrains = [];
+      const slowOut = new EventEmitter();
+      slowOut.write = (chunk) => {
+        slowChunks.push(Buffer.from(chunk));
+        pendingDrains.push(() => slowOut.emit("drain"));
+        return false;
+      };
+      const slowRunner = createTeeRunner({ logPath: join(teeDir, "slow.log"), cwd: root, _stdout: slowOut });
+      // The child paces itself on its own backpressure and exits naturally —
+      // process.exit() would truncate its in-flight stdout, which is a child
+      // bug the tee must not be blamed for.
+      const slowChild = slowRunner.spawn(process.execPath, ["-e", `
+        const chunk = 'y'.repeat(4096) + '\\n';
+        let index = 0;
+        function pump() {
+          while (index < 100) {
+            index += 1;
+            if (!process.stdout.write(chunk)) { process.stdout.once('drain', pump); return; }
+          }
+        }
+        pump();
+      `]);
+      const slowCleanup = slowRunner.attach(slowChild);
+      const slowDone = slowRunner.waitFor(slowChild);
+      const releaser = setInterval(() => { const release = pendingDrains.shift(); if (release !== undefined) release(); }, 1);
+      const slowResult = await slowDone;
+      clearInterval(releaser);
+      if (typeof slowCleanup === "function") await slowCleanup();
+      await slowRunner.close();
+      const total = 100 * (4096 + 1);
+      const slowSeen = slowChunks.reduce((sum, chunk) => sum + chunk.length, 0);
+      const slowLogged = readFileSync(join(teeDir, "slow.log"), "utf8");
+      if (slowResult.code !== 0 || slowSeen !== total || slowLogged.length !== total) {
+        throw new Error(`backpressure must not lose data (console ${slowSeen}, log ${slowLogged.length}, expected ${total})`);
+      }
+    }
+
+    // Console Ctrl watcher: the first Ctrl+C only marks the run interrupted;
+    // after forceGraceMs (or a second Ctrl+C) the child's whole process TREE
+    // is torn down (a bare kill leaves dsh's grandchildren attached to the
+    // console — the "window will not close" case). waitForProcessExit honors
+    // the flag.
+    {
+      const fakeChild = { pid: 31337, killCalls: 0, kill() { this.killCalls += 1; } };
+      const treeKills = [];
+      const watcher = createInterruptWatcher({ forceGraceMs: 25, _killTree: (pid) => treeKills.push(pid) });
+      watcher.noteChild(fakeChild);
+      process.emit("SIGINT");
+      if (!watcher.interrupted()) throw new Error("the first Ctrl+C must mark the watcher interrupted (and not kill yet)");
+      if (fakeChild.killCalls !== 0 || treeKills.length !== 0) throw new Error("the first Ctrl+C must give the child its own chance to exit");
+      await new Promise((resolvePromise) => setTimeout(resolvePromise, 60));
+      if (treeKills.length !== 1 || treeKills[0] !== 31337) throw new Error("the force-deadline must tear down the tree of a child that ignored Ctrl+C");
+      process.emit("SIGINT");
+      if (treeKills.length !== 2) throw new Error("a second Ctrl+C must escalate at once");
+      let aborted = false;
+      watcher.onAbort(() => { aborted = true; });
+      process.emit("SIGBREAK");
+      if (!aborted) throw new Error("inspection pauses must be cut short by any further console signal");
+      watcher.unlisten();
+      if (await waitForProcessExit(process.pid, 5000, 10, () => true) !== false) throw new Error("waitForProcessExit must abort on shouldAbort instead of waiting out the timeout");
+      if (!await waitForProcessExit(0x7ffffff1, 500, 20, () => false)) throw new Error("waitForProcessExit without an abort keeps its liveness semantics");
+    }
+
+    // The anti-misrollback pin: a Ctrl+C during the grace window is NOT a
+    // crash. On Windows the killed child reports code 1 / no signal — without
+    // the watcher's flag probation would roll back a healthy install and
+    // restart dsh in a window the user just tried to close.
+    {
+      const mkInterruptProfile = (homeName) => {
+        const ihome = join(root, homeName);
+        const iprofile = join(ihome, "profiles", "web");
+        const goodDir = join(iprofile, "node_modules", "good");
+        mkdirSync(goodDir, { recursive: true });
+        writeFileSync(join(iprofile, "package.json"), JSON.stringify({
+          dependencies: { good: "1.0.0" },
+          dsh: { profile: { bundles: ["good"] } },
+        }));
+        writeFileSync(join(iprofile, "cordis.patch.yml"), "[]\n");
+        writeFileSync(join(goodDir, "package.json"), JSON.stringify({ name: "good", version: "1.0.0", dsh: { bundle: { patch: "./cordis.patch.yml" } } }));
+        writeFileSync(join(goodDir, "cordis.patch.yml"), "- insert:\n    - id: good-row\n      name: good\n");
+        const ipending = createProfileSnapshot(iprofile, { spec: "good" });
+        markPendingSnapshot(ipending, { spec: "good@1.0.0", preflight: { candidate: { name: "good", version: "1.0.0", kind: "bundle" } } });
+        if (!validateInstalledProfile(iprofile).ok) throw new Error("interrupt fixture prerequisite: the profile must pass static validation");
+        return { ihome, iprofile };
+      };
+
+      // interrupted: exit 130, marker stays pending, nothing rolls back
+      const { ihome } = mkInterruptProfile("interrupt-home");
+      const interruptedWatcher = createInterruptWatcher({ forceGraceMs: 60000 });
+      process.emit("SIGINT");
+      const interruptedCode = await cmdLaunch({
+        profile: "web",
+        home: ihome,
+        graceMs: 4000,
+        commandArgv: [process.execPath, "-e", "process.exit(1)"],
+        interrupt: interruptedWatcher,
+      });
+      interruptedWatcher.unlisten();
+      if (interruptedCode !== 130) throw new Error(`an interrupted run must exit 130, got ${interruptedCode}`);
+      if (readPendingSnapshot(join(ihome, "profiles", "web")) === undefined) throw new Error("an interrupted run must leave the pending marker for the next launch");
+      if (!existsSync(join(ihome, "profiles", "web", "node_modules", "good", "package.json"))) throw new Error("an interrupted run must not roll the install back");
+
+      // The same crash WITHOUT an interrupt must not read as 130: offline the
+      // rollback-and-restart may legitimately fail (no pnpm to reconcile
+      // node_modules), which throws — both spellings prove the interrupt
+      // branch was NOT taken. A marker-free run pins the pure exit-code split.
+      const plain = mkInterruptProfile("interrupt-control-home");
+      let plainReturned;
+      let plainCode;
+      try {
+        plainCode = await cmdLaunch({
+          profile: "web",
+          home: plain.ihome,
+          graceMs: 4000,
+          commandArgv: [process.execPath, "-e", "process.exit(1)"],
+        });
+        plainReturned = true;
+      } catch {
+        plainReturned = false; // offline rollback limits, not the pin under test
+      }
+      if (plainReturned && plainCode === 130) throw new Error("a genuine grace-window crash must not report the interrupt convention 130");
+
+      const bareHome = join(root, "interrupt-bare-home");
+      const bareProfile = join(bareHome, "profiles", "web");
+      mkdirSync(bareProfile, { recursive: true });
+      writeFileSync(join(bareProfile, "package.json"), JSON.stringify({ dependencies: {} }));
+      writeFileSync(join(bareProfile, "cordis.patch.yml"), "[]\n");
+      const barePlain = await cmdLaunch({
+        profile: "web",
+        home: bareHome,
+        commandArgv: [process.execPath, "-e", "process.exit(1)"],
+      });
+      if (barePlain !== 1) throw new Error(`a plain crash without an interrupt keeps the child's code, got ${barePlain}`);
+      const bareWatcher = createInterruptWatcher({ forceGraceMs: 60000 });
+      process.emit("SIGINT");
+      const bareInterrupted = await cmdLaunch({
+        profile: "web",
+        home: bareHome,
+        commandArgv: [process.execPath, "-e", "process.exit(1)"],
+        interrupt: bareWatcher,
+      });
+      bareWatcher.unlisten();
+      if (bareInterrupted !== 130) throw new Error(`an interrupted plain run reports 130, got ${bareInterrupted}`);
+
+      // interrupted while waiting for the outgoing pid: refuse, don't outwait
+      const waitingWatcher = createInterruptWatcher({ forceGraceMs: 60000 });
+      process.emit("SIGINT");
+      let cancelled = false;
+      try {
+        await cmdLaunch({
+          profile: "web",
+          home: plain.ihome,
+          commandArgv: [process.execPath, "-e", "process.exit(0)"],
+          awaitExitPid: 999999,
+          interrupt: waitingWatcher,
+          _waitForExit: async (pid, timeoutMs, pollMs, shouldAbort) => (shouldAbort?.() === true ? false : true),
+        });
+      } catch (error) {
+        cancelled = /interrupted while waiting/.test(error.message);
+      }
+      waitingWatcher.unlisten();
+      if (!cancelled) throw new Error("a Ctrl+C during the await-exit wait must cancel the launch with a clear message");
+    }
+
     // quoteCmdArg: strict MSVCRT/CommandLineToArgvW quoting; cmd metacharacters
     // are refused rather than escaped.
     {