@qzsy/dsh-command-palette 1.3.1 → 1.4.1

package/scripts/verify-status.mjs

@@ -0,0 +1,780 @@
+#!/usr/bin/env node
+/**
+ * Standalone verification for the command palette's session status surface.
+ *
+ * Covers:
+ *  - loading the prebuilt browser module through a fake
+ *    `window.__ModuleLoader__` and instantiating its factory with React;
+ *  - the completion/failure badge matrix (pending > running > failure > unread);
+ *  - the `api-session/error` failure feed lifecycle and failure store;
+ *  - failure message normalization (whitespace collapse + 180 char cap);
+ *  - workspace aggregation priority/counts and subagent filtering;
+ *  - session-group summary segments and session row wiring;
+ *  - the production injection surface (inject/apply and hooks.sessionFailures).
+ *
+ * Usage (from the repository root):
+ *   node plugins/packages/dsh-command-palette/scripts/verify-status.mjs
+ *
+ * Exit code 0 means every check passed; 1 lists the failures.
+ *
+ * Only Node built-ins and the repository's own `react` dependency are used.
+ * The runtime file is never modified.
+ */
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { isDeepStrictEqual, inspect } from 'node:util';
+import vm from 'node:vm';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = resolve(HERE, '../../../..');
+const CLIENT_PATH = join(REPO_ROOT, 'plugins', 'packages', 'dsh-command-palette', 'runtime', 'client.js');
+const REPO_PACKAGE_JSON = join(REPO_ROOT, 'package.json');
+const EXPECTED_MODULE_ID = '@qzsy/dsh-command-palette';
+const MINUTE = 60 * 1000;
+const NOW = 1_700_000_000_000;
+
+// ---------------------------------------------------------------------------
+// Tiny check harness
+// ---------------------------------------------------------------------------
+
+const results = [];
+
+function oneLine(value, limit = 420) {
+  const flat = String(value).replace(/\s+/g, ' ').trim();
+  return flat.length > limit ? `${flat.slice(0, limit - 1)}…` : flat;
+}
+
+function formatValue(value) {
+  let rendered;
+  try {
+    rendered = inspect(value, {
+      depth: 6,
+      breakLength: Infinity,
+      compact: true,
+      maxArrayLength: 20,
+      maxStringLength: 300
+    });
+  } catch {
+    rendered = String(value);
+  }
+  return oneLine(rendered, 320);
+}
+
+function equal(actual, expected, what = 'value') {
+  if (!isDeepStrictEqual(actual, expected)) {
+    throw new Error(`${what}: expected ${formatValue(expected)}, got ${formatValue(actual)}`);
+  }
+}
+
+function truthy(value, what = 'condition') {
+  if (!value) throw new Error(`${what}: expected a truthy value, got ${formatValue(value)}`);
+}
+
+function check(name, body) {
+  try {
+    body();
+    results.push({ name, ok: true });
+    console.log(`PASS  ${name}`);
+  } catch (error) {
+    const detail = oneLine(error instanceof Error ? error.message : String(error));
+    results.push({ name, ok: false, detail });
+    console.log(`FAIL  ${name} :: ${detail}`);
+  }
+}
+
+function report() {
+  const failed = results.filter((entry) => !entry.ok);
+  const passed = results.length - failed.length;
+  console.log(`\nSummary: ${passed} passed, ${failed.length} failed, ${results.length} checks`);
+  if (failed.length === 0) {
+    console.log('Result: OK');
+    return 0;
+  }
+  console.log('\nFailed checks:');
+  for (const entry of failed) console.log(` - ${entry.name}: ${entry.detail}`);
+  console.log('\nResult: FAILED');
+  return 1;
+}
+
+// ---------------------------------------------------------------------------
+// Boot: capture the window.__ModuleLoader__ registration and run the factory
+// ---------------------------------------------------------------------------
+
+const requireFromRepo = createRequire(REPO_PACKAGE_JSON);
+
+function boot() {
+  let source;
+  try {
+    source = readFileSync(CLIENT_PATH, 'utf8');
+  } catch (error) {
+    throw new Error(`cannot read ${CLIENT_PATH}: ${error.message}`);
+  }
+
+  let registration = null;
+  const hadWindow = Object.prototype.hasOwnProperty.call(globalThis, 'window');
+  const previousWindow = globalThis.window;
+  globalThis.window = {
+    __ModuleLoader__: {
+      load(next) {
+        if (registration !== null) throw new Error('window.__ModuleLoader__.load was called more than once');
+        registration = next;
+      }
+    }
+  };
+  try {
+    vm.runInThisContext(source, { filename: CLIENT_PATH });
+  } finally {
+    if (hadWindow) globalThis.window = previousWindow;
+    else delete globalThis.window;
+  }
+
+  if (registration === null) throw new Error('runtime/client.js did not call window.__ModuleLoader__.load');
+  if (typeof registration.factory !== 'function') throw new Error('module registration has no factory');
+  const plugin = registration.factory((id) => requireFromRepo(id));
+  return { plugin, registration, source };
+}
+
+// ---------------------------------------------------------------------------
+// Stubs and fixtures
+// ---------------------------------------------------------------------------
+
+/** zh values for every key touched by the helpers under test. */
+const ZH = {
+  'status.running': '工作中',
+  'status.pending': '待处理',
+  'status.approval': '待批准',
+  'status.planReview': '待审阅',
+  'status.question': '待回答',
+  'status.done': '已完成',
+  'status.doneTitle': '已完成，尚未查看',
+  'status.error': '出错',
+  'status.errorTitle': '运行出错：{message}',
+  'status.errorUnreadTitle': '运行出错（尚未查看）：{message}',
+  'status.errorUnknown': '未知错误',
+  'status.runningCount': '{n} 个工作中',
+  'status.pendingCount': '{n} 个待处理',
+  'status.errorCount': '{n} 个出错',
+  'status.unreadCount': '{n} 个未读',
+  'group.active': '{n} 个进行中',
+  'group.pending': '{n} 个待处理',
+  'group.error': '{n} 个出错',
+  'group.unread': '{n} 个未读',
+  'item.untitled': '未命名',
+  'item.noWorkspace': '未分组',
+  'time.now': '刚刚',
+  'time.short.m': '{n}m',
+  'time.short.h': '{n}h',
+  'time.short.d': '{n}d',
+  'time.short.mo': '{n}mo',
+  'time.short.y': '{n}y'
+};
+
+function makeT() {
+  return function t(key, params) {
+    const template = ZH[key];
+    if (typeof template !== 'string') throw new Error(`stub t() is missing zh dictionary key: ${key}`);
+    if (params === undefined) return template;
+    return template.replace(/\{(\w+)\}/g, (match, name) => (
+      Object.prototype.hasOwnProperty.call(params, name) ? String(params[name]) : match
+    ));
+  };
+}
+
+const t = makeT();
+const at = (minutes) => NOW - minutes * MINUTE;
+
+function createFakeRemote() {
+  const handlers = new Map();
+  const subscriptions = [];
+  const disposals = [];
+
+  return {
+    remote: {
+      $on(event, handler) {
+        subscriptions.push(event);
+        if (!handlers.has(event)) handlers.set(event, new Set());
+        handlers.get(event).add(handler);
+        let disposed = false;
+        return () => {
+          if (disposed) return;
+          disposed = true;
+          disposals.push(event);
+          handlers.get(event)?.delete(handler);
+        };
+      }
+    },
+    subscriptions,
+    disposals,
+    emit(event, ...args) {
+      const listeners = handlers.get(event);
+      if (listeners === undefined || listeners.size === 0) throw new Error(`no live handler subscribed to ${event}`);
+      for (const listener of [...listeners]) listener(...args);
+    },
+    countHandlers() {
+      let total = 0;
+      for (const listeners of handlers.values()) total += listeners.size;
+      return total;
+    }
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Checks
+// ---------------------------------------------------------------------------
+
+function runChecks({ plugin, registration, source }) {
+  const api = plugin.__test;
+
+  // --- module loading and production surface ------------------------------
+
+  check('load: runtime registers exactly one module factory', () => {
+    equal(registration.id, EXPECTED_MODULE_ID, 'module id');
+    equal(typeof registration.factory, 'function', 'registration factory');
+  });
+
+  check('surface: plugin exposes inject and apply', () => {
+    truthy(Array.isArray(plugin.inject), 'inject is an array');
+    equal(typeof plugin.apply, 'function', 'apply');
+  });
+
+  check('surface: inject declares the remote capability', () => {
+    truthy(plugin.inject.includes('remote'), "inject contains 'remote'");
+  });
+
+  check('surface: __test exposes the documented helpers', () => {
+    const expected = [
+      'createFailureStore',
+      'installFailureFeed',
+      'normalizeFailureMessage',
+      'sessionBadge',
+      'sessionItems',
+      'sessionState',
+      'summarizeSessionRows',
+      'workspaceItems'
+    ].sort();
+    equal(Object.keys(api).sort(), expected, '__test keys');
+    for (const name of expected) equal(typeof api[name], 'function', `__test.${name}`);
+  });
+
+  check('source: PaletteDialog destructures useSessionFailures', () => {
+    truthy(
+      /function\s+PaletteDialog\s*\([^)]*\buseSessionFailures\b[^)]*\)/.test(source),
+      'PaletteDialog signature should destructure useSessionFailures'
+    );
+  });
+
+  check('source: injected() exposes hooks.sessionFailures', () => {
+    truthy(
+      /const\s+injected\s*=\s*\(\)\s*=>\s*\(\{[\s\S]*?hooks\s*:\s*\{[\s\S]*?\bsessionFailures\s*:\s*failures\.store\b/.test(source),
+      'injected() hooks should expose the failure store as sessionFailures'
+    );
+  });
+
+  check('source: apply wires the failure store and feed', () => {
+    truthy(
+      /const\s+failures\s*=\s*createFailureStore\(\)/.test(source),
+      'apply should create the failure store'
+    );
+    truthy(
+      /ctx\.effect\(\s*\(\)\s*=>\s*installFailureFeed\(ctx,\s*failures\)/.test(source),
+      'apply should install the failure feed through ctx.effect'
+    );
+  });
+
+  // --- normalizeFailureMessage -------------------------------------------
+
+  check('normalize: collapses whitespace and trims', () => {
+    equal(
+      api.normalizeFailureMessage('  network   timeout\n\twhile reading  '),
+      'network timeout while reading'
+    );
+  });
+
+  check('normalize: keeps a message exactly at the 180 character limit', () => {
+    const input = 'a'.repeat(180);
+    const output = api.normalizeFailureMessage(input);
+    equal(output.length, 180, 'length');
+    equal(output, input, 'message');
+  });
+
+  check('normalize: caps long messages at 180 characters with an ellipsis', () => {
+    const output = api.normalizeFailureMessage('b'.repeat(400));
+    equal(output.length, 180, 'length');
+    equal(output, `${'b'.repeat(179)}…`, 'message');
+  });
+
+  check('normalize: non-string input becomes an empty string', () => {
+    for (const input of [undefined, null, 42, true, {}, [], Symbol('x')]) {
+      equal(api.normalizeFailureMessage(input), '', `normalize(${String(input)})`);
+    }
+  });
+
+  // --- failure store + installFailureFeed lifecycle -----------------------
+
+  check('store: starts with an empty snapshot Map', () => {
+    const { store } = api.createFailureStore();
+    truthy(store.getSnapshot() instanceof Map, 'snapshot is a Map');
+    equal(store.getSnapshot().size, 0, 'snapshot size');
+  });
+
+  check('feed: subscribes to the four session lifecycle events', () => {
+    const fake = createFakeRemote();
+    const failures = api.createFailureStore();
+    const dispose = api.installFailureFeed({ remote: fake.remote }, failures);
+    equal(fake.subscriptions, [
+      'api-session/error',
+      'api-session/status',
+      'api-session/activity',
+      'api-session/removed'
+    ], 'subscribed events');
+    equal(fake.countHandlers(), 4, 'live handlers');
+    equal(typeof dispose, 'function', 'disposer');
+    dispose();
+  });
+
+  check('feed: api-session/error records a normalized failure per session', () => {
+    const fake = createFakeRemote();
+    const failures = api.createFailureStore();
+    api.installFailureFeed({ remote: fake.remote }, failures);
+    fake.emit('api-session/error', 's1', '  provider  500\nrequest failed ');
+    fake.emit('api-session/error', 's2', 'socket closed');
+    const snapshot = failures.store.getSnapshot();
+    equal(snapshot.size, 2, 'snapshot size');
+    equal(snapshot.get('s1').message, 'provider 500 request failed', 's1 message');
+    equal(typeof snapshot.get('s1').at, 'number', 's1 timestamp');
+    equal(snapshot.get('s2').message, 'socket closed', 's2 message');
+  });
+
+  check('feed: duplicate errors keep the latest message', () => {
+    const fake = createFakeRemote();
+    const failures = api.createFailureStore();
+    api.installFailureFeed({ remote: fake.remote }, failures);
+    fake.emit('api-session/error', 's1', 'first failure');
+    fake.emit('api-session/error', 's1', 'second failure');
+    const snapshot = failures.store.getSnapshot();
+    equal(snapshot.size, 1, 'snapshot size');
+    equal(snapshot.get('s1').message, 'second failure', 'latest message');
+  });
+
+  check('feed: a new turn (status running=true) clears the failure', () => {
+    const fake = createFakeRemote();
+    const failures = api.createFailureStore();
+    api.installFailureFeed({ remote: fake.remote }, failures);
+    fake.emit('api-session/error', 's1', 'boom');
+    fake.emit('api-session/status', 's1', true);
+    equal(failures.store.getSnapshot().has('s1'), false, 'failure cleared');
+  });
+
+  check('feed: status running=false does not clear the failure', () => {
+    const fake = createFakeRemote();
+    const failures = api.createFailureStore();
+    api.installFailureFeed({ remote: fake.remote }, failures);
+    fake.emit('api-session/error', 's1', 'boom');
+    fake.emit('api-session/status', 's1', false);
+    equal(failures.store.getSnapshot().get('s1').message, 'boom', 'failure retained');
+  });
+
+  check('feed: a new user prompt (activity) clears the failure', () => {
+    const fake = createFakeRemote();
+    const failures = api.createFailureStore();
+    api.installFailureFeed({ remote: fake.remote }, failures);
+    fake.emit('api-session/error', 's1', 'boom');
+    fake.emit('api-session/activity', 's1');
+    equal(failures.store.getSnapshot().has('s1'), false, 'failure cleared');
+  });
+
+  check('feed: a removed session clears the failure', () => {
+    const fake = createFakeRemote();
+    const failures = api.createFailureStore();
+    api.installFailureFeed({ remote: fake.remote }, failures);
+    fake.emit('api-session/error', 's1', 'boom');
+    fake.emit('api-session/removed', 's1');
+    equal(failures.store.getSnapshot().has('s1'), false, 'failure cleared');
+  });
+
+  check('feed: disposer removes every subscription and is idempotent', () => {
+    const fake = createFakeRemote();
+    const failures = api.createFailureStore();
+    const dispose = api.installFailureFeed({ remote: fake.remote }, failures);
+    dispose();
+    equal(fake.countHandlers(), 0, 'live handlers after dispose');
+    equal([...fake.disposals].sort(), [
+      'api-session/activity',
+      'api-session/error',
+      'api-session/removed',
+      'api-session/status'
+    ], 'disposed events');
+    dispose();
+  });
+
+  check('feed: missing ctx.remote returns a no-op disposer', () => {
+    for (const ctx of [undefined, null, {}, { remote: {} }, { remote: { $on: 'not-a-function' } }]) {
+      const dispose = api.installFailureFeed(ctx, api.createFailureStore());
+      equal(typeof dispose, 'function', 'disposer');
+      dispose();
+      dispose();
+    }
+  });
+
+  check('feed: empty/invalid ids and messages are contained', () => {
+    const fake = createFakeRemote();
+    const failures = api.createFailureStore();
+    api.installFailureFeed({ remote: fake.remote }, failures);
+    for (const sessionId of ['', null, 42, {}, []]) {
+      fake.emit('api-session/error', sessionId, 'ignored');
+    }
+    equal(failures.store.getSnapshot().size, 0, 'no entries for invalid ids');
+    fake.emit('api-session/error', 's-ok', undefined);
+    fake.emit('api-session/error', 's-ok2', { message: 'not a string' });
+    const snapshot = failures.store.getSnapshot();
+    equal(snapshot.get('s-ok').message, '', 'undefined message normalizes to empty');
+    equal(snapshot.get('s-ok2').message, '', 'object message normalizes to empty');
+    for (const sessionId of ['', null, 42]) {
+      failures.record(sessionId, 'ignored');
+      failures.clear(sessionId);
+    }
+  });
+
+  // --- badge state matrix -------------------------------------------------
+
+  const STALE_FAILURE = { message: 'stale network error', at: NOW };
+  const FAILURE = { message: 'provider 500', at: NOW };
+  const badge = (row, status, failure) => api.sessionBadge(row, status, failure, t);
+
+  check('badge: pending approval outranks running, failure and unread', () => {
+    equal(
+      badge({ running: true }, { running: true, pendingInteraction: { kind: 'approval' }, completionUnread: true }, FAILURE),
+      { tone: 'pending', label: '待批准' }
+    );
+  });
+
+  check('badge: pending plan review outranks running, failure and unread', () => {
+    equal(
+      badge({ running: true }, { running: true, pendingInteraction: { kind: 'plan-review' }, completionUnread: true }, FAILURE),
+      { tone: 'pending', label: '待审阅' }
+    );
+  });
+
+  check('badge: pending question outranks running, failure and unread', () => {
+    equal(
+      badge({ running: true }, { running: true, pendingInteraction: { kind: 'question' }, completionUnread: true }, FAILURE),
+      { tone: 'pending', label: '待回答' }
+    );
+  });
+
+  check('badge: other pending kinds fall back to the pending label', () => {
+    equal(
+      badge({ running: true }, { running: true, pendingInteraction: { kind: 'permission' }, completionUnread: true }, FAILURE),
+      { tone: 'pending', label: '待处理' }
+    );
+  });
+
+  check('badge: running outranks a stale failure and unread completion', () => {
+    equal(
+      badge({}, { running: true, completionUnread: true }, STALE_FAILURE),
+      { tone: 'running', label: '工作中' }
+    );
+  });
+
+  check('badge: legacy row.running still outranks a failure', () => {
+    equal(
+      badge({ running: true }, undefined, FAILURE),
+      { tone: 'running', label: '工作中' }
+    );
+  });
+
+  check('badge: a failure without unread completion is an error badge with the plain tooltip', () => {
+    const expected = { tone: 'error', label: '出错', title: '运行出错：provider 500' };
+    equal(badge({}, undefined, FAILURE), expected, 'failure without a status snapshot');
+    equal(badge({}, { completionUnread: false }, FAILURE), expected, 'failure with viewed completion');
+  });
+
+  check('badge: a failure with unread completion uses the unread tooltip', () => {
+    equal(
+      badge({}, { completionUnread: true }, FAILURE),
+      { tone: 'error', label: '出错', title: '运行出错（尚未查看）：provider 500' }
+    );
+  });
+
+  check('badge: an empty failure message falls back to the unknown-error text', () => {
+    equal(
+      badge({}, {}, { message: '', at: NOW }),
+      { tone: 'error', label: '出错', title: '运行出错：未知错误' }
+    );
+  });
+
+  check('badge: unread success is a done badge with the unread tooltip', () => {
+    equal(
+      badge({}, { completionUnread: true }, undefined),
+      { tone: 'done', label: '已完成', title: '已完成，尚未查看' }
+    );
+  });
+
+  check('badge: viewed success has no badge', () => {
+    equal(badge({}, { completionUnread: false }, undefined), null, 'viewed completion');
+    equal(badge({}, {}, undefined), null, 'status without unread completion');
+    equal(badge({}, undefined, undefined), null, 'no status and no failure');
+  });
+
+  // --- session group summary ---------------------------------------------
+
+  check('summary: emits present tones in running, pending, error, unread order', () => {
+    equal(
+      api.summarizeSessionRows([
+        { badge: { tone: 'error' } },
+        { badge: { tone: 'done' } },
+        { badge: { tone: 'pending' } },
+        { badge: { tone: 'running' } },
+        { badge: { tone: 'error' } }
+      ], t),
+      ['1 个进行中', '1 个待处理', '2 个出错', '1 个未读']
+    );
+  });
+
+  check('summary: omits tones that are not present', () => {
+    equal(
+      api.summarizeSessionRows([
+        { badge: { tone: 'running' } },
+        { badge: { tone: 'running' } },
+        { badge: { tone: 'done' } }
+      ], t),
+      ['2 个进行中', '1 个未读']
+    );
+  });
+
+  check('summary: returns no segments for empty or badge-less rows', () => {
+    equal(api.summarizeSessionRows([], t), []);
+    equal(api.summarizeSessionRows([{}, { badge: null }, { badge: { tone: 'unknown' } }], t), []);
+  });
+
+  // --- workspace aggregation ---------------------------------------------
+
+  const sessions = {
+    byId: {
+      p1: { id: 'p1', updatedAt: at(2) },
+      p2: { id: 'p2', updatedAt: at(1) },
+      e1: { id: 'e1', updatedAt: at(3) },
+      e4: { id: 'e4', updatedAt: at(4) },
+      r1: { id: 'r1', updatedAt: at(5) },
+      u1: { id: 'u1', updatedAt: at(6) },
+      e2: { id: 'e2', updatedAt: at(10) },
+      e3: { id: 'e3', updatedAt: at(12) },
+      r2: { id: 'r2', updatedAt: at(2) },
+      ux: { id: 'ux', updatedAt: at(1) },
+      r3: { id: 'r3', updatedAt: at(3) },
+      r4: { id: 'r4', updatedAt: at(8) },
+      u2: { id: 'u2', updatedAt: at(1) },
+      u3: { id: 'u3', updatedAt: at(20) },
+      u4: { id: 'u4', updatedAt: at(6) },
+      u5: { id: 'u5', updatedAt: at(7) },
+      v1: { id: 'v1', updatedAt: at(9) },
+      n1: { id: 'n1', updatedAt: at(5) },
+      sub1: { id: 'sub1', updatedAt: at(1), origin: 'subagent' }
+    }
+  };
+  const statuses = new Map([
+    ['p1', { pendingInteraction: { kind: 'approval' } }],
+    ['p2', { pendingInteraction: { kind: 'question' } }],
+    ['r1', { running: true }],
+    ['u1', { completionUnread: true }],
+    ['r2', { running: true }],
+    ['ux', { completionUnread: true }],
+    ['r3', { running: true }],
+    ['r4', { running: true }],
+    ['u2', { completionUnread: true }],
+    ['u3', { completionUnread: true }],
+    ['u4', { completionUnread: true }],
+    ['u5', { completionUnread: true }],
+    ['n1', { completionUnread: true }],
+    ['sub1', { pendingInteraction: { kind: 'approval' } }]
+  ]);
+  const failures = new Map([
+    ['e1', { message: 'boom one', at: NOW }],
+    ['e4', { message: 'boom four', at: NOW }],
+    ['e2', { message: 'boom two', at: NOW }],
+    ['e3', { message: 'boom three', at: NOW }]
+  ]);
+  const workspaces = {
+    items: [
+      {
+        workspaceId: 'ws-pending',
+        path: 'D:/projects/ws-pending',
+        title: 'Pending',
+        sessionIds: ['p1', 'p2', 'e1', 'e4', 'r1', 'u1'],
+        createdAt: new Date(at(60 * 24 * 30)).toISOString()
+      },
+      {
+        workspaceId: 'ws-error',
+        path: 'D:/projects/ws-error',
+        title: 'Error',
+        sessionIds: ['e2', 'e3', 'r2', 'ux'],
+        createdAt: new Date(at(60 * 24 * 30)).toISOString()
+      },
+      {
+        workspaceId: 'ws-running',
+        path: 'D:/projects/ws-running',
+        title: 'Running',
+        sessionIds: ['r3', 'r4', 'u2', 'u3'],
+        createdAt: new Date(at(60 * 24 * 30)).toISOString()
+      },
+      {
+        workspaceId: 'ws-unread',
+        path: 'D:/projects/ws-unread',
+        title: 'Unread',
+        sessionIds: ['u4', 'u5'],
+        // Newer than every session on purpose: recency/meta must use sessions.
+        createdAt: new Date(at(1)).toISOString()
+      },
+      {
+        workspaceId: 'ws-quiet',
+        path: 'D:/projects/ws-quiet',
+        title: 'Quiet',
+        sessionIds: ['v1', 'missing-session'],
+        createdAt: new Date(at(60 * 24 * 30)).toISOString()
+      },
+      {
+        workspaceId: 'ws-subagent',
+        path: 'D:/projects/ws-subagent',
+        title: 'Subagent',
+        sessionIds: ['n1', 'sub1'],
+        createdAt: new Date(at(60 * 24 * 30)).toISOString()
+      }
+    ],
+    archivedSessionIds: []
+  };
+  const workspaceRows = api.workspaceItems(sessions, workspaces, NOW, t, 'D:/projects', statuses, failures, false, undefined);
+  const workspaceById = new Map(workspaceRows.map((item) => [item.workspaceId, item]));
+
+  check('workspaces: pending outranks error/running/unread and counts pending sessions', () => {
+    const item = workspaceById.get('ws-pending');
+    truthy(item !== undefined, 'ws-pending row');
+    equal(item.badge, { tone: 'pending', label: '2 个待处理' }, 'badge');
+  });
+
+  check('workspaces: error outranks running/unread and counts failed sessions', () => {
+    const item = workspaceById.get('ws-error');
+    truthy(item !== undefined, 'ws-error row');
+    equal(item.badge, { tone: 'error', label: '2 个出错' }, 'badge');
+  });
+
+  check('workspaces: running outranks unread and counts running sessions', () => {
+    const item = workspaceById.get('ws-running');
+    truthy(item !== undefined, 'ws-running row');
+    equal(item.badge, { tone: 'running', label: '2 个工作中' }, 'badge');
+  });
+
+  check('workspaces: unread-only workspace aggregates to done with its count', () => {
+    const item = workspaceById.get('ws-unread');
+    truthy(item !== undefined, 'ws-unread row');
+    equal(item.badge, { tone: 'done', label: '2 个未读' }, 'badge');
+  });
+
+  check('workspaces: quiet workspace has no aggregate badge', () => {
+    const item = workspaceById.get('ws-quiet');
+    truthy(item !== undefined, 'ws-quiet row');
+    equal(item.badge, null, 'badge');
+  });
+
+  check('workspaces: newest session drives recency/meta instead of workspace.createdAt', () => {
+    const item = workspaceById.get('ws-unread');
+    truthy(item !== undefined, 'ws-unread row');
+    equal(item.recency, at(6), 'recency from newest session');
+    equal(item.meta, '6m', 'relative meta from newest session');
+  });
+
+  check('workspaces: subagent sessions are excluded when includeSubagents is false', () => {
+    const item = workspaceById.get('ws-subagent');
+    truthy(item !== undefined, 'ws-subagent row');
+    equal(item.badge, { tone: 'done', label: '1 个未读' }, 'badge');
+    equal(item.recency, at(5), 'recency ignores the subagent session');
+    equal(item.meta, '5m', 'meta ignores the subagent session');
+  });
+
+  check('workspaces: includeSubagents=true lets a newer subagent drive the aggregate', () => {
+    const rows = api.workspaceItems(sessions, workspaces, NOW, t, 'D:/projects', statuses, failures, true, undefined);
+    const item = rows.find((entry) => entry.workspaceId === 'ws-subagent');
+    truthy(item !== undefined, 'ws-subagent row');
+    equal(item.badge, { tone: 'pending', label: '1 个待处理' }, 'badge');
+    equal(item.recency, at(1), 'recency includes the subagent session');
+    equal(item.meta, '1m', 'meta includes the subagent session');
+  });
+
+  // --- sessionItems wiring ------------------------------------------------
+
+  const sessionRowFixtures = {
+    byId: {
+      s1: { id: 's1', updatedAt: at(3), title: '  Alpha  ', cwd: 'D:/projects/alpha' },
+      s2: { id: 's2', updatedAt: at(2), title: '', displayTitle: 'Beta', cwd: 'D:/projects/beta' },
+      sBlank: { id: 'sBlank', updatedAt: at(1), blank: true, title: 'Blank', cwd: 'D:/projects/blank' },
+      sArchived: { id: 'sArchived', updatedAt: NOW, title: 'Archived', cwd: 'D:/projects/archived' }
+    }
+  };
+  const sessionRowWorkspaces = {
+    items: [
+      {
+        workspaceId: 'ws-alpha',
+        path: 'D:/projects/alpha',
+        title: 'Alpha workspace',
+        sessionIds: ['s1', 'sArchived'],
+        createdAt: new Date(NOW).toISOString()
+      }
+    ],
+    archivedSessionIds: ['sArchived']
+  };
+  const sessionRowStatuses = new Map([['s1', { running: true }]]);
+  const sessionRowFailures = new Map([['s2', { message: 'provider 500', at: NOW }]]);
+  const sessionRows = api.sessionItems(
+    sessionRowFixtures,
+    sessionRowWorkspaces,
+    NOW,
+    t,
+    sessionRowStatuses,
+    sessionRowFailures,
+    undefined
+  );
+
+  check('sessions: filters blank and archived rows', () => {
+    equal(
+      sessionRows.map((row) => row.sessionId).sort(),
+      ['s1', 's2'],
+      'visible session ids'
+    );
+  });
+
+  check('sessions: wires the failure feed into an error badge', () => {
+    const row = sessionRows.find((entry) => entry.sessionId === 's2');
+    truthy(row !== undefined, 's2 row');
+    equal(row.badge, { tone: 'error', label: '出错', title: '运行出错：provider 500' }, 'badge');
+    equal(row.failure, { message: 'provider 500', at: NOW }, 'failure payload');
+  });
+
+  check('sessions: wires the status snapshot into a running badge', () => {
+    const row = sessionRows.find((entry) => entry.sessionId === 's1');
+    truthy(row !== undefined, 's1 row');
+    equal(row.badge, { tone: 'running', label: '工作中' }, 'badge');
+    equal(row.status, { running: true }, 'status payload');
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Entry point
+// ---------------------------------------------------------------------------
+
+function main() {
+  let booted;
+  try {
+    booted = boot();
+  } catch (error) {
+    const message = oneLine(error instanceof Error ? error.message : String(error));
+    console.log(`FAIL  boot: ${message}`);
+    console.log('\nSummary: 0 passed, 1 failed, 1 check');
+    console.log(`\nFailed checks:\n - boot: ${message}`);
+    return 1;
+  }
+  runChecks(booted);
+  return report();
+}
+
+process.exitCode = main();