dsh-autorestart 0.8.4 → 0.8.6

package/lib/checkpoint.js

@@ -59,6 +59,20 @@ const RESTART_KEYS = new Set([
   'notBefore',
   'requesters',
   'parkGoals',
+  // THIS RESTART MUST NOT TAKE A SNAPSHOT (user decision, 2026-11-02).
+  // The request that follows a manual rollback is exactly a restart of a state
+  // that was JUST restored from a copy: snapshotting it again would push an
+  // identical duplicate into the list (and squeeze the older, still useful
+  // copies out of it). The undo copy of the rollback is the rollback point
+  // already, so this restart carries the fact "no copy for me" on the request
+  // itself — a flag, not an inference from the reason text.
+  'skipBackup',
+  // THE SNAPSHOT THIS REQUEST ALREADY TOOK. It lives on the request, so it is
+  // dropped by itself when the request is withdrawn or carried out (the request
+  // object is replaced / removed), and it survives a deferral — which is the whole
+  // point: a 205 MB copy must not be repeated because a conversation interrupted
+  // the restart (user report, 2026-10-30).
+  'snapshot',
 ]);
 
 const ENTRY_KEYS = new Set([
@@ -92,8 +106,16 @@ const CONTEXT_OVERFLOW_KEYS = new Set(['over', 'inputTokens', 'contextWindow', '
 /** LEGACY record shape written by the pause-based build. */
 const PARKED_GOAL_KEYS = new Set(['goalId', 'parkedAt', 'resumedAt']);
 
-/** Current record shape: written after a successful `ctx.goals.disarm()`. */
-const DISARMED_GOAL_KEYS = new Set(['goalId', 'disarmedAt', 'resumedAt']);
+/**
+ * Current record shape: written after a successful `ctx.goals.disarm()`.
+ *
+ * `reason` says WHY the goal was taken away ("restart-queued" when the pending
+ * restart did it). The write side has been writing it since 2026-11-02, and a
+ * whitelist that refused it silently threw the answer away on the next boot —
+ * the record existed but could not be read. A field the plugin really writes
+ * belongs in the shape it is normalized against.
+ */
+const DISARMED_GOAL_KEYS = new Set(['goalId', 'disarmedAt', 'resumedAt', 'reason']);
 
 const TOP_LEVEL_KEYS = new Set([
   'version',
@@ -110,6 +132,16 @@ const TOP_LEVEL_KEYS = new Set([
   'seenFeatureVersions',
   'onboarding',
   'sleep',
+  // The seed of the FIRST safe copy: what happened when a new host process
+  // looked for a known-good backup and found none (user decision, 2026-10-30).
+  'firstInstallBackup',
+  // THE BOOT-TIME REPORTS (user decision, 2026-11-02). The Host writes both and
+  // the next boot has to be able to read them back: the sweep of leftover
+  // watcher scripts, and the state of the restart gate. A whitelist that refused
+  // them threw the answer away on the very next boot — the record existed, but
+  // could not be read.
+  'watcherHygiene',
+  'restartGate',
   'updatedAt',
 ]);
 
@@ -228,6 +260,10 @@ function normalizeRestartPhase(raw, now) {
     // that polls every 2 s would otherwise never learn that a backup happened
     // (user report, 2026-10-29). null = nothing was measured.
     snapshotBytes: isFiniteNumber(raw.snapshotBytes) ? Math.max(0, Math.trunc(raw.snapshotBytes)) : null,
+    // WHY the stage is what it is ("deferred: conversation-active", "snapshot
+    // done", …). A stage without a reason cannot be diagnosed after the fact —
+    // and the hang this fixes was exactly an unexplained leftover stage.
+    reason: typeof raw.reason === 'string' && raw.reason !== '' ? raw.reason : null,
     blocked: isFiniteNumber(raw.blocked) ? Math.max(0, Math.trunc(raw.blocked)) : 0,
   };
   return { record, changed };
@@ -244,7 +280,16 @@ function normalizeRestartPhase(raw, now) {
  * @param {{ phase: string, now?: number, blocked?: number, restartStage?: boolean }} options
  * @returns {object|null} the recorded stage
  */
-export function setRestartPhase(state, { phase, now = Date.now(), blocked = 0, restartStage = true } = {}) {
+export function setRestartPhase(state, {
+  phase,
+  now = Date.now(),
+  blocked = 0,
+  restartStage = true,
+  reason = null,
+  // undefined = carry what the record already measured, null = forget it, a
+  // number = this is the size of the snapshot this restart already paid for.
+  snapshotBytes,
+} = {}) {
   if (!isObject(state)) return null;
   if (!RESTART_PHASES.includes(phase)) return state.restartPhase ?? null;
   const moment = isFiniteNumber(now) ? now : Date.now();
@@ -273,8 +318,14 @@ export function setRestartPhase(state, { phase, now = Date.now(), blocked = 0, r
       ? previous.progress
       : null,
     // A NEW restart starts with nothing measured; a stage change inside one
-    // restart keeps the size it already has.
-    snapshotBytes: sameRestart ? measuredBytes : null,
+    // restart keeps the size it already has — and a caller that knows the size
+    // (the request's own snapshot) may state it explicitly.
+    snapshotBytes: snapshotBytes === null
+      ? null
+      : (isFiniteNumber(snapshotBytes) ? Math.max(0, Math.trunc(snapshotBytes)) : (sameRestart ? measuredBytes : null)),
+    // WHY this stage (see normalizeRestartPhase): "deferred: <reason>" is what
+    // tells a reader that the restart went back to waiting on purpose.
+    reason: typeof reason === 'string' && reason !== '' ? reason : null,
     blocked: isFiniteNumber(blocked) ? Math.max(0, Math.trunc(blocked)) : 0,
   };
   state.restartPhase = record;
@@ -308,6 +359,7 @@ export function setRestartProgress(state, { files = 0, bytes = 0, total = 0, fil
     // The live byte counter IS the size of the snapshot so far: keeping it here
     // means the number survives the moment the copy ends.
     snapshotBytes: number(bytes),
+    reason: previous !== null && typeof previous.reason === 'string' ? previous.reason : null,
     blocked: previous !== null && isFiniteNumber(previous.blocked) ? previous.blocked : 0,
   };
   state.updatedAt = moment;
@@ -489,10 +541,20 @@ function normalizeDisarmedGoals(raw) {
       goalId: nullableString(value.goalId),
       disarmedAt: nullableNumber(value.disarmedAt),
       resumedAt: nullableNumber(value.resumedAt),
+      // WHY the goal was taken away. Kept like the timestamps: a record whose
+      // reason survives is the difference between "it was disarmed" and "it was
+      // disarmed because a restart was queued".
+      reason: nullableString(value.reason),
     };
     if (typeof value.goalId !== 'string' && value.goalId != null) changed = true;
     if (value.disarmedAt != null && !isFiniteNumber(value.disarmedAt)) changed = true;
     if (value.resumedAt != null && !isFiniteNumber(value.resumedAt)) changed = true;
+    // A reason that is not a string is not a readable reason: drop the value
+    // (the field itself is known, so this is not "an unknown key").
+    if (typeof value.reason !== 'string' && value.reason != null) {
+      record.reason = null;
+      changed = true;
+    }
     if (record.goalId === null && record.disarmedAt === null && record.resumedAt === null) {
       changed = true;
       continue;
@@ -715,6 +777,31 @@ function normalizeRequesters(raw) {
  * @param {unknown} raw
  * @returns {{ restart: object|null, changed: boolean }}
  */
+/**
+ * Coerce the "this request already took a snapshot" record.
+ *
+ * It is a pointer plus the numbers of that copy, and nothing else: the profile
+ * itself lives in the backup directory, which is checked against the manifest
+ * before it is used again.
+ *
+ * @param {unknown} raw
+ * @returns {{ requestedAt: number, dir: string, profileDir: string|null, files: number, bytes: number, total: number, at: number }|null}
+ */
+function normalizeRestartSnapshot(raw) {
+  if (!isObject(raw)) return null;
+  if (typeof raw.dir !== 'string' || raw.dir === '') return null;
+  const number = (value) => (isFiniteNumber(value) ? Math.max(0, Math.trunc(value)) : 0);
+  return {
+    requestedAt: number(raw.requestedAt),
+    dir: raw.dir,
+    profileDir: typeof raw.profileDir === 'string' && raw.profileDir !== '' ? raw.profileDir : null,
+    files: number(raw.files),
+    bytes: number(raw.bytes),
+    total: number(raw.total),
+    at: number(raw.at),
+  };
+}
+
 function normalizeRestart(raw) {
   if (!isObject(raw)) return { restart: null, changed: raw !== null && raw !== undefined };
   let changed = false;
@@ -735,13 +822,23 @@ function normalizeRestart(raw) {
     // Disarming the goals of goal-driven sessions is the default: a restart must
     // never deadlock behind a goal that keeps its own agent busy.
     parkGoals: raw.parkGoals !== false,
+    // A restart that must not snapshot (the one that follows a manual rollback,
+    // user decision 2026-11-02). It defaults to FALSE: every other restart keeps
+    // taking its copy, and only a request that says so in bytes skips it.
+    skipBackup: raw.skipBackup === true,
   };
+  // The snapshot is only carried when there IS one: a checkpoint that never took
+  // a snapshot must normalize to exactly the object it was.
+  const snapshot = normalizeRestartSnapshot(raw.snapshot);
+  if (snapshot !== null) restart.snapshot = snapshot;
+  else if (raw.snapshot != null) changed = true;
   if (!isFiniteNumber(raw.generation) || raw.generation < 0) changed = true;
   if (!isFiniteNumber(raw.requestedAt)) changed = true;
   if (!isFiniteNumber(raw.attempt) || raw.attempt < 0) changed = true;
   if (raw.failedAttempts != null && (!isFiniteNumber(raw.failedAttempts) || raw.failedAttempts < 0)) changed = true;
   if (raw.notBefore != null && !isFiniteNumber(raw.notBefore)) changed = true;
   if (typeof raw.parkGoals !== 'boolean' && raw.parkGoals != null) changed = true;
+  if (typeof raw.skipBackup !== 'boolean' && raw.skipBackup != null) changed = true;
   if (typeof raw.resume !== 'boolean' && raw.resume != null) changed = true;
   if (raw.requesters != null && !Array.isArray(raw.requesters)) changed = true;
   if (Array.isArray(raw.requesters) && requesters.length !== raw.requesters.length) changed = true;
@@ -845,9 +942,110 @@ export function normalizeState(raw, now = Date.now()) {
     if (onboarding.changed) repaired = true;
   }
 
+  // THE FIRST SAFE COPY: what happened when this machine looked for a
+  // known-good backup and found none. It survives a restart, so a machine with
+  // NO safe copy can say so instead of looking healthy.
+  if (raw.firstInstallBackup != null) {
+    const seeded = normalizeFirstInstallBackup(raw.firstInstallBackup);
+    if (seeded === null) repaired = true;
+    else state.firstInstallBackup = seeded;
+  }
+
+  // THE SWEEP OF LEFTOVER WATCHER SCRIPTS: which files this platform could not
+  // run and therefore removed. It survives a restart, so "leftover files = 0"
+  // stays provable instead of being re-derived from an empty directory.
+  if (raw.watcherHygiene != null) {
+    const hygiene = normalizeWatcherHygiene(raw.watcherHygiene);
+    if (hygiene === null) repaired = true;
+    else state.watcherHygiene = hygiene;
+  }
+
+  // THE RESTART GATE: why the restart is (or is not) allowed right now. It is a
+  // REPORT, not a permission — the live gate decides every time — but the answer
+  // of the boot that wrote it must survive to the next boot.
+  if (raw.restartGate != null) {
+    const gate = normalizeRestartGate(raw.restartGate);
+    if (gate === null) repaired = true;
+    else state.restartGate = gate;
+  }
+
   return { state, repaired };
 }
 
+/**
+ * Normalize the report of the legacy-watcher sweep.
+ *
+ * A value that is not an object says nothing about the sweep, so it is dropped
+ * (and the caller marks the state as repaired).
+ *
+ * @param {unknown} raw
+ * @returns {{ skipped: boolean, reason: string|null, removed: string[], kept: string[], scanned: number, error: string|null }|null}
+ */
+function normalizeWatcherHygiene(raw) {
+  if (!isObject(raw)) return null;
+  /** @param {unknown} value */
+  const names = (value) => (Array.isArray(value)
+    ? value.filter((name) => typeof name === 'string' && name !== '')
+    : []);
+  return {
+    skipped: raw.skipped === true,
+    reason: typeof raw.reason === 'string' && raw.reason !== '' ? raw.reason : null,
+    removed: names(raw.removed),
+    kept: names(raw.kept),
+    scanned: isFiniteNumber(raw.scanned) && raw.scanned >= 0 ? Math.trunc(raw.scanned) : 0,
+    error: typeof raw.error === 'string' && raw.error !== '' ? raw.error : null,
+  };
+}
+
+/**
+ * Normalize the report of the restart gate.
+ *
+ * `allow` and `reason` are the answer; without both there is nothing to read, so
+ * the record is dropped. `blockedBy` names the sessions that were in the way.
+ *
+ * @param {unknown} raw
+ * @returns {{ allow: boolean, reason: string, blockedBy: Array<{ sessionId: string|null, reason: string }>, quietForMs: number }|null}
+ */
+function normalizeRestartGate(raw) {
+  if (!isObject(raw)) return null;
+  const reason = typeof raw.reason === 'string' && raw.reason !== '' ? raw.reason : null;
+  if (typeof raw.allow !== 'boolean' || reason === null) return null;
+  const blockedBy = Array.isArray(raw.blockedBy)
+    ? raw.blockedBy.filter((entry) => isObject(entry)).map((entry) => ({
+      sessionId: typeof entry.sessionId === 'string' && entry.sessionId !== '' ? entry.sessionId : null,
+      reason: typeof entry.reason === 'string' ? entry.reason : '',
+    }))
+    : [];
+  return {
+    allow: raw.allow,
+    reason,
+    blockedBy,
+    quietForMs: isFiniteNumber(raw.quietForMs) && raw.quietForMs >= 0 ? raw.quietForMs : 0,
+  };
+}
+
+/**
+ * Normalize the record of the first-install safe copy.
+ *
+ * A record without a `result` says nothing, so it is dropped (and the caller
+ * marks the state as repaired).
+ *
+ * @param {unknown} raw
+ * @returns {{ result: string, at: number|null, dir: string|null, bytes: number|null, error: string|null }|null}
+ */
+function normalizeFirstInstallBackup(raw) {
+  if (!isObject(raw)) return null;
+  const result = typeof raw.result === 'string' && raw.result !== '' ? raw.result : null;
+  if (result === null) return null;
+  return {
+    result,
+    at: isFiniteNumber(raw.at) ? raw.at : null,
+    dir: typeof raw.dir === 'string' && raw.dir !== '' ? raw.dir : null,
+    bytes: isFiniteNumber(raw.bytes) ? raw.bytes : null,
+    error: typeof raw.error === 'string' && raw.error !== '' ? raw.error : null,
+  };
+}
+
 /**
  * Read a checkpoint from disk. Never throws and never creates directories.
  *
@@ -1437,10 +1635,15 @@ export function setContextOverflow(state, sessionId, { over = false, inputTokens
  * Mutates `state` in place and returns it.
  *
  * @param {object} state
- * @param {{ reason?: string, bySessionId?: string|null, resume?: boolean, parkGoals?: boolean, now?: number }} options
+ * @param {{ reason?: string, bySessionId?: string|null, resume?: boolean, parkGoals?: boolean, skipBackup?: boolean, now?: number }} options
+ *   `skipBackup: true` marks a restart that MUST NOT take the pre-restart
+ *   snapshot. It is off by default; the manual rollback sets it (user decision,
+ *   2026-11-02) because the state this restart brings up was just restored from
+ *   a copy, and copying it again only makes a duplicate that squeezes the older
+ *   copies out of the list.
  * @returns {object} state
  */
-export function requestRestart(state, { reason, bySessionId = null, resume = true, parkGoals = true, now = Date.now() } = {}) {
+export function requestRestart(state, { reason, bySessionId = null, resume = true, parkGoals = true, skipBackup = false, now = Date.now() } = {}) {
   const generation = (isFiniteNumber(state.generation) && state.generation >= 0 ? state.generation : 0) + 1;
   state.generation = generation;
   state.phase = 'deferred';
@@ -1478,6 +1681,10 @@ export function requestRestart(state, { reason, bySessionId = null, resume = tru
     // A goal-driven session must not deadlock the restart: disarming its goal is
     // on by default and can be turned off per restart request.
     parkGoals: parkGoals !== false,
+    // THIS REQUEST ASKS FOR NO SNAPSHOT (default: it does want one). The
+    // restart that carries out a manual rollback sets it, so the state that was
+    // just restored is not copied on top of the list a second time.
+    skipBackup: skipBackup === true,
   };
   for (const requester of requesters) {
     if (requester.resume === false) continue;

package/lib/cookie-clear.js

@@ -0,0 +1,260 @@
+/**
+ * dsh-autorestart - the command that removes the STALE handshake cookies.
+ *
+ * WHY THIS EXISTS:
+ *
+ * The desktop app mints ONE `dsh-auth-*` cookie per launch. The name carries
+ * the random port, the cookie lives 30 days (Max-Age=2592000), and a cookie
+ * does NOT carry a port - so the browser sends ALL of them, on every request,
+ * to 127.0.0.1.
+ *
+ * The host answers with Node's default max header size of 16384 bytes. With 71
+ * cookies the Cookie header alone is 16188 bytes; add the browser's own headers
+ * and the request is 16559 bytes -> the host answers 431 (Request Header
+ * Fields Too Large), the desktop app reports the misleading "desktop welcome:
+ * Web authentication failed" and dies on startup. The crash loop then trips
+ * the official native-fatal recovery, which wipes the profile and drops every
+ * plugin but two.
+ *
+ * Measured on this machine with the real cookies and the real browser headers:
+ *   70 cookies -> 16331 bytes -> 200 OK
+ *   71 cookies -> 16559 bytes -> 431 Request Header Fields Too Large
+ *
+ * WHERE IT RUNS: between the kill and the relaunch. Only then has Chromium
+ * left, and only then is the cookie jar unlocked.
+ *
+ * WHAT IT MATCHES (widened, user decision 2026-10-30): every `dsh-auth-%`
+ * cookie of `127.0.0.1`, WHATEVER its path. The official code that mints them
+ * always writes `Path=/`, but a leftover cookie with another path would still
+ * be sent to `127.0.0.1` and would still count against the 16 KB header — and
+ * a missed deletion costs far more than a deleted one. Nothing else in the jar
+ * is ever addressed.
+ *
+ * The command is EMPTY when the interpreter or the script cannot be found: the
+ * restart then behaves exactly as it did before, and a cleanup that cannot run
+ * never blocks a restart.
+ *
+ * This module is the SINGLE source of the command: the plugin and the
+ * verification script both build it here, so a verification can never prove
+ * something the plugin does not actually do.
+ *
+ * THE RESULT IS WRITTEN DOWN: the cleanup script writes
+ * `<stateDir>/last-cookie-clear.json` (`{at, ok, removed, reason}`) because it
+ * is the only process that can know how many rows it deleted, and the health
+ * route reports that record. It is the result of the LAST cleanup, never a
+ * live count: the cookie jar is locked by the running browser, so a live count
+ * would be a guess dressed as a fact.
+ *
+ * ESM only, Node builtins only.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { resolveNodeInterpreter } from './node-runtime.js';
+
+/** The directory this very file lives in - the plugin directory. */
+const PLUGIN_DIR = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+
+/** The cleanup script, next to the other rescue scripts. */
+export const COOKIE_CLEAR_SCRIPT_NAME = 'clear-dsh-auth-cookies.mjs';
+
+/** How long the cleanup may run before it is killed, in milliseconds. */
+const CLEANUP_TIMEOUT_MS = 20000;
+
+/** The file the cleanup script writes its result into (inside the state dir). */
+export const COOKIE_CLEAR_REPORT_NAME = 'last-cookie-clear.json';
+
+/** The version of that record. */
+export const COOKIE_CLEAR_REPORT_VERSION = 1;
+
+/**
+ * The path of the cleanup result.
+ *
+ * @param {string} stateDir
+ * @returns {string}
+ */
+export function cookieClearReportPath(stateDir) {
+  const root = typeof stateDir === 'string' ? stateDir.trim() : '';
+  if (root === '') return '';
+  return path.join(root, COOKIE_CLEAR_REPORT_NAME);
+}
+
+/**
+ * Write the result of a cleanup.
+ *
+ * The four fields the health route and the settings page read are `at`, `ok`,
+ * `removed` and `reason`; the version and the ISO time are there so a human
+ * reading the file does not have to convert an epoch.
+ *
+ * @param {string} stateDir
+ * @param {{ at?: number, ok?: boolean, removed?: number|null, reason?: string }} [payload]
+ * @returns {{ ok: boolean, path: string, report: object|null, error: string|null }}
+ */
+export function writeCookieClearReport(stateDir, payload = {}) {
+  const target = cookieClearReportPath(stateDir);
+  if (target === '') {
+    return { ok: false, path: '', report: null, error: 'there is no state directory to write the result into' };
+  }
+  const at = Number.isFinite(Number(payload.at)) ? Number(payload.at) : Date.now();
+  const report = {
+    version: COOKIE_CLEAR_REPORT_VERSION,
+    at,
+    atIso: new Date(at).toISOString(),
+    ok: payload.ok === true,
+    removed: Number.isFinite(Number(payload.removed)) ? Math.max(0, Math.trunc(Number(payload.removed))) : null,
+    reason: typeof payload.reason === 'string' ? payload.reason : '',
+  };
+  try {
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    const temporary = target + '.tmp';
+    // No byte order mark: every reader of this file is JSON.parse.
+    fs.writeFileSync(temporary, JSON.stringify(report, null, 2) + '\n', 'utf8');
+    fs.renameSync(temporary, target);
+    return { ok: true, path: target, report, error: null };
+  } catch (error) {
+    return {
+      ok: false,
+      path: target,
+      report,
+      error: error && error.message ? String(error.message) : String(error),
+    };
+  }
+}
+
+/**
+ * Read the result of the last cleanup.
+ *
+ * A file that is not there is an ANSWER ("no cleanup has run yet"), not an
+ * error: the very first launch of a fresh installation has none.
+ *
+ * @param {string} stateDir
+ * @returns {{ ok: boolean, report: object|null, error: string|null }}
+ */
+export function readCookieClearReport(stateDir) {
+  const target = cookieClearReportPath(stateDir);
+  if (target === '') return { ok: false, report: null, error: 'there is no state directory to read the result from' };
+  let text = '';
+  try {
+    text = fs.readFileSync(target, 'utf8');
+  } catch (error) {
+    const missing = error && error.code === 'ENOENT';
+    return {
+      ok: false,
+      report: null,
+      error: missing ? 'no cleanup has run yet' : (error && error.message ? String(error.message) : String(error)),
+    };
+  }
+  try {
+    const parsed = JSON.parse(text.charCodeAt(0) === 0xfeff ? text.slice(1) : text);
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+      return { ok: false, report: null, error: 'the cleanup result is not an object' };
+    }
+    return { ok: true, report: parsed, error: null };
+  } catch (error) {
+    return {
+      ok: false,
+      report: null,
+      error: 'the cleanup result cannot be parsed: ' + (error && error.message ? String(error.message) : String(error)),
+    };
+  }
+}
+
+/**
+ * The cleanup result as the health route reports it.
+ *
+ * TWO HONESTY RULES, both written down here so nobody "improves" them later:
+ *
+ *   1. the numbers are those of the LAST cleanup, never a live count. The
+ *      cookie jar is an open SQLite database of a RUNNING browser; reading it
+ *      while Chromium holds it either fails or (worse) reports a number that
+ *      is already stale. `live` is therefore always `null`, and the note says
+ *      why.
+ *   2. "no cleanup has run yet" and "the cleanup could not run" are different
+ *      answers, and neither is reported as success.
+ *
+ * @param {object|null} report the parsed `last-cookie-clear.json`, if any
+ * @param {{ readError?: string|null }} [meta]
+ * @returns {{
+ *   at: number|null, atIso: string|null, ok: boolean|null, removed: number|null,
+ *   reason: string, live: null, liveNote: string, source: string,
+ * }}
+ */
+export function summarizeCookieClear(report, meta = {}) {
+  const source = 'last-cookie-clear.json';
+  const liveNote = 'the live number of cookies cannot be read: the cookie jar belongs to the running browser and is locked; this is the result of the last cleanup';
+  const record = report && typeof report === 'object' ? report : null;
+  if (record === null) {
+    return {
+      at: null,
+      atIso: null,
+      ok: null,
+      removed: null,
+      reason: typeof meta.readError === 'string' && meta.readError !== ''
+        ? String(meta.readError)
+        : 'no cleanup has run yet',
+      live: null,
+      liveNote,
+      source,
+    };
+  }
+  const at = Number.isFinite(Number(record.at)) ? Number(record.at) : null;
+  return {
+    at,
+    atIso: typeof record.atIso === 'string' ? record.atIso : (at === null ? null : new Date(at).toISOString()),
+    ok: record.ok === true,
+    removed: Number.isFinite(Number(record.removed)) ? Number(record.removed) : null,
+    reason: typeof record.reason === 'string' ? record.reason : '',
+    live: null,
+    liveNote,
+    source,
+  };
+}
+
+/**
+ * Escape a value for a single-quoted PowerShell string.
+ *
+ * @param {unknown} value
+ * @returns {string}
+ */
+export function psQuote(value) {
+  return "'" + String(value == null ? '' : value).replace(/'/g, "''") + "'";
+}
+
+/**
+ * Build the command that removes the stale handshake cookies.
+ *
+ * @param {{
+ *   pluginDir?: string,
+ *   execPath?: string,
+ *   platform?: string,
+ *   timeoutMs?: number,
+ * }} [options]
+ * @returns {string} the command, or '' when it cannot be built
+ */
+export function buildCookieClearCommand(options = {}) {
+  try {
+    const pluginDir = typeof options.pluginDir === 'string' && options.pluginDir !== ''
+      ? options.pluginDir
+      : PLUGIN_DIR;
+    const script = path.join(pluginDir, 'scripts', COOKIE_CLEAR_SCRIPT_NAME);
+    if (!fs.existsSync(script)) return '';
+    const interpreter = resolveNodeInterpreter({
+      execPath: typeof options.execPath === 'string' ? options.execPath : process.execPath,
+      platform: typeof options.platform === 'string' ? options.platform : process.platform,
+    });
+    if (!interpreter.ok) return '';
+    const timeoutMs = typeof options.timeoutMs === 'number' && Number.isFinite(options.timeoutMs) && options.timeoutMs > 0
+      ? Math.trunc(options.timeoutMs)
+      : CLEANUP_TIMEOUT_MS;
+    // The cleanup runs as its own hidden process with a wait timeout: if it
+    // hangs, it is killed and the relaunch continues anyway.
+    return 'powershell.exe -NoProfile -NonInteractive -Command '
+      + '"$p = Start-Process -FilePath ' + psQuote(interpreter.path)
+      + ' -ArgumentList ' + psQuote(script)
+      + ' -WindowStyle Hidden -PassThru; if ($null -ne $p) { if (-not $p.WaitForExit(' + timeoutMs + ')) { $p.Kill() } }"';
+  } catch {
+    return '';
+  }
+}

package/lib/lifecycle.js

@@ -293,8 +293,17 @@ export function restartDecision(
   const requestedAt = isFiniteNumber(restart.requestedAt) ? restart.requestedAt : 0;
   const attempt = isFiniteNumber(restart.attempt) ? restart.attempt : 0;
   const notBefore = isFiniteNumber(restart.notBefore) ? restart.notBefore : 0;
-  const softDeadline = requestedAt + (isFiniteNumber(softMs) ? softMs : 0);
-  const hardDeadline = requestedAt + (isFiniteNumber(hardMs) ? hardMs : 0);
+
+  // NO DEADLINES (user decision, 2026-11-02).
+  //
+  // `softMs` / `hardMs` stay in the option list so no caller has to change, and
+  // they are IGNORED: a pending restart waits for the idle gate and nothing else.
+  // There is no soft window, no hard deadline, no timer and no default that can
+  // end the request — it ends in exactly two ways:
+  //   1. the gate opens and the restart runs;
+  //   2. the user withdraws it (the cancel route, handled by the caller).
+  // The old design reported "the hard deadline has passed", which read like "the
+  // request is void" — it never was, and it only confused everybody reading it.
 
   // Backoff after a failed scheduling attempt: wait without re-planning.
   if (notBefore > 0 && now < notBefore) return { action: 'wait', reason: 'restart-backoff' };
@@ -312,50 +321,24 @@ export function restartDecision(
     return { action: 'restart', reason: 'no-agent-running' };
   }
 
-  if (now < softDeadline) return { action: 'wait', reason: 'agents-busy-within-soft-window' };
-
-  if (now < hardDeadline) {
-    if (restart.softWarned === true) {
-      return { action: 'wait', reason: 'agents-busy-awaiting-hard-deadline' };
-    }
+  // Somebody is still running. The ONLY thing that may act on that is the explicit
+  // opt-in `forceRestartWhenBusy` — it restarts OVER a running conversation, and
+  // it says so in its own name. It is not a deadline and it is off by default.
+  if (forceRestartWhenBusy === true && policy === 'auto' && state.phase === 'deferred') {
+    if (attempt > 0) return { action: 'give-up', reason: 'forced-restart-already-attempted' };
     return {
-      action: 'warn',
-      reason: 'agents-busy-past-soft-deadline',
-      log: 'dsh-autorestart: agents are still running after the soft deadline; waiting for the hard deadline, where the restart is only forced if forceRestartWhenBusy is enabled',
-      markSoftWarned: true,
+      action: 'force-restart',
+      reason: 'force-restart-while-busy',
+      log: 'dsh-autorestart: forceRestartWhenBusy is enabled, so the restart interrupts the running conversations',
     };
   }
 
-  // Hard deadline reached while a conversation is still running.
-  //
-  // From here on the plugin does NOT pretend that "everything is fine, we are
-  // just waiting a little longer": the wait has become a LONG wait, and the
-  // caller (index.js) has to make it VISIBLE — in the log and in the state
-  // payload — while KEEPING the user's restart request alive. The request is
-  // never silently dropped.
-  if (policy === 'wait') {
-    return {
-      action: 'long-wait',
-      reason: 'hard-deadline-policy-wait',
-      log: 'defer policy wait: still busy after hard deadline',
-      blockedBy: busy,
-      waitingSince: requestedAt,
-    };
-  }
-  // The hard deadline only forces a restart when the operator explicitly opted in
-  // (forceRestartWhenBusy) AND the restart is actually deferred. Every other
-  // combination keeps waiting: a running conversation is never killed.
-  if (forceRestartWhenBusy === true && policy === 'auto' && state.phase === 'deferred') {
-    if (attempt > 0) return { action: 'give-up', reason: 'forced-restart-already-attempted' };
-    return { action: 'force-restart', reason: 'hard-deadline-force-restart' };
-  }
-  // forceRestartWhenBusy is disabled (the default): the restart keeps waiting
-  // until the idle gate is quiet again, and it never gives up. The result says
-  // so explicitly — a long wait, with the sessions that hold it.
+  // Everything else keeps waiting, for as long as it takes. The answer says so
+  // explicitly — a long wait, with the sessions that hold it, and no end time.
   return {
     action: 'long-wait',
-    reason: 'hard-deadline-waiting-for-conversations',
-    log: 'dsh-autorestart: hard deadline reached but conversations are still running; forceRestartWhenBusy is disabled, so the restart keeps waiting',
+    reason: 'waiting-for-conversations',
+    log: 'dsh-autorestart: conversations are still running; the restart keeps waiting until they are done',
     blockedBy: busy,
     waitingSince: requestedAt,
   };