@dsh-workbench/shared 0.3.6 → 0.3.7

package/src/components/Form.tsx

@@ -1,5 +1,5 @@
 import { h, useEffect, useRef, useState } from '../lib/react.js';
-import type { FormProps } from './FormTypes.js';
+import type { FormProps, FormValues } from './FormTypes.js';
 import { FormActions } from './FormActions.js';
 import { FormRows } from './FormRows.js';
 import { Note } from './Note.js';
@@ -16,13 +16,15 @@ import './Form.css';
 
 /**
  * 整张表单：`fields` 进，行、错误、操作区、（被挡住的）提交都由它安排 —— 它自己一个值都不存，
- * 值仍归调用点的 model（`value` 只读给校验看）。
+ * 值仍归调用点（`value` 与 `onChange` 写在字段配置的同一格里，`Form` 只是把两者原样递给那一格的 `control`）。
+ * 写了 `Form<Values>` 就按 `Values` 把每一格的键与值类型钉住（`Values` 里会 `visible: false` 的键写成可选键）；
+ * 不写就是默认档，键值都不钉。
  * 还没提交过时一格错都不显示；第一次提交之后每次渲染重算，改好了当场消。
  * 提交那一拍永远先算一遍：有错就不调 `onSubmit`，并把第一个有错的 `FormRow` 带进视口、聚焦它里面的控件。
  * 回车与点提交钮走的是同一条路：真 `<form>` 的隐式提交在**只有一个文本框**时也会 fire，所以 `busy` / `disabled` 时回车同样不提交。
  * 调用点只管数据与语义：行怎么排、错误摆哪、什么时候校验、按钮在哪，这里没有口子。
- * @param props.fields - 每格的键 / 标签 / 值 / 校验 / 控件；`visible: false` 的那格当它不存在（不渲染、不校验、不进 `values`）。
- * @param props.onSubmit - 校验全过的那一拍，回的是从 `fields` 现取的键值表；被挡住时不会被调。
+ * @param props.fields - 每格的键 / 标签 / 值 / 值怎么改（`onChange`）/ 校验 / 控件；`visible: false` 的那格当它不存在（不渲染、不校验、不进 `values`）。
+ * @param props.onSubmit - 校验全过的那一拍，回的是从 `fields` 现取的键值表（按 `visibleFieldsOf` 过滤过，不可见那格不在里面）；被挡住时不会被调。
  * @param props.submit - 提交钮文案；`busyLabel` 是提交中换的那句，不给就沿用 `label`。
  * @param props.cancel - 取消钮；给了就排在提交钮左边，`busy` 时一起禁用。
  * @param props.extra - 其余动作（default / danger），排在最左，`busy` 时一起禁用。
@@ -31,7 +33,7 @@ import './Form.css';
  * @param props.problem - 整表级那句错（提交失败），落在行与操作区之间；不给就不画。
  * @returns 一个 `<form>`（`noValidate`：报错形状归 `FormRow`，不走浏览器的气泡）。
  */
-export function Form(props: FormProps) {
+export function Form<Values extends object = FormValues>(props: FormProps<Values>) {
   const { fields, onSubmit, submit, cancel, extra, busy = false, disabled = false, problem } = props;
   const [done, setDone] = useState(false);
   const [reveal, setReveal] = useState(0);

package/src/components/FormNodes.tsx

@@ -1,7 +1,7 @@
 import type { ReactNode } from '../lib/react.js';
 import { h } from '../lib/react.js';
 import type { FormAction } from './FormActions.js';
-import type { FormField, FormValue } from './FormTypes.js';
+import type { FormField, FormFieldOf, FormValues } from './FormTypes.js';
 import { FormRow } from './FormRows.js';
 
 /**
@@ -9,7 +9,9 @@ import { FormRow } from './FormRows.js';
  * @param fields - 表单的字段清单。
  * @returns 保序的新数组，`visible` 不给或为 `true` 的都在；全不可见时给空数组。
  */
-export function visibleFieldsOf(fields: readonly FormField[]): readonly FormField[] {
+export function visibleFieldsOf<Values extends object>(
+  fields: readonly FormFieldOf<Values>[],
+): readonly FormFieldOf<Values>[] {
   return fields.filter((field) => field.visible !== false);
 }
 
@@ -19,7 +21,7 @@ export function visibleFieldsOf(fields: readonly FormField[]): readonly FormFiel
  * @param fields - 表单的字段清单（通常是已经过滤过可见性的那份）。
  * @returns 出问题的键的清单、按首次出现顺序去重；缺失的键一律记成空串（报的时候印成 `（空 key）`），空表给空数组。
  */
-export function duplicateKeysOf(fields: readonly FormField[]): readonly string[] {
+export function duplicateKeysOf(fields: readonly { readonly key: string }[]): readonly string[] {
   const seen = new Set<string>();
   const duplicated = new Set<string>();
   for (const field of fields) {
@@ -39,7 +41,7 @@ export function duplicateKeysOf(fields: readonly FormField[]): readonly string[]
  * 形式与理由同 `FormActions` 里那颗多出来的 `primary`：装配的小错不该让 `CardBoundary` 把用户的整张卡变空白。
  * @param fields - 表单的字段清单（通常是已经过滤过可见性的那份）。
  */
-export function reportDuplicateKeys(fields: readonly FormField[]): void {
+export function reportDuplicateKeys(fields: readonly { readonly key: string }[]): void {
   const duplicated = duplicateKeysOf(fields);
   if (duplicated.length === 0) return;
   const named = duplicated.map((key) => (key === '' ? '（空 key）' : key));
@@ -54,10 +56,12 @@ export function reportDuplicateKeys(fields: readonly FormField[]): void {
  * @param fields - 表单的字段清单；取的就是它们的 `value`，`value` 是数组的那格（多选）原样带出、不复制。
  * @returns 键为字段 `key`、值为该格 `value` 的表；`fields` 为空时给空表，不是 `undefined`。
  */
-export function formValuesOf(fields: readonly FormField[]): Readonly<Record<string, FormValue>> {
-  const values: Record<string, FormValue> = {};
+export function formValuesOf<Values extends object>(
+  fields: readonly FormFieldOf<Values>[],
+): Readonly<Values> {
+  const values: Record<string, unknown> = {};
   for (const field of fields) values[field.key] = field.value;
-  return values;
+  return values as Readonly<Values>;
 }
 
 /**
@@ -68,19 +72,26 @@ export function formValuesOf(fields: readonly FormField[]): Readonly<Record<stri
  * @param show - 提交过没有；false 时全给 `undefined`，true 时逐格调 `field.validate` 并按真值收。
  * @returns 键为 `key`、值为那句文案或 `undefined` 的表；没给 `validate` 的格子也是 `undefined`。
  */
-export function formProblemsOf(
-  fields: readonly FormField[],
+export function formProblemsOf<Values extends object>(
+  fields: readonly FormFieldOf<Values>[],
   show: boolean,
 ): Readonly<Record<string, ReactNode | undefined>> {
   const values = formValuesOf(fields);
   const problems: Record<string, ReactNode | undefined> = {};
   for (const field of fields) {
-    const found = show ? field.validate?.(field.value, values) : undefined;
+    const found = show ? problemOf(field, values) : undefined;
     problems[field.key] = found ? found : undefined;
   }
   return problems;
 }
 
+function problemOf<K extends string, V, Vals extends object>(
+  field: FormField<K, V, Vals>,
+  values: Readonly<Vals>,
+): ReactNode | undefined {
+  return field.validate?.(field.value, values);
+}
+
 /**
  * 按字段顺序取第一处错误 —— 提交被挡住时要带进视口的就是这一格。
  * 判的是**真值**（与 `formProblemsOf` 同一口径）：假值那种"错误文案"渲染出来本来就是空的，不算错。
@@ -88,19 +99,19 @@ export function formProblemsOf(
  * @param problems - `formProblemsOf` 那张表，也可以是调用点自己拼的（同样按真值判）。
  * @returns 第一格有错的字段；一格都没错时给 `undefined`。
  */
-export function formFirstProblemOf(
-  fields: readonly FormField[],
+export function formFirstProblemOf<Values extends object>(
+  fields: readonly FormFieldOf<Values>[],
   problems: Readonly<Record<string, ReactNode | undefined>>,
-): FormField | undefined {
+): FormFieldOf<Values> | undefined {
   return fields.find((field) => Boolean(problems[field.key]));
 }
 
 /**
  * 提交那一拍的结果：有错就挡住（并点出第一处错在哪一格），没错就把键值表交出去。
  */
-export type FormSubmitOutcome =
-  | { readonly blocked: true; readonly first: FormField }
-  | { readonly blocked: false; readonly values: Readonly<Record<string, FormValue>> };
+export type FormSubmitOutcome<Values extends object = FormValues> =
+  | { readonly blocked: true; readonly first: FormFieldOf<Values> }
+  | { readonly blocked: false; readonly values: Readonly<Values> };
 
 /**
  * 算提交那一拍该干什么 —— `Form` 的提交钮点下去、以及 `<form>` 的 Enter 提交，走的都是它。
@@ -109,7 +120,9 @@ export type FormSubmitOutcome =
  * @returns `blocked: true` 时带上是按字段顺序数第一格有错的字段（拿它去 `revealFirstProblem`）；
  * `blocked: false` 时带上从 `fields` 现取的键值表。空表一定给 `blocked: false` 与空 values。
  */
-export function formSubmitOf(fields: readonly FormField[]): FormSubmitOutcome {
+export function formSubmitOf<Values extends object>(
+  fields: readonly FormFieldOf<Values>[],
+): FormSubmitOutcome<Values> {
   const problems = formProblemsOf(fields, true);
   const first = formFirstProblemOf(fields, problems);
   if (first !== undefined) return { blocked: true, first };
@@ -170,8 +183,8 @@ export function formActionsOf(args: {
  * @param args.busy - 提交中：每格的绑定 `disabled` 为真。
  * @returns `FormRow` 组成的数组；没有可画的格子时给空数组。
  */
-export function formRowsOf(args: {
-  readonly fields: readonly FormField[];
+export function formRowsOf<Values extends object>(args: {
+  readonly fields: readonly FormFieldOf<Values>[];
   readonly problems: Readonly<Record<string, ReactNode | undefined>>;
   readonly showProblem: boolean;
   readonly busy: boolean;
@@ -183,11 +196,22 @@ export function formRowsOf(args: {
       hint: field.hint,
       problem: args.showProblem ? args.problems[field.key] : undefined,
       layout: field.layout,
-    }, field.control({
-      id: `wb-form-${field.key}`,
-      name: field.key,
-      invalid: args.showProblem && Boolean(args.problems[field.key]),
-      disabled: args.busy || field.disabled === true,
-    })),
+    }, controlOf(field, args.problems, args.showProblem, args.busy)),
   );
-}
+}
+
+function controlOf<K extends string, V, Vals extends object>(
+  field: FormField<K, V, Vals>,
+  problems: Readonly<Record<string, ReactNode | undefined>>,
+  showProblem: boolean,
+  busy: boolean,
+): ReactNode {
+  return field.control({
+    id: `wb-form-${field.key}`,
+    name: field.key,
+    invalid: showProblem && Boolean(problems[field.key]),
+    disabled: busy || field.disabled === true,
+    value: field.value,
+    onChange: field.onChange,
+  });
+}

package/src/components/FormTypes.test.ts

@@ -0,0 +1,31 @@
+import { describe, expect, expectTypeOf, it } from 'vitest';
+import type { FormFieldOf, FormProps } from './FormTypes.js';
+
+type Draft = { readonly env: string; readonly branch?: string };
+
+type Submitted = Parameters<FormProps<Draft>['onSubmit']>[0];
+type EnvField = Extract<FormFieldOf<Draft>, { readonly key: 'env' }>;
+type BranchField = Extract<FormFieldOf<Draft>, { readonly key: 'branch' }>;
+type AcceptedKeys = Pick<FormFieldOf<Draft>, 'key'>['key'];
+type StrangerKeyAccepted = { readonly key: 'nope' } extends Pick<FormFieldOf<Draft>, 'key'> ? true : false;
+
+const draft: FormFieldOf<Draft> = {
+  key: 'env',
+  label: '环境',
+  value: 'stage',
+  onChange: (next) => void next.trim(),
+  control: (binding) => binding.value,
+};
+
+describe('Form<Values> 把每一格的键与值钉住（这几条由 tsc 核，`vitest run` 跑的是最后那条 expect）', () => {
+  it('★ 键只取 Values 的键、值只取那一键的类型；会隐藏的键写成可选键，提交表跟着带上 undefined', () => {
+    expectTypeOf<AcceptedKeys>().toEqualTypeOf<'env' | 'branch'>();
+    expectTypeOf<StrangerKeyAccepted>().toEqualTypeOf<false>();
+    expectTypeOf<EnvField['value']>().toEqualTypeOf<string>();
+    expectTypeOf<EnvField['onChange']>().toEqualTypeOf<(next: string) => void>();
+    expectTypeOf<BranchField['value']>().toEqualTypeOf<string | undefined>();
+    expectTypeOf<Submitted>().toEqualTypeOf<Readonly<Draft>>();
+    expectTypeOf<Submitted['branch']>().toEqualTypeOf<string | undefined>();
+    expect(draft.key).toBe('env');
+  });
+});

package/src/components/FormTypes.ts

@@ -2,38 +2,65 @@ import type { ReactNode } from '../lib/react.js';
 import type { FormAction } from './FormActions.js';
 
 /**
- * 一格控件的值：单值（`TextField` / `SelectField` / `ChoiceGroup` 单选），或一组值（`ChoiceGroup` 多选）。
+ * 默认档一格控件的值：单值（`TextField` / `SelectField` / `ChoiceGroup` 单选），或一组值（`ChoiceGroup` 多选）。
+ * 写了 `Form<Values>` 的类型参数之后，每一格的值类型由 `Values[那一格的键]` 定 —— 这个联合只是**没写类型参数**时的默认档。
  */
 export type FormValue = string | readonly string[];
 
 /**
- * `Form` 递给控件那一格的绑定：`id` / `name` / `invalid` / `disabled` 由 `Form` 定，控件只负责接上。
+ * 默认档的 `Values`：键是任意 `string`、值是 `FormValue` —— 不写 `Form<Values>` 的类型参数时就是它，
+ * 于是 `fields` 的键与值都不钉（老写法照旧能编），代价是每格拿到的都是那个联合、要自己收窄。
  */
-export interface FormFieldBinding {
+export type FormValues = Readonly<Record<string, FormValue>>;
+
+/**
+ * `Form` 递给控件那一格的绑定：`id` / `name` / `invalid` / `disabled` 由 `Form` 定；
+ * `value` / `onChange` 就是这一格自己那份配置里的那两个**原样转手**（`Form` 不持有值）——
+ * 控件接上即可，别再自己接 model：值只写在字段配置里那一次。
+ */
+export interface FormFieldBinding<K extends string = string, V = FormValue> {
   readonly id: string;
-  readonly name: string;
+  readonly name: K;
   readonly invalid: boolean;
   readonly disabled: boolean;
+  readonly value: V;
+  readonly onChange: (next: V) => void;
 }
 
 /**
- * 一格字段的配置：键、标签、值、怎么算错（`validate`）、控件本身 —— 排布、时机、阻断都不写在这里，那些归 `Form`。
+ * 一格字段的配置：键、标签、值、值怎么改（`onChange`）、怎么算错（`validate`）、控件本身 ——
+ * 排布、时机、阻断都不写在这里，那些归 `Form`。`value` 与 `onChange` 就在同一格里，`control` 从绑定直接取
+ * （`(binding) => …（{ value: binding.value, onChange: binding.onChange }）`），值不再有第二处。
  * `validate` 是纯函数、同步、只读 `values`：返回**真值**才算这一格错，假值（`undefined` / `null` / `false` / 空串）
  * 一律当"没错"—— 所以 `(value) => value.trim() === '' && '必填'` 这种用 `&&` 算文案的写法是对的，
  * 它的返回值就是错误行那句话。
  */
-export interface FormField {
-  readonly key: string;
+export interface FormField<
+  K extends string = string,
+  V = FormValue,
+  Vals extends object = FormValues,
+> {
+  readonly key: K;
   readonly label: ReactNode;
   readonly hint?: ReactNode | undefined;
   readonly layout?: 'inline' | 'stacked' | undefined;
-  readonly value: FormValue;
+  readonly value: V;
+  readonly onChange: (next: V) => void;
   readonly visible?: boolean | undefined;
   readonly disabled?: boolean | undefined;
-  readonly validate?: (value: FormValue, values: Readonly<Record<string, FormValue>>) => ReactNode | undefined;
-  readonly control: (binding: FormFieldBinding) => ReactNode;
+  readonly validate?: (value: V, values: Readonly<Vals>) => ReactNode | undefined;
+  readonly control: (binding: FormFieldBinding<K, V>) => ReactNode;
 }
 
+/**
+ * 把 `Values` 的每一键映射成一格字段 —— 写 `Form<Values>` 时 `fields` 就是这个联合的数组：
+ * `{ key: 'env', … }` 那一格的 `value` / `onChange` / `validate` 只认 `Values['env']`，
+ * `control` 拿到的绑定也只带它。要"键值都不钉"的松档就干脆别写类型参数（默认档 `FormValues`），别手写这个类型。
+ */
+export type FormFieldOf<Values extends object> = {
+  [K in keyof Values & string]: FormField<K, Values[K], Values>;
+}[keyof Values & string];
+
 /**
  * 提交钮：文案归调用点，位置、禁用与忙态归 `Form`。
  */
@@ -51,15 +78,19 @@ export interface FormCancel {
 }
 
 /**
- * `Form` 的契约：fields 配置进，排布、校验时机、提交阻断、操作区全归组件。
+ * `Form` 的契约：`fields` 配置进，排布、校验时机、提交阻断、操作区全归组件。
+ * `Values` 是**那张值表**的形状（不写就是默认档 `FormValues`）：`fields` 的键只能取它的键，
+ * 每格的 `value` / `onChange` / `validate` 只认它那一键的值类型，`onSubmit` 与 `validate` 第二参收到的也是它。
+ * **会 `visible: false` 的键写成可选键**（`branch?: string`）—— 那一格不渲染、不校验、不进 `values`（规则五），
+ * 可选键让"它可能不在表里"这件事在类型上也成立；永远可见的键照常必填。
  */
-export interface FormProps {
-  readonly fields: readonly FormField[];
-  readonly onSubmit: (values: Readonly<Record<string, FormValue>>) => void;
+export interface FormProps<Values extends object = FormValues> {
+  readonly fields: readonly FormFieldOf<Values>[];
+  readonly onSubmit: (values: Readonly<Values>) => void;
   readonly submit: FormSubmit;
   readonly cancel?: FormCancel | undefined;
   readonly extra?: readonly FormAction[] | undefined;
   readonly busy?: boolean | undefined;
   readonly disabled?: boolean | undefined;
   readonly problem?: ReactNode | undefined;
-}
+}

package/src/components/FormWiring.test.tsx

@@ -7,6 +7,7 @@ function field(key: string, value: FormValue, validate?: FormField['validate']):
     key,
     label: key,
     value,
+    onChange: () => {},
     control: (binding) => `${key}:${binding.id}:${String(binding.invalid)}:${String(binding.disabled)}`,
     ...(validate === undefined ? {} : { validate }),
   };

package/src/config/constants.ts

@@ -73,6 +73,9 @@ export const OPENCLI_MAX_CONCURRENT = 4;
 /** 启动预热站点那一跳的超时（毫秒）；超时按未热对待，不挡面板。 */
 export const WARM_TIMEOUT_MS = 20_000;
 
+/** 体检结果算「还新鲜」的时长（毫秒）：期内再来的强制体检直接回上一次那份快照。 */
+export const PREFLIGHT_FRESH_MS = 30_000;
+
 /** 装 / 卸模块包的超时（毫秒）：pnpm 与取包内容都按它算。 */
 export const INSTALL_TIMEOUT_MS = 300_000;
 

package/src/host/__tests__/board-fact.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, it } from 'vitest';
+import type { BoardProbe } from '../../lib/board-fact.js';
+import { boardFactOf } from '../board-fact.js';
+
+const WORKSHOP = '/w/workbench/diy';
+
+const probe = (over: Partial<BoardProbe> = {}): BoardProbe => ({
+  workbench: true,
+  where: WORKSHOP,
+  bar: true,
+  board: WORKSHOP,
+  open: true,
+  drawn: true,
+  ...over,
+});
+
+describe('板事实：一份判据，两边共用', () => {
+  it('★★ 画着的就是工坊那块板（含子路径）⇒ workshop', () => {
+    expect(boardFactOf(probe(), WORKSHOP)).toBe('workshop');
+    expect(boardFactOf(probe({ board: `${WORKSHOP}/packages` }), WORKSHOP)).toBe('workshop');
+  });
+
+  it('★★ 画的是别的项目的板 ⇒ other（前缀像但没落在里面也算 other）', () => {
+    expect(boardFactOf(probe({ board: '/w/project' }), WORKSHOP)).toBe('other');
+    expect(boardFactOf(probe({ board: `${WORKSHOP}-other` }), WORKSHOP)).toBe('other');
+  });
+
+  it('★★ 那块板没画在屏上 ⇒ hidden：不挂、没声明开着、量出来不可见，三条里任一条不成立都算', () => {
+    expect(boardFactOf(probe({ bar: false }), WORKSHOP)).toBe('hidden');
+    expect(boardFactOf(probe({ open: false }), WORKSHOP)).toBe('hidden');
+    expect(boardFactOf(probe({ drawn: false }), WORKSHOP)).toBe('hidden');
+  });
+
+  it('★★ 工作台没答话（旧外壳 / 夹具页）⇒ unknown：放行，但不许当成"就是工坊板"', () => {
+    expect(boardFactOf(probe({ workbench: false }), WORKSHOP)).toBe('unknown');
+  });
+
+  it('★ 画着板但说不清是哪块、或不知道工坊在哪 ⇒ unknown', () => {
+    expect(boardFactOf(probe({ board: '' }), WORKSHOP)).toBe('unknown');
+    expect(boardFactOf(probe(), null)).toBe('unknown');
+  });
+
+  it('★★ 顺序要紧：没画在屏上，就别去猜是哪块板', () => {
+    expect(boardFactOf(probe({ board: WORKSHOP, drawn: false }), WORKSHOP)).toBe('hidden');
+    expect(boardFactOf(probe({ workbench: false, bar: false }), WORKSHOP)).toBe('unknown');
+  });
+});

package/src/{lib → host/__tests__}/diy-debug.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest';
-import { DEBUG_STALE_MS, createDebugStore, parseDebugIntent, type DebugPact } from './diy-debug.js';
+import { DEBUG_STALE_MS, createDebugStore, parseDebugIntent, type DebugPact } from '../diy-debug.js';
 
 const pact = (sessionId: string, now = 1000, unit = 'demo'): DebugPact => ({
   sessionId,

package/src/{lib → host/__tests__}/diy-record.test.ts

@@ -4,9 +4,10 @@ import {
   createRecordStore,
   parseRecordIntent,
   recordOwnerText,
+  shotDueOf,
   type RecordPact,
   type RecordState,
-} from './diy-record.js';
+} from '../diy-record.js';
 
 const pact = (sessionId: string, now = 1000, unit = 'demo'): RecordPact => ({
   sessionId,
@@ -169,3 +170,138 @@ describe('用户在左栏按的三个键：意图词表只此一份', () => {
     }
   });
 });
+
+describe('按计数落图的台账：落成才前进，失败如实记、同一个计数只重试一次', () => {
+  const shot = (n: number, extra: Partial<RecordState['shots'][number]> = {}) => ({
+    n,
+    at: 1500 + n,
+    path: `/w/diy/shots/rec-shot-demo-${String(n)}.png`,
+    ...extra,
+  });
+
+  it('★ begin 时台账是空的（还没人按过「截图」）', () => {
+    const store = createRecordStore();
+    const state = held(store.begin(pact('s1', 1000)));
+
+    expect(state.shots).toEqual([]);
+    expect(state.shotsSeen).toBe(0);
+    expect(state.shotTries).toBeNull();
+  });
+
+  it('★★ 落成一张 ⇒ 台账一条、shotsSeen 跟到那个计数、重试数清零', () => {
+    const store = createRecordStore();
+    store.begin(pact('s1', 1000));
+    store.shotFailed('s1', shot(1, { error: '第一次没成' }), 1501);
+
+    const state = held(store.shotTaken('s1', shot(1), 1502));
+
+    expect(state.shots).toEqual([shot(1)]);
+    expect(state.shotsSeen).toBe(1);
+    expect(state.shotTries).toBeNull();
+  });
+
+  it('★★ 落失败 ⇒ 那一条带 error 原文、shotsSeen 一步不前进、同一个计数重试一次就试满了', () => {
+    const store = createRecordStore();
+    store.begin(pact('s1', 1000));
+
+    const first = held(store.shotFailed('s1', shot(1, { error: 'opencli：截不下来' }), 1501));
+    expect(first.shots).toEqual([shot(1, { error: 'opencli：截不下来' })]);
+    expect(first.shotsSeen).toBe(0);
+    expect(first.shotTries).toEqual({ n: 1, tries: 1 });
+
+    const retried = held(store.shotFailed('s1', shot(1, { error: '还是截不下来' }), 1601));
+    expect(retried.shots).toEqual([shot(1, { error: '还是截不下来' })]);
+    expect(retried.shotTries).toEqual({ n: 1, tries: 2 });
+  });
+
+  it('★★ shotDueOf：没涨不拍 / 涨了才拍 / 试满两次就放下 / 他再按一下（计数换新）重来', () => {
+    const store = createRecordStore();
+    const state = held(store.begin(pact('s1', 1000)));
+
+    expect(shotDueOf(state, 0)).toBeNull();
+    expect(shotDueOf(state, 1)).toBe(1);
+    expect(shotDueOf(state, 2.9)).toBe(2);
+    expect(shotDueOf(state, Number.NaN)).toBeNull();
+
+    const done = held(store.shotTaken('s1', shot(1), 1500));
+    expect(shotDueOf(done, 1)).toBeNull();
+    expect(shotDueOf(done, 2)).toBe(2);
+
+    const failed = held(store.shotFailed('s1', shot(2, { error: '没成' }), 1501));
+    expect(shotDueOf(failed, 2)).toBe(2);
+
+    const tried = held(store.shotFailed('s1', shot(2, { error: '还是没成' }), 1502));
+    expect(shotDueOf(tried, 2)).toBeNull();
+    expect(shotDueOf(tried, 3)).toBe(3);
+  });
+
+  it('★ 台账按计数排好，且同一张只留最新那条（重试不叠行）', () => {
+    const store = createRecordStore();
+    store.begin(pact('s1', 1000));
+    store.shotTaken('s1', shot(2), 1500);
+    store.shotFailed('s1', shot(1, { error: '没成' }), 1501);
+
+    const state = held(store.shotFailed('s1', shot(1, { error: '重试也没成' }), 1502));
+
+    expect(state.shots.map((one) => one.n)).toEqual([1, 2]);
+    expect(state.shots).toHaveLength(2);
+    expect(state.shots[0]?.error).toBe('重试也没成');
+  });
+
+  it('★ 台账不是谁都能写的：别人的会话 / 没有那一场，当场拒', () => {
+    const store = createRecordStore();
+
+    expect(store.shotTaken('s1', shot(1), 1000)).toEqual({ ok: false, code: 'none' });
+    expect(store.shotFailed('s1', shot(1), 1000)).toEqual({ ok: false, code: 'none' });
+
+    store.begin(pact('s1', 1000));
+    expect(store.shotTaken('s2', shot(1), 1100)).toEqual({ ok: false, code: 'not-owner' });
+    expect(store.shotFailed('s2', shot(1), 1100)).toEqual({ ok: false, code: 'not-owner' });
+    expect(store.live(1100)?.shots).toEqual([]);
+  });
+});
+
+describe('门铃那一格：命中记一次，超时一个字不动', () => {
+  it('★★ begin 时 0 次；命中一次 +1，并把这一次等了多少毫秒记下', () => {
+    const store = createRecordStore();
+    const state = held(store.begin(pact('s1', 1000)));
+
+    expect(state.beats).toBe(0);
+    expect(state.beatMs).toBe(0);
+
+    const first = held(store.beat('s1', 42, 1200));
+    expect(first.beats).toBe(1);
+    expect(first.beatMs).toBe(42);
+    expect(first.at).toBe(1200);
+
+    const second = held(store.beat('s1', 7, 1300));
+    expect(second.beats).toBe(2);
+    expect(second.beatMs).toBe(7);
+  });
+
+  it('★★ 跟着相位走不丢（started / finished 都保留），收工连它一起清；别人的会话不许写', () => {
+    const store = createRecordStore();
+    store.begin(pact('s1', 1000));
+    store.beat('s1', 12, 1100);
+    store.started('s1', 2000, 2001);
+    store.finished('s1', 3000, 3002);
+
+    const live = store.live(3002);
+    expect(live?.beats).toBe(1);
+    expect(live?.beatMs).toBe(12);
+
+    expect(store.beat('s2', 5, 3100)).toEqual({ ok: false, code: 'not-owner' });
+    expect(held(store.beat('s1', 5, 3200)).beats).toBe(2);
+    expect(store.stop('s1', 3300).ok).toBe(true);
+    expect(store.live(3300)).toBeNull();
+    expect(store.beat('s1', 5, 3400)).toEqual({ ok: false, code: 'none' });
+  });
+
+  it('★ 负数 / 小数收成正经毫秒（读侧那一行不出现 "-0 毫秒" 这种话）', () => {
+    const store = createRecordStore();
+    store.begin(pact('s1', 1000));
+
+    expect(held(store.beat('s1', -3, 1100)).beatMs).toBe(0);
+    expect(held(store.beat('s1', 4.7, 1200)).beatMs).toBe(4);
+  });
+});

package/src/host/__tests__/facts.test.ts

@@ -0,0 +1,13 @@
+import { describe, expect, it } from 'vitest';
+import { isFactScope, scopePrefixOf } from '../../api/facts.js';
+import { unitFactScope } from '../facts.js';
+
+describe('unitFactScope', () => {
+  it('命名空间 = 模块 id + `*`（"这个模块的数据全作废"只写一个字符串）', () => {
+    expect(unitFactScope('cmdb')).toBe('cmdb*');
+    expect(isFactScope('cmdb*')).toBe(true);
+    expect(isFactScope('*')).toBe(false);
+    expect(isFactScope('cmdb/summary')).toBe(false);
+    expect(scopePrefixOf('cmdb*')).toBe('cmdb');
+  });
+});

package/src/host/__tests__/long-task.test.ts

@@ -140,6 +140,48 @@ describe('createLongTaskRegistry.stop（停止只是转发给生产方，认不
   });
 });
 
+describe('createLongTaskRegistry.live（外壳侧栏那颗 loading 点读的：不分工作区，只给活着的）', () => {
+  it('★★ 两个工作区各一趟在跑 ⇒ 两趟都在；收尾的 / 停掉的不在', async () => {
+    const h = harness();
+    const runs = createLongTaskRegistry(h.deps);
+    const a = runs.start({ workspace: '/w/a', target: 'release', session: 's-1' });
+    const b = runs.start({ workspace: '/w/b', target: 'board' });
+
+    expect(runs.live().map((one) => one.id)).toEqual([a.id, b.id]);
+    expect(runs.live().map((one) => one.session)).toEqual(['s-1', undefined]);
+
+    h.done({});
+    await flush();
+    expect(runs.live().map((one) => one.id)).toEqual([a.id]);
+
+    runs.stop(a.id);
+    expect(runs.live()).toEqual([]);
+  });
+
+  it('★ 要登录那种也算活着（与 longTaskDot 同一口径）', () => {
+    const h = harness();
+    const runs = createLongTaskRegistry(h.deps);
+    runs.start({ workspace: '/w/a', target: 'release' });
+
+    h.step({ kind: 'start', text: '未登录', loginUrl: 'https://x/login' });
+
+    expect(runs.live().map((one) => one.status)).toEqual(['needs-login']);
+  });
+
+  it('★★ 交回的是 base 快照（工作区 / 目标 / 来源会话都在），模块那层 view 投影不参与', () => {
+    const h = harness({ view: () => ({ hidden: true }) });
+    const runs = createLongTaskRegistry(h.deps);
+    runs.start({ workspace: '/w/a', target: 'release', session: 's-1' });
+
+    expect(runs.live()[0]).toMatchObject({
+      workspace: '/w/a',
+      target: 'release',
+      session: 's-1',
+      status: 'running',
+    });
+  });
+});
+
 describe('sharedLongTaskRegistry（那一份跨热重载存活）', () => {
   it('★★ 槽里那份**上一版的注册表**（四个方法、没有 stop）仍被认回：升级那次重载不重建空表', () => {
     const scope = `test-${String(Date.now())}-${Math.random()}`;

package/src/{lib → host/__tests__}/panel-state.test.ts

@@ -5,7 +5,7 @@ import {
   createPanelStateStore,
   parseCardsReport,
   parseCrashReport,
-} from './panel-state';
+} from '../panel-state.js';
 
 function card(unit: string, route: string, phase: 'idle' | 'loading' | 'ready' | 'error', at: number) {
   return { unit, route, phase, at };