dsh-autorestart 0.6.1 → 0.7.0

package/lib/backup.js

@@ -37,9 +37,87 @@ export const DEFAULT_MAX_BACKUPS = 2;
 /** The report the detached helper writes when it rolls a backup back. */
 export const ROLLBACK_REPORT_NAME = 'last-rollback.json';
 
+/** The lock that makes sure a snapshot is restored ONCE. */
+export const ROLLBACK_LOCK_NAME = 'rollback.lock';
+
+/**
+ * Claim the right to restore the snapshot.
+ *
+ * TWO parties can want to restore the snapshot at the same time: the plugin
+ * itself (it saw that the restart failed) and the detached watcher (the host
+ * never came back). Both copy the same files over the profile — two copies at
+ * once would write the same files at the same time, and the plugin tree is
+ * 117 MB.
+ *
+ * The claim is atomic: the file is CREATED, never opened, so exactly ONE
+ * caller gets it. The loser stands down.
+ *
+ * @param {string} stateDir
+ * @returns {{ ok: boolean, path: string, error: string|null }}
+ */
+export function claimRollbackLock(stateDir) {
+  const dir = typeof stateDir === 'string' ? stateDir.trim() : '';
+  if (dir === '') return { ok: false, path: '', error: 'claimRollbackLock requires stateDir' };
+  const file = path.join(dir, ROLLBACK_LOCK_NAME);
+  try {
+    fs.mkdirSync(dir, { recursive: true });
+  } catch {
+    /* the directory may already be there */
+  }
+  // A lock that is older than 10 minutes belongs to a process that died in the
+  // middle of its restore: it must not block the rollback for ever.
+  try {
+    const stat = fs.statSync(file);
+    if (Date.now() - stat.mtimeMs > 10 * 60 * 1000) {
+      fs.rmSync(file, { force: true });
+    }
+  } catch {
+    /* no lock there: nothing to clean up */
+  }
+  try {
+    const handle = fs.openSync(file, 'wx');
+    try {
+      fs.writeFileSync(handle, String(process.pid ?? ''), 'utf8');
+    } catch {
+      /* the owner is what matters, not the note inside the file */
+    }
+    try {
+      fs.closeSync(handle);
+    } catch {
+      /* nothing else to do */
+    }
+    return { ok: true, path: file, error: null };
+  } catch {
+    return { ok: false, path: file, error: 'another rollback is already running' };
+  }
+}
+
+/**
+ * Release the rollback lock.
+ *
+ * @param {string} stateDir
+ * @returns {boolean} whether a lock was removed
+ */
+export function releaseRollbackLock(stateDir) {
+  const dir = typeof stateDir === 'string' ? stateDir.trim() : '';
+  if (dir === '') return false;
+  try {
+    fs.rmSync(path.join(dir, ROLLBACK_LOCK_NAME), { force: true });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 /**
  * A filesystem-safe timestamp for a backup directory name.
  *
+ * The name is in UTC on purpose: it sorts chronologically and it does not
+ * depend on the timezone of the machine. The price is that it does NOT look
+ * like the wall clock the operator reads (`2026-10-29T00-25-20-779Z` is
+ * 08:25 in Shanghai) — so the manifest and the restart record carry the local
+ * time as well, and a fresh snapshot can never be mistaken for an old one.
+ *
  * @param {number} [now]
  * @returns {string}
  */
@@ -48,6 +126,26 @@ export function backupStamp(now = Date.now()) {
   return date.toISOString().replace(/[:.]/g, '-');
 }
 
+/**
+ * The local time of an epoch, with the UTC offset (`2026-10-29T08:25:20+08:00`).
+ *
+ * @param {number|null|undefined} at
+ * @returns {string|null}
+ */
+export function backupLocalTime(at) {
+  const value = Number(at);
+  if (!Number.isFinite(value)) return null;
+  const date = new Date(value);
+  if (Number.isNaN(date.getTime())) return null;
+  const offsetMinutes = -date.getTimezoneOffset();
+  const sign = offsetMinutes >= 0 ? '+' : '-';
+  const absolute = Math.abs(offsetMinutes);
+  const hours = String(Math.floor(absolute / 60)).padStart(2, '0');
+  const minutes = String(absolute % 60).padStart(2, '0');
+  const local = new Date(value + offsetMinutes * 60000).toISOString();
+  return `${local.slice(0, 19)}${sign}${hours}:${minutes}`;
+}
+
 /**
  * The backups directory that belongs to a state directory.
  *
@@ -142,8 +240,12 @@ export function pruneBackups(backupsDir, maxBackups = DEFAULT_MAX_BACKUPS) {
 /**
  * List the backups, newest first.
  *
+ * Only the DIRECTORY is read: the name, the manifest and nothing else. The
+ * backup tree can be 150 MB per copy, so its contents are never walked — the
+ * manifest already carries the size, the file count and the local time.
+ *
  * @param {string} backupsDir
- * @returns {Array<{name: string, dir: string, at: number|null, bytes: number|null, includePlugins: boolean}>}
+ * @returns {Array<{name: string, dir: string, at: number|null, atLocal: string|null, bytes: number|null, files: number|null, includePlugins: boolean}>}
  */
 export function listBackups(backupsDir) {
   let names;
@@ -158,11 +260,18 @@ export function listBackups(backupsDir) {
   for (const name of names.sort().reverse()) {
     const dir = path.join(backupsDir, name);
     const manifest = readManifest(dir);
+    const at = manifest && Number.isFinite(manifest.at) ? manifest.at : null;
     out.push({
       name,
       dir,
-      at: manifest && Number.isFinite(manifest.at) ? manifest.at : null,
+      at,
+      // The local time of the snapshot. The directory name is UTC on purpose,
+      // so a fresh snapshot must never look like an old one.
+      atLocal: manifest && typeof manifest.atLocal === 'string' && manifest.atLocal !== ''
+        ? manifest.atLocal
+        : (at === null ? null : backupLocalTime(at)),
       bytes: manifest && Number.isFinite(manifest.bytes) ? manifest.bytes : null,
+      files: manifest && Array.isArray(manifest.files) ? manifest.files.length : null,
       includePlugins: Boolean(manifest && manifest.includePlugins === true),
     });
   }
@@ -202,7 +311,7 @@ export function readManifest(backupDir) {
  *   maxBackups?: number,
  *   now?: number,
  * }} options
- * @returns {{ ok: boolean, dir: string|null, stamp: string|null, bytes: number, files: string[], includePlugins: boolean, pruned: string[], error: string|null }}
+ * @returns {{ ok: boolean, dir: string|null, stamp: string|null, at: number|null, atLocal: string|null, durationMs: number, bytes: number, files: string[], includePlugins: boolean, pruned: string[], error: string|null }}
  */
 export function createBackup({
   profileDir,
@@ -213,10 +322,14 @@ export function createBackup({
 } = {}) {
   const profile = typeof profileDir === 'string' ? profileDir.trim() : '';
   const root = typeof backupsDir === 'string' ? backupsDir.trim() : '';
+  const startedAt = Date.now();
   const base = {
     ok: false,
     dir: null,
     stamp: null,
+    at: null,
+    atLocal: null,
+    durationMs: 0,
     bytes: 0,
     files: [],
     includePlugins: includePlugins === true,
@@ -261,6 +374,9 @@ export function createBackup({
   const manifest = {
     stamp,
     at: Number(now),
+    // The wall clock of the machine: the directory name above is UTC, and
+    // without this line a fresh snapshot looks like an old leftover.
+    atLocal: backupLocalTime(Number(now)),
     profileDir: profile,
     includePlugins: includePlugins === true,
     files,
@@ -273,7 +389,18 @@ export function createBackup({
   }
 
   const pruned = pruneBackups(root, maxBackups);
-  return { ...base, ok: true, dir, stamp, bytes, files, pruned };
+  return {
+    ...base,
+    ok: true,
+    dir,
+    stamp,
+    at: Number(now),
+    atLocal: manifest.atLocal,
+    durationMs: Math.max(0, Date.now() - startedAt),
+    bytes,
+    files,
+    pruned,
+  };
 }
 
 /**

package/lib/blockers.js

@@ -0,0 +1,228 @@
+/**
+ * dsh-autorestart — ONE task count for every surface.
+ *
+ * A TASK is one conversation of the left sidebar: the session itself. A
+ * subagent belongs to the session that spawned it, so a session and its
+ * subagents are ONE task. The sidebar counts them once — so the bubble has
+ * to count them the same way.
+ *
+ * THE DEFECT THIS FIXES
+ *
+ * The real machine showed this:
+ *
+ *     blockedBy: [1] session  (父会话 A)
+ *                [2] subagent (父 = A)
+ *                [3] subagent (父 = B)
+ *
+ * The sidebar showed TWO busy conversations, and the bubble said "waiting for
+ * 3 tasks to finish". It counted every BLOCKER, so a parent session and its
+ * own subagent were counted twice.
+ *
+ * THE RULE (one rule, four surfaces)
+ *
+ *   - a session is a task of its own: its key is its own session id;
+ *   - a subagent belongs to the session that created it: its key is the
+ *     PARENT's session id, so a parent and its subagents are ONE task;
+ *   - a subagent whose parent is only known by its TITLE joins the session
+ *     with that title (the shutdown card reports the title but no id);
+ *   - a subagent with no known parent at all is a task of its own;
+ *   - a pending restart is not a task: it is what the shutdown waits for.
+ *
+ * THE TWO HALVES
+ *
+ * The browser half of this rule lives in `client.js`: the client is a CLASSIC
+ * script and cannot import an ES module. The two implementations MUST agree,
+ * and `test/task-count.test.mjs` runs the same cases through both — so a
+ * change on one side that is not made on the other fails the suite.
+ *
+ * ESM only, Node builtins only.
+ */
+
+/** The prefix of the key of a family that is known by its session id. */
+const SESSION_KEY = 'session:'
+
+/** The prefix of the key of a family that is only known by its title. */
+const TITLE_KEY = 'title:'
+
+/**
+ * One trimmed string field of a blocker.
+ *
+ * @param {any} entry
+ * @param {string} key
+ * @returns {string}
+ */
+function field(entry, key) {
+  if (!entry || typeof entry !== 'object') return ''
+  const value = entry[key]
+  return typeof value === 'string' ? value.trim() : ''
+}
+
+/**
+ * WHAT a blocker is: a session, a subagent or a pending restart.
+ *
+ * The kind is NOT the only evidence: an entry that names a parent session
+ * (`parentSessionId` / `parentTitle`) IS a subagent, whatever the Host
+ * called it.
+ *
+ * @param {any} entry
+ * @returns {'session'|'subagent'|'restart-pending'}
+ */
+export function blockerKind(entry) {
+  if (!entry || typeof entry !== 'object') return 'session'
+  if (entry.kind === 'restart-pending') return 'restart-pending'
+  if (entry.kind === 'subagent') return 'subagent'
+  if (entry.kind === 'session') return 'session'
+  if (field(entry, 'parentSessionId') !== '' || field(entry, 'parentTitle') !== '') return 'subagent'
+  return 'session'
+}
+
+/**
+ * The session id of a blocker.
+ *
+ * @param {any} entry
+ * @returns {string}
+ */
+function sessionIdOf(entry) {
+  if (!entry || typeof entry !== 'object') return ''
+  const value = entry.sessionId
+  return value == null ? '' : String(value).trim()
+}
+
+/**
+ * The title of the session a subagent belongs to.
+ *
+ * @param {any} entry
+ * @returns {string}
+ */
+function parentTitleOf(entry) {
+  return field(entry, 'parentTitle') || field(entry, 'label')
+}
+
+/**
+ * The title of a blocker (for a session: its own title).
+ *
+ * @param {any} entry
+ * @returns {string}
+ */
+function titleOf(entry) {
+  return field(entry, 'label') || field(entry, 'title')
+}
+
+/**
+ * The map "title of a session" → "session id" of the sessions in the list.
+ *
+ * It is the fallback for the surfaces that report the parent by its title
+ * only (the shutdown card): without it, the members of a team would become
+ * tasks of their own.
+ *
+ * @param {any[]} entries
+ * @returns {Map<string, string>}
+ */
+function sessionTitles(entries) {
+  const map = new Map()
+  for (const entry of entries) {
+    if (!entry || typeof entry !== 'object') continue
+    if (blockerKind(entry) === 'subagent') continue
+    const title = titleOf(entry)
+    if (title === '') continue
+    const id = sessionIdOf(entry)
+    if (id === '') continue
+    if (!map.has(title)) map.set(title, id)
+  }
+  return map
+}
+
+/**
+ * The key of the family every entry belongs to.
+ *
+ * One key per entry, in the order of the list ('' for an entry that is not a
+ * task at all).
+ *
+ * @param {any[]} entries the blockers the Host reported
+ * @returns {string[]}
+ */
+export function blockerTaskKeys(entries) {
+  const list = Array.isArray(entries) ? entries : []
+  const titles = sessionTitles(list)
+  const keys = []
+  for (let index = 0; index < list.length; index += 1) {
+    const entry = list[index]
+    if (!entry || typeof entry !== 'object') {
+      keys.push('')
+      continue
+    }
+    const kind = blockerKind(entry)
+    if (kind === 'restart-pending') {
+      // A pending restart is not a task: it is what the shutdown waits for.
+      keys.push('')
+      continue
+    }
+    if (kind === 'subagent') {
+      const parentId = field(entry, 'parentSessionId')
+      if (parentId !== '') {
+        keys.push(SESSION_KEY + parentId)
+        continue
+      }
+      const parentTitle = parentTitleOf(entry)
+      if (parentTitle !== '') {
+        const known = titles.get(parentTitle)
+        keys.push(known ? SESSION_KEY + known : TITLE_KEY + parentTitle)
+        continue
+      }
+      const own = sessionIdOf(entry)
+      keys.push(own !== '' ? SESSION_KEY + own : 'entry:' + index)
+      continue
+    }
+    const own = sessionIdOf(entry)
+    keys.push(own !== '' ? SESSION_KEY + own : 'entry:' + index)
+  }
+  return keys
+}
+
+/**
+ * How many TASKS the blockers are.
+ *
+ * A parent session and its own subagents are ONE task: the same number the
+ * left sidebar shows.
+ *
+ * @param {any[]} entries the blockers the Host reported
+ * @returns {number}
+ */
+export function countBlockerTasks(entries) {
+  const keys = blockerTaskKeys(entries)
+  const families = new Set()
+  for (const key of keys) {
+    if (key !== '') families.add(key)
+  }
+  return families.size
+}
+
+/**
+ * How many of those tasks are carried by SUBAGENTS ONLY.
+ *
+ * A task whose session is idle and whose subagent works is a task of the
+ * subagent — that is what the card tells the user ("2 of them are
+ * subagents"). A task whose session works itself is not one of them, even
+ * when it has subagents of its own.
+ *
+ * @param {any[]} entries the blockers the Host reported
+ * @returns {number}
+ */
+export function countSubagentTasks(entries) {
+  const list = Array.isArray(entries) ? entries : []
+  const keys = blockerTaskKeys(list)
+  const families = new Map()
+  list.forEach((entry, index) => {
+    const key = keys[index]
+    if (key === '') return
+    const family = families.get(key) || { session: false, subagent: false }
+    if (blockerKind(entry) === 'subagent') family.subagent = true
+    else family.session = true
+    families.set(key, family)
+  })
+  let count = 0
+  for (const family of families.values()) {
+    if (family.subagent && !family.session) count += 1
+  }
+  return count
+}

package/lib/checkpoint.js

@@ -106,6 +106,7 @@ const TOP_LEVEL_KEYS = new Set([
   'parkedGoals',
   'disarmedGoals',
   'seenFeatureVersions',
+  'onboarding',
   'sleep',
   'updatedAt',
 ]);
@@ -175,11 +176,84 @@ export function createEmptyState(now = Date.now()) {
     restart: null,
     sessions: {},
     seenFeatureVersions: {},
+    onboarding: null,
     sleep: null,
     updatedAt: now,
   };
 }
 
+/**
+ * Normalize the record of the one-time questions.
+ *
+ * The record is `{ feature, version, answeredAt, choice }`: WHICH question was
+ * answered (the id of the feature), the version of the question, when it was
+ * answered, and WHAT the user chose.
+ *
+ * A broken record is DROPPED: a question whose answer cannot be read is
+ * asked again — that is much better than a card that never comes back
+ * because of a half-written file.
+ *
+ * @param {unknown} raw
+ * @returns {{ onboarding: object|null, changed: boolean }}
+ */
+function normalizeOnboarding(raw) {
+  if (raw == null) return { onboarding: null, changed: false };
+  if (!isObject(raw)) return { onboarding: null, changed: true };
+  const feature = nullableString(raw.feature);
+  const version = nullableString(raw.version);
+  const choice = nullableString(raw.choice);
+  const answeredAt = nullableNumber(raw.answeredAt);
+  if (feature === null || version === null || choice === null || answeredAt === null) {
+    return { onboarding: null, changed: true };
+  }
+  // The values that were in effect BEFORE the answer: they are what the undo
+  // puts back.
+  const previous = isObject(raw.previous)
+    ? {
+      restartMode: nullableString(raw.previous.restartMode),
+      restartCommand: nullableString(raw.previous.restartCommand),
+    }
+    : null;
+  return { onboarding: { feature, version, choice, answeredAt, previous }, changed: false };
+}
+
+/**
+ * Record the answer of a one-time question.
+ *
+ * @param {object} state the checkpoint state (mutated in place)
+ * @param {{
+ *   feature?: string,
+ *   version?: string,
+ *   choice?: string,
+ *   previous?: { restartMode?: string, restartCommand?: string }|null,
+ *   now?: number,
+ * }} answer
+ * @returns {object} the recorded answer
+ */
+export function recordOnboarding(state, {
+  feature = '',
+  version = '',
+  choice = '',
+  previous = null,
+  now = Date.now(),
+} = {}) {
+  const record = {
+    feature: String(feature ?? ''),
+    version: String(version ?? ''),
+    choice: String(choice ?? ''),
+    answeredAt: Number.isFinite(Number(now)) ? Number(now) : Date.now(),
+    previous: previous && typeof previous === 'object'
+      ? {
+        restartMode: typeof previous.restartMode === 'string' ? previous.restartMode : null,
+        restartCommand: typeof previous.restartCommand === 'string' ? previous.restartCommand : null,
+      }
+      : null,
+  };
+  if (!state || typeof state !== 'object') return record;
+  state.onboarding = record;
+  return record;
+}
+
 /**
  * Normalize one persisted goal record. Unknown or wrong-typed fields are
  * dropped; `{ goal: null }` means "no goal recorded".
@@ -610,6 +684,14 @@ export function normalizeState(raw, now = Date.now()) {
     if (sleep.changed) repaired = true;
   }
 
+  // The answer of the one-time questions: it has to survive a restart, so a
+  // question is never asked twice.
+  if (raw.onboarding != null) {
+    const onboarding = normalizeOnboarding(raw.onboarding);
+    state.onboarding = onboarding.onboarding;
+    if (onboarding.changed) repaired = true;
+  }
+
   return { state, repaired };
 }
 
@@ -1271,6 +1353,71 @@ export function cancelRestart(state, { now = Date.now() } = {}) {
   return state;
 }
 
+/**
+ * Withdraw ONE requester from a pending restart — "cancel MY restart".
+ *
+ * A restart request is COALESCED: several sessions may ask for the same
+ * restart cycle, and every one of them is kept in `restart.requesters`. So
+ * "withdraw the restart I asked for" must NOT take the other requesters
+ * with it — that is how one session could cancel everybody's restart.
+ *
+ * The rules:
+ *
+ *   - the session must be a requester; if it is not, NOTHING is changed
+ *     (`reason: 'not-a-requester'`) — never a silent "cancel everything";
+ *   - the session id is required (`reason: 'no-session-id'` when it is
+ *     missing) — it is never guessed;
+ *   - the last requester leaving really cancels the restart (`cancelled:
+ *     true`), with the same cleanup as {@link cancelRestart};
+ *   - while other requesters remain, the restart stays and
+ *     `restart.bySessionId` is re-pointed at the first of them when it
+ *     pointed at the session that just left.
+ *
+ * Mutates `state` in place and returns the outcome.
+ *
+ * @param {object} state
+ * @param {{ sessionId?: string|null, now?: number }} options
+ * @returns {{ removed: boolean, cancelled: boolean, remaining: number, requesters: string[], reason: string }}
+ */
+export function cancelOwnRestart(state, { sessionId = null, now = Date.now() } = {}) {
+  const restart = isObject(state.restart) ? state.restart : null;
+  if (!restart) {
+    return { removed: false, cancelled: false, remaining: 0, requesters: [], reason: 'no-restart-pending' };
+  }
+  const requesters = normalizeRequesters(restart.requesters);
+  const ids = requesters.map((entry) => entry.sessionId);
+  const id = typeof sessionId === 'string' ? sessionId.trim() : '';
+  if (id === '') {
+    return { removed: false, cancelled: false, remaining: ids.length, requesters: ids, reason: 'no-session-id' };
+  }
+  // The requester list is the truth. The legacy fallback covers a state file
+  // that knows only `bySessionId` (no requesters at all).
+  const inList = ids.includes(id);
+  const legacyOnly = !inList && requesters.length === 0 && restart.bySessionId === id;
+  if (!inList && !legacyOnly) {
+    return { removed: false, cancelled: false, remaining: ids.length, requesters: ids, reason: 'not-a-requester' };
+  }
+  const kept = requesters.filter((entry) => entry.sessionId !== id);
+  if (kept.length === 0) {
+    // The LAST requester left: the restart really goes away.
+    cancelRestart(state, { now });
+    return { removed: true, cancelled: true, remaining: 0, requesters: [], reason: 'cancelled' };
+  }
+  // Other sessions are still waiting for this restart: it stays.
+  restart.requesters = kept;
+  if (restart.bySessionId === id) {
+    restart.bySessionId = kept[0].sessionId;
+  }
+  state.updatedAt = now;
+  return {
+    removed: true,
+    cancelled: false,
+    remaining: kept.length,
+    requesters: kept.map((entry) => entry.sessionId),
+    reason: 'withdrawn',
+  };
+}
+
 /**
  * Record the shutdown intent: "switch the machine off when the work is done".
  *