dsh-autorestart 0.6.2 → 0.7.0

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".
  *

package/lib/diagnostics.js

@@ -0,0 +1,180 @@
+/**
+ * dsh-autorestart — THE DIAGNOSTICS BEHIND "REPORT A PROBLEM".
+ *
+ * When something goes wrong, the user should be able to hand us the facts in
+ * one click — without writing anything down by hand and without leaking
+ * anything private.
+ *
+ * There is exactly ONE generator (`buildDiagnostics`): the host builds the
+ * text, the browser copies it. Two generators would drift, and a drifted
+ * diagnostic is worse than none.
+ *
+ * WHAT IS IN IT: the plugin version, the platform, whether this is the
+ * desktop client, how the host was started (the mode AND the evidence the
+ * verdict rests on), who supervises it, the restart mode, and the verdict of
+ * the last restart (with the checks that failed).
+ *
+ * WHAT IS NEVER IN IT: the access token, a URL that carries a token, or any
+ * secret. The generator only copies the fields it knows, so a token cannot
+ * leak through a field nobody thought about — and everything that IS copied
+ * goes through the redaction again.
+ *
+ * ESM only, Node builtins only.
+ */
+
+/** The mailbox that works when GitHub does not. */
+export const SUPPORT_EMAIL = '252170229@qq.com'
+
+/** Where the "new issue" page lives. */
+export const ISSUE_URL_BASE = 'https://github.com/Eason-22/dsh-autorestart/issues/new'
+
+/** The body of a pre-filled issue must stay short: URLs have a length limit. */
+export const DIAGNOSTIC_BODY_LIMIT = 800
+
+/**
+ * The patterns that must never survive into a diagnostic.
+ *
+ * They cover the access token of the instance, the query parameters that
+ * carry it, and the usual "key: value" secrets.
+ */
+const SECRET_PATTERNS = Object.freeze([
+  /([?&](?:token|access[_-]?token|api[_-]?key|apikey|secret|password|auth|authorization)=)[^&\s"'<>]+/gi,
+  /("|')?(?:token|access[_-]?token|api[_-]?key|apikey|secret|password|authorization)("|')?\s*[:=]\s*(?:"[^"]*"|'[^']*'|[^\s,;}\]]+)/gi,
+  /\bBearer\s+[A-Za-z0-9._~+/-]{8,}=*/gi,
+])
+
+/**
+ * Remove anything that looks like a secret from a piece of text.
+ *
+ * @param {unknown} value
+ * @returns {string}
+ */
+export function redactSecrets(value) {
+  let text = typeof value === 'string' ? value : String(value ?? '')
+  for (const pattern of SECRET_PATTERNS) {
+    text = text.replace(pattern, '[redacted]')
+  }
+  return text
+}
+
+/**
+ * Shorten a path: the last four segments are kept (the user name may stay),
+ * everything before them is cut.
+ *
+ * @param {unknown} value
+ * @returns {string}
+ */
+export function truncatePath(value) {
+  const text = typeof value === 'string' ? value.trim() : ''
+  if (text === '') return ''
+  const parts = text.split(/[\\/]+/).filter((part) => part !== '')
+  if (parts.length <= 4) return text
+  return '…/' + parts.slice(-4).join('/')
+}
+
+/**
+ * Cut a text to a length limit (the issue body has to stay short).
+ *
+ * @param {string} text
+ * @param {number} [limit]
+ * @returns {string}
+ */
+export function truncateBody(text, limit = DIAGNOSTIC_BODY_LIMIT) {
+  const source = typeof text === 'string' ? text : ''
+  const max = Number.isFinite(Number(limit)) && Number(limit) > 0 ? Math.trunc(Number(limit)) : DIAGNOSTIC_BODY_LIMIT
+  if (source.length <= max) return source
+  return source.slice(0, Math.max(0, max - 1)) + '…'
+}
+
+/**
+ * The pre-filled "new issue" URL.
+ *
+ * @param {string} base
+ * @param {string} title
+ * @param {string} body
+ * @returns {string}
+ */
+export function buildIssueUrl(base, title, body) {
+  const root = typeof base === 'string' && base.trim() !== '' ? base.trim() : ISSUE_URL_BASE
+  const safeTitle = truncateBody(redactSecrets(title), 200)
+  const safeBody = truncateBody(redactSecrets(body), DIAGNOSTIC_BODY_LIMIT)
+  return root + '?title=' + encodeURIComponent(safeTitle) + '&body=' + encodeURIComponent(safeBody)
+}
+
+/**
+ * The `mailto:` link (the fallback when there is no GitHub account).
+ *
+ * @param {string} email
+ * @param {string} subject
+ * @param {string} body
+ * @returns {string}
+ */
+export function buildMailtoUrl(email, subject, body) {
+  const to = typeof email === 'string' && email.trim() !== '' ? email.trim() : SUPPORT_EMAIL
+  const safeSubject = truncateBody(redactSecrets(subject), 200)
+  const safeBody = truncateBody(redactSecrets(body), DIAGNOSTIC_BODY_LIMIT)
+  return 'mailto:' + to + '?subject=' + encodeURIComponent(safeSubject) + '&body=' + encodeURIComponent(safeBody)
+}
+
+/**
+ * Read one field out of a payload, without ever throwing.
+ *
+ * @param {any} source
+ * @param {string} key
+ * @param {any} [fallback]
+ * @returns {any}
+ */
+function field(source, key, fallback = '') {
+  if (!source || typeof source !== 'object') return fallback
+  const value = source[key]
+  return value === undefined || value === null ? fallback : value
+}
+
+/**
+ * The diagnostic text of this host.
+ *
+ * It is a PURE function of the payload: the same facts always produce the
+ * same text, and nothing outside the fields listed below can ever end up in
+ * it.
+ *
+ * @param {{
+ *   version?: string,
+ *   platform?: string,
+ *   hostKind?: string,
+ *   isDesktopApp?: boolean,
+ *   startup?: { mode?: string, kind?: string, evidence?: string },
+ *   supervisor?: { mode?: string, kind?: string },
+ *   restartMode?: string,
+ *   lastRestart?: { result?: string, failedChecks?: string[] },
+ *   stateDir?: string,
+ * }} [payload]
+ * @returns {string}
+ */
+export function buildDiagnostics(payload = {}) {
+  const source = payload && typeof payload === 'object' ? payload : {}
+  const startup = field(source, 'startup', {})
+  const supervisor = field(source, 'supervisor', {})
+  const lastRestart = field(source, 'lastRestart', {})
+  const failedChecks = Array.isArray(field(lastRestart, 'failedChecks', []))
+    ? field(lastRestart, 'failedChecks', []).map((check) => redactSecrets(String(check)))
+    : []
+
+  const lines = [
+    '--- dsh-autorestart diagnostics ---',
+    'plugin version: ' + redactSecrets(field(source, 'version', 'unknown')),
+    'platform: ' + redactSecrets(field(source, 'platform', 'unknown')),
+    'host kind: ' + redactSecrets(field(source, 'hostKind', 'unknown')),
+    'desktop client: ' + (field(source, 'isDesktopApp', false) === true ? 'yes' : 'no'),
+    'startup mode: ' + redactSecrets(field(startup, 'mode', 'unknown')),
+    'startup evidence: ' + redactSecrets(field(startup, 'evidence', 'unknown')),
+    'supervisor mode: ' + redactSecrets(field(supervisor, 'mode', 'unknown')),
+    'supervisor kind: ' + redactSecrets(field(supervisor, 'kind', 'unknown')),
+    'restart mode: ' + redactSecrets(field(source, 'restartMode', 'unknown')),
+    'last restart result: ' + redactSecrets(field(lastRestart, 'result', 'unknown')),
+    'last restart failed checks: ' + (failedChecks.length > 0 ? failedChecks.join(', ') : 'none'),
+  ]
+  const stateDir = truncatePath(field(source, 'stateDir', ''))
+  if (stateDir !== '') lines.push('dsh home: ' + redactSecrets(stateDir))
+  lines.push('--- end ---')
+  return lines.join('\n')
+}