@dsh-workbench/shared 0.3.3 → 0.3.5

package/src/host/unit-face.ts

@@ -8,6 +8,11 @@ import type { ApprovalCall, ApprovalFacts, ApprovalPolicy } from '../host/tool-a
 import type { ValueHandoff } from '../host/value-handoff.js';
 import type { WorkspaceStore } from '../host/workspace-store.js';
 
+export interface ToolScopeContext {
+  readonly workspace: string | null;
+  readonly preset: string | null;
+}
+
 export interface UnitMountDeps {
   readonly manifest: UnitManifest;
   readonly ctx: DshHostContext;
@@ -43,7 +48,7 @@ export interface UnitMountResult {
   registerTools(): Array<() => void>;
   readonly factsOf?: ((call: UnitCall) => readonly string[] | undefined) | undefined;
   readonly gate?: {
-    deniedTools(workspace: string | null): readonly string[];
+    deniedTools(context: ToolScopeContext): readonly string[];
     subscribe(listener: () => void): () => void;
   };
   readonly context?: {

package/src/host.ts

@@ -9,6 +9,7 @@ export * from './lib/ui.js';
 export * from './lib/panel-state.js';
 export * from './lib/board-fact.js';
 export * from './lib/diy-debug.js';
+export * from './lib/diy-record.js';
 export * from './api/blocker-table.js';
 export * from './host/browser-find.js';
 export * from './host/browser-read.js';

package/src/i18n/en.ts

@@ -1,5 +1,6 @@
 import type { WorkbenchMessages } from './zh.js';
 
+/** 外壳自带的英文词表：键必须与 `zh` 逐一对应，值不许为空串。 */
 export const en: Record<keyof WorkbenchMessages, string> = {
   'brand.name': 'Workbench',
 
@@ -423,18 +424,31 @@ export const en: Record<keyof WorkbenchMessages, string> = {
   'configSync.emptyProviders': 'The workbench has no model provider yet — sync the llm- rows from some profile, or configure one under Models.',
   'configSync.failed': 'The sync did not go through; try again.',
 
-  'debug.status': 'Workbench DIY debugging',
-  'debug.status.trouble': 'Workbench DIY debugging needs attention',
-  'debug.stalled': 'Workbench DIY debugging paused',
+  'debug.workspace': 'this workspace',
+  'debug.status': 'Debugging “{title}”',
+  'debug.status.trouble': 'Debugging needs your attention ({title})',
+  'debug.stalled': 'Debugging paused ({title})',
   'debug.act.pause': 'Pause debugging',
   'debug.act.resume': 'Resume debugging',
   'debug.act.stop': 'Stop debugging',
   'debug.act.stop.ask': 'Confirm stop',
-  'debug.card.here.title': 'Workbench DIY debugging is on',
+  'debug.card.here.title': 'Debugging “{title}”',
   'debug.card.here.note': 'Do not switch workspaces or touch the panel',
-  'debug.card.away.title': 'Workbench DIY debugging is on',
-  'debug.card.away.note': 'Switch to the Workbench DIY workspace',
+  'debug.card.away.note': 'Switch back to “{title}”',
   'debug.card.paused.note': 'Paused',
-  'debug.card.hidden.note': 'Switch to the Workbench panel',
-  'debug.back': 'Back to the workshop screen',
+  'debug.card.hidden.note': 'Switch back to the Workbench panel',
+  'record.waiting': 'Recording handoff · your turn',
+  'record.waiting.note': 'Press "Start recording" on that page, then "Stop recording" when done (it will not switch you back)',
+  'record.recording': 'Recording',
+  'record.recording.note': 'Press "Stop recording" when done; if the bar is gone press Halt so the agent grabs it first',
+  'record.finished': 'Recording finished',
+  'record.finished.note': 'This run is done — the agent will grab it and wrap up on its own',
+  'record.act.cancel': 'Cancel',
+  'record.act.halt': 'Halt',
+  'approval.record.site': 'Site',
+  'approval.record.what': 'Records',
+  'approval.record.lands': 'Lands in',
+  'approval.record.noUrl': 'no site given (this call gets refused)',
+  'approval.record.oneAction': 'one action',
+  'approval.record.noSwitch': 'it will not switch you back (the leftbar footer shows the state)',
 };

package/src/i18n/index.ts

@@ -1,10 +1,13 @@
 import { en } from './en.js';
 import { zh, type WorkbenchMessages } from './zh.js';
 
+/** 外壳自带的两份词表（`zh` 为基准、`en` 同构）：`client.tsx` 拿它当合并各套件词表的底座。 */
 export const dictionaries = { zh, en };
 
+/** 中文词表的键类型（从 `zh.ts` 转出）：`en` 与模块词表都得覆盖同一批键。 */
 export type { WorkbenchMessages };
 
+/** 一份按语言分的词表：`zh` / `en` 必须同键，另可带模块自己那份语言。 */
 export interface Dictionaries {
   readonly zh: Readonly<Record<string, string>>;
   readonly en: Readonly<Record<string, string>>;

package/src/i18n/merge.ts

@@ -1,5 +1,6 @@
 import type { Dictionaries } from './index.js';
 
+/** 一个套件交上来的词表：`unit` 是套件 id（也是键前缀），`messages` 缺省表示这次不参与合并。 */
 export interface MessagesContribution {
   readonly unit: string;
   readonly messages?: Dictionaries | undefined;
@@ -23,6 +24,7 @@ function assertSelfConsistent(unit: string, messages: Dictionaries): void {
   }
 }
 
+/** 把各套件的词表合到外壳底座上：键必须以 `<unit>.` 开头、不许撞已有键，违规当场抛错。 */
 export function mergeMessages(
   base: Dictionaries,
   contributions: readonly MessagesContribution[],
@@ -53,11 +55,13 @@ export function mergeMessages(
   return { zh, en };
 }
 
+/** 一条没合进去的贡献：哪个套件 + 为什么被拒（人话原因）。 */
 export interface MessagesProblem {
   readonly unit: string;
   readonly reason: string;
 }
 
+/** 合并结果：合出来的词表 + 被跳过的贡献；`problems` 为空即全部合上了。 */
 export interface MessagesMerge {
   readonly dictionaries: Dictionaries;
   readonly problems: readonly MessagesProblem[];
@@ -68,6 +72,7 @@ function reasonOf(error: unknown): string {
   return typeof error === 'string' ? error : String(error);
 }
 
+/** 逐份试合、坏的跳过：一份贡献不合规只记进 `problems`，不影响其余套件与已有词表。 */
 export function mergeMessagesSkipping(
   base: Dictionaries,
   contributions: readonly MessagesContribution[],

package/src/i18n/zh.ts

@@ -1,3 +1,4 @@
+/** 外壳自带的中文词表（命名空间 `workbench`）：`en` 与它逐键对齐，模块那份在它之上合并。 */
 export const zh = {
   'brand.name': '工作台',
 
@@ -418,20 +419,34 @@ export const zh = {
   'configSync.emptyProviders': '工作台还没有任何模型供应商 —— 去「配置同步」从某个 profile 把 llm- 那几行搬过来，或自己去「模型」里配。',
   'configSync.failed': '同步没成功，再试一次。',
 
-  'debug.status': '工作台 DIY 开发调试中',
-  'debug.status.trouble': '工作台 DIY 开发调试异常',
-  'debug.stalled': '工作台 DIY 调试暂停',
+  'debug.workspace': '这个工作区',
+  'debug.status': '「{title}」调试中',
+  'debug.status.trouble': '调试要你看一眼（{title}）',
+  'debug.stalled': '调试已暂停（{title}）',
   'debug.act.pause': '暂停调试',
   'debug.act.resume': '继续调试',
   'debug.act.stop': '结束调试',
   'debug.act.stop.ask': '确认结束',
-  'debug.card.here.title': '当前工作台 DIY 开发调试中',
+  'debug.card.here.title': '正在调试「{title}」',
   'debug.card.here.note': '请勿切换工作区和操作面板',
-  'debug.card.away.title': '工作台 DIY 开发调试中',
-  'debug.card.away.note': '请切换到工作台 DIY 工作区',
+  'debug.card.away.note': '请切回「{title}」那一屏',
   'debug.card.paused.note': '已暂停',
-  'debug.card.hidden.note': '请切换到工作台面板',
-  'debug.back': '回到工坊那一屏',
+  'debug.card.hidden.note': '请切回工作台面板',
+  'record.waiting': '取证交接 · 等你出手',
+  'record.waiting.note': '请在那一页按「开始录制」，做完按「结束录制」（录完不替你切回来）',
+  'record.recording': '录制中',
+  'record.recording.note': '做完按「结束录制」；浮条没了按「停」，让 agent 先取再收',
+  'record.finished': '录制完成',
+  'record.finished.note': '这一段录完了 —— agent 会自己来取并收工，不用你点',
+  'record.act.cancel': '取消',
+  'record.act.halt': '停',
+  'approval.record.site': '站点',
+  'approval.record.what': '录制功能',
+  'approval.record.lands': '落点',
+  'approval.record.noUrl': '没给站点地址（这次会被当场拒）',
+  'approval.record.oneAction': '一次操作',
+  'approval.record.noSwitch': '录完不会替你切回来（左栏底部会亮一条状态）',
 } as const;
 
+/** 中文词表的键类型：`en` 与模块词表都得覆盖同一批键。 */
 export type WorkbenchMessages = typeof zh;

package/src/index.ts

@@ -20,8 +20,11 @@ export * from './components/CardBoundary.js';
 export * from './components/CardHead.js';
 export * from './components/ChoiceGroup.js';
 export * from './components/Field.js';
+export * from './components/Form.js';
 export * from './components/FormActions.js';
+export * from './components/FormNodes.js';
 export * from './components/FormRows.js';
+export * from './components/FormTypes.js';
 export * from './components/Link.js';
 export * from './components/LongTaskRow.js';
 export * from './components/Note.js';
@@ -29,6 +32,7 @@ export * from './components/ResourceStates.js';
 export * from './components/Rows.js';
 export * from './components/SaveBar.js';
 export * from './components/SelectField.js';
+export * from './components/SelectFieldNodes.js';
 export * from './components/SettingsSection.js';
 export * from './components/Spinner.js';
 export * from './components/Stack.js';
@@ -43,10 +47,11 @@ export * from './i18n/index.js';
 export * from './i18n/merge.js';
 export * from './i18n/zh.js';
 export * from './lib/blocker-action.js';
-export * from './lib/busy.js';
-export * from './lib/form-problem.js';
 export * from './lib/board-fact.js';
+export * from './lib/busy.js';
 export * from './lib/diy-debug.js';
+export * from './lib/diy-record.js';
+export * from './lib/form-problem.js';
 export * from './lib/panel-state.js';
 export * from './lib/react.js';
 export * from './lib/text.js';

package/src/lib/blocker-action.ts

@@ -1,21 +1,43 @@
+/**
+ * 阻断态取词：i18n 的 `(key) => 文案` 那一半；那几颗钮的「重试中…」等临时说法都从它来。
+ */
 export type BlockerLabelTranslate = (key: string) => string;
 
+/**
+ * 阻断态上一颗钮的形状：`kind` 定行为（`retry` / `copy` 等），`label` 是它平时的文案。
+ */
 export interface BlockerActionShape {
   readonly kind: string;
   readonly label: string;
   readonly text?: string | undefined;
 }
 
+/**
+ * 这颗钮此刻的运行态：是否正在重试、哪一支正在跑（按 label 认）、刚复制过哪段文本。
+ */
 export interface BlockerLabelState {
   readonly retrying: boolean;
   readonly running: string | null;
   readonly copied: string | null;
 }
 
+/**
+ * 这颗钮此刻该不该按成等待态：这一轮忙还没收，或有一支正在跑。
+ * @param busy - 这一轮忙是不是还在。
+ * @param running - 正在跑的那一支的 label；没有就给 `null`。
+ * @returns 该等待给 `true`，否则 `false`。
+ */
 export function blockerPending(busy: boolean, running: string | null): boolean {
   return busy || running !== null;
 }
 
+/**
+ * 这颗钮此刻该显示什么字：正在重试说「重试中…」，正在跑的那一支说「修复中…」，刚复制过的说「已复制」，其余原样。
+ * @param action - 这颗钮的形状（行为 + 平时文案）。
+ * @param state - 此刻的运行态。
+ * @param t - i18n 取词函数。
+ * @returns 要显示的文案；三种临时态都不成立时就是 `action.label`。
+ */
 export function blockerActionLabel(
   action: BlockerActionShape,
   state: BlockerLabelState,

package/src/lib/board-fact.ts

@@ -1,9 +1,15 @@
+/**
+ * 椅面（右栏那块画板）此刻归属哪一类：`workshop` 本工坊、`other` 别家、`hidden` 没画出来、`unknown` 探不到。
+ */
 export type BoardFactState =
   | 'workshop'
   | 'other'
   | 'hidden'
   | 'unknown';
 
+/**
+ * 左栏底部「调试」那条状态要说的档位：`ok` 在板上、`off-workspace` 切去了别的项目、`panel-closed` 面板没开、`other-board` 画的是别家的板、`unknown` 探不到。
+ */
 export type BoardSituation =
   | 'ok'
   | 'off-workspace'
@@ -11,6 +17,9 @@ export type BoardSituation =
   | 'other-board'
   | 'unknown';
 
+/**
+ * 一次页面探针的读数：外壳在不在、探的是哪个工作区、右栏开没开、板上挂的路径、椅面画出来没有。
+ */
 export interface BoardProbe {
   readonly workbench: boolean;
   readonly where: string;
@@ -20,12 +29,24 @@ export interface BoardProbe {
   readonly drawn: boolean;
 }
 
+/**
+ * 判一个路径落不落在这个工作区里（按路径前缀比，不是字符串包含）。
+ * @param root - 工作区根路径。
+ * @param target - 要判的路径。
+ * @returns 同一个路径或在其下给 `true`；`root` 末尾带不带斜杠都认（`/a` 不匹配 `/ab`）。
+ */
 export function insideWorkshop(root: string, target: string): boolean {
   if (target === root) return true;
   const base = root.endsWith('/') ? root : `${root}/`;
   return target.startsWith(base);
 }
 
+/**
+ * 把一次探针读数归成椅面归属。
+ * @param probe - 探针读数。
+ * @param workshop - 当前工作区根路径；`null` 表示还不知道当前是哪个工作区。
+ * @returns 外壳不在、或板路径与工作区缺一 → `unknown`；右栏没开或没画出来 → `hidden`；板在本工作区 → `workshop`，否则 `other`。
+ */
 export function boardFactOf(probe: BoardProbe, workshop: string | null): BoardFactState {
   if (!probe.workbench) return 'unknown';
   if (!probe.bar || !probe.open || !probe.drawn) return 'hidden';
@@ -33,6 +54,12 @@ export function boardFactOf(probe: BoardProbe, workshop: string | null): BoardFa
   return insideWorkshop(workshop, probe.board) ? 'workshop' : 'other';
 }
 
+/**
+ * 把探针读数归成左栏那句人话的档位。
+ * @param probe - 探针读数。
+ * @param workshop - 当前工作区根路径；`null` 一律 `unknown`。
+ * @returns 椅面画着 → 本板 `ok` / 别板 `other-board`；没画着 → 页面已走 `off-workspace`，否则 `panel-closed`。
+ */
 export function boardSituation(probe: BoardProbe, workshop: string | null): BoardSituation {
   if (!probe.workbench || workshop === null) return 'unknown';
   const drawn = probe.bar && probe.open && probe.drawn;

package/src/lib/busy.ts

@@ -1,8 +1,18 @@
+/**
+ * 忙态按下限收尾的判据结果：还该不该显示（`visible`），以及还要按住多少毫秒（`releaseInMs`，0 = 立刻可收）。
+ */
 export interface BusyHold {
   readonly visible: boolean;
   readonly releaseInMs: number;
 }
 
+/**
+ * 按「至少显示 floorMs」算这一轮忙此刻该不该收：没到下限就继续显示，并给出剩余时长供调用方起定时器。
+ * @param since - 这一轮忙开始的时间戳；`null`（没开过这一轮）一律不显示。
+ * @param now - 当前时间戳。
+ * @param floorMs - 至少显示的时长（毫秒）。
+ * @returns 还该不该显示 + 剩余毫秒；到点或已过下限给不显示，时钟倒退按「刚开头」算（剩余 = 下限，不给负数）。
+ */
 export function holdBusy(since: number | null, now: number, floorMs: number): BusyHold {
   if (since === null) return { visible: false, releaseInMs: 0 };
   const elapsed = Math.max(0, now - since);

package/src/lib/diy-debug.test.ts

@@ -3,7 +3,8 @@ import { DEBUG_STALE_MS, createDebugStore, parseDebugIntent, type DebugPact } fr
 
 const pact = (sessionId: string, now = 1000, unit = 'demo'): DebugPact => ({
   sessionId,
-  workspace: '/w/diy',
+  workspacePath: '/w/diy',
+  title: '演示工作区',
   board: '/w/diy',
   unit,
   name: unit,

package/src/lib/diy-debug.ts

@@ -1,17 +1,35 @@
+/**
+ * 调试约定的两个相位：`debugging` 正占着用户的屏，`paused` 已暂停但仍持着约定。
+ */
 export type DebugPhase = 'debugging' | 'paused';
 
+/**
+ * 调试约定收得下的三个人话动作：暂停 / 继续 / 结束。
+ */
 export type DebugIntent = 'pause' | 'resume' | 'stop';
 
+/**
+ * 把工具入参收成人话动作。
+ * @param value - 任意入参值。
+ * @returns `'pause'` / `'resume'` / `'stop'` 原样；别的值（含 `undefined`、多余空白、大小写不同）给 `null`，由调用方拒。
+ */
 export function parseDebugIntent(value: unknown): DebugIntent | null {
   return value === 'pause' || value === 'resume' || value === 'stop' ? value : null;
 }
 
+/**
+ * 调试约定的有效期（4 小时，毫秒）：超过它没动静的约定算过期、当场让人。
+ */
 export const DEBUG_STALE_MS = 4 * 60 * 60 * 1000;
 
+/**
+ * 一份活着的调试约定：相位 + 谁的会话 + 哪个工作区 / 板 / 单元 + 起于何时（`at` 是最后一次动作）。
+ */
 export interface DebugState {
   readonly phase: DebugPhase;
   readonly sessionId: string;
-  readonly workspace: string;
+  readonly workspacePath: string;
+  readonly title: string;
   readonly board: string;
   readonly unit: string;
   readonly name: string;
@@ -19,15 +37,22 @@ export interface DebugState {
   readonly at: number;
 }
 
+/**
+ * 建立约定要交的那几件：会话、工作区、板、单元、名字，以及此刻的时间戳。
+ */
 export interface DebugPact {
   readonly sessionId: string;
-  readonly workspace: string;
+  readonly workspacePath: string;
+  readonly title: string;
   readonly board: string;
   readonly unit: string;
   readonly name: string;
   readonly now: number;
 }
 
+/**
+ * 约定被拒的原因码：自己已持有 / 别人持着 / 不是持有者 / 没有约定 / 已暂停 / 已在调试。
+ */
 export type DebugRefusal =
   | 'already-held'
   | 'held-by-other'
@@ -36,10 +61,16 @@ export type DebugRefusal =
   | 'already-paused'
   | 'already-debugging';
 
+/**
+ * 一次约定动作的结果：成功带新状态，失败带拒绝码。
+ */
 export type DebugMove =
   | { readonly ok: true; readonly state: DebugState }
   | { readonly ok: false; readonly code: DebugRefusal };
 
+/**
+ * 调试约定的存取口（外壳持有一份）：`live` 取当前有效的约定，`begin` / `pause` / `resume` / `stop` 推相位。
+ */
 export interface DebugStore {
   live(now: number): DebugState | null;
   begin(pact: DebugPact): DebugMove;
@@ -60,6 +91,10 @@ function ownerOf(state: DebugState | null, sessionId: string, now: number): Debu
   return held.sessionId === sessionId ? held : 'not-owner';
 }
 
+/**
+ * 造一份新的调试约定存储（进程内存，同一时刻只可能有一份有效约定）。
+ * @returns 存取口；动作成不成都在返回的 `DebugMove` 里，不抛异常。
+ */
 export function createDebugStore(): DebugStore {
   let held: DebugState | null = null;
 
@@ -76,7 +111,8 @@ export function createDebugStore(): DebugStore {
       const state: DebugState = {
         phase: 'debugging',
         sessionId: pact.sessionId,
-        workspace: pact.workspace,
+        workspacePath: pact.workspacePath,
+        title: pact.title,
         board: pact.board,
         unit: pact.unit,
         name: pact.name,
@@ -114,6 +150,11 @@ export function createDebugStore(): DebugStore {
   };
 }
 
+/**
+ * 「谁还占着」的一句话，用于别人来抢时说清现况。
+ * @param state - 当前有效的那份约定。
+ * @returns 形如「会话 x（自 HH:mm:ssZ 起在调试 y）」的中文串。
+ */
 export function debugOwnerText(state: DebugState): string {
   return `会话 ${state.sessionId}（自 ${new Date(state.startedAt).toISOString().slice(11, 19)}Z 起在调试 ${state.unit}）`;
 }

package/src/lib/diy-record.test.ts

@@ -0,0 +1,171 @@
+import { describe, expect, it } from 'vitest';
+import {
+  RECORD_STALE_MS,
+  createRecordStore,
+  parseRecordIntent,
+  recordOwnerText,
+  type RecordPact,
+  type RecordState,
+} from './diy-record.js';
+
+const pact = (sessionId: string, now = 1000, unit = 'demo'): RecordPact => ({
+  sessionId,
+  workspace: '/w/diy',
+  unit,
+  name: unit,
+  url: 'https://cmdb.example.com/env',
+  title: '环境 · CMDB',
+  action: '发布',
+  expect: { method: 'POST', urlContains: '/api/publish' },
+  captureFile: '/w/diy/shots/rec-demo.jsonl',
+  now,
+});
+
+const held = (move: { ok: true; state: RecordState } | { ok: false; code: string }): RecordState => {
+  if (!move.ok) throw new Error(`expected ok, got ${move.code}`);
+  return move.state;
+};
+
+describe('录制交接：一台机器一次一场，谁开谁收工', () => {
+  it('★ begin ⇒ armed，把目标、那一页、那一下、捕获文件都记下', () => {
+    const store = createRecordStore();
+    const state = held(store.begin(pact('s1', 1000)));
+
+    expect(state.phase).toBe('armed');
+    expect(state.unit).toBe('demo');
+    expect(state.url).toBe('https://cmdb.example.com/env');
+    expect(state.action).toBe('发布');
+    expect(state.expect).toEqual({ method: 'POST', urlContains: '/api/publish' });
+    expect(state.captureFile).toBe('/w/diy/shots/rec-demo.jsonl');
+    expect(state.startedAt).toBe(1000);
+    expect(state.t0).toBeNull();
+    expect(state.t1).toBeNull();
+    expect(store.live(1000)).toEqual(state);
+  });
+
+  it('★★ 另一场占着就不许再开；同一个会话再来一次 ⇒ already-held', () => {
+    const store = createRecordStore();
+    store.begin(pact('s1', 1000));
+
+    expect(store.begin(pact('s2', 1200))).toEqual({ ok: false, code: 'held-by-other' });
+    expect(store.begin(pact('s1', 1300))).toEqual({ ok: false, code: 'already-held' });
+    expect(store.live(1300)?.sessionId).toBe('s1');
+  });
+
+  it('★ 用户按「开始」⇒ recording，t0 是他按的那一刻（不是 store 收到的那一刻）', () => {
+    const store = createRecordStore();
+    store.begin(pact('s1', 1000));
+
+    const state = held(store.started('s1', 2000, 2001));
+    expect(state.phase).toBe('recording');
+    expect(state.t0).toBe(2000);
+    expect(state.at).toBe(2001);
+    expect(state.startedAt).toBe(1000);
+  });
+
+  it('★ 用户按「结束」⇒ finished，t1 落下来；再按一次「结束」⇒ not-recording', () => {
+    const store = createRecordStore();
+    store.begin(pact('s1', 1000));
+    store.started('s1', 2000, 2001);
+
+    const state = held(store.finished('s1', 5000, 5002));
+    expect(state.phase).toBe('finished');
+    expect(state.t1).toBe(5000);
+    expect(store.finished('s1', 6000, 6000)).toEqual({ ok: false, code: 'not-recording' });
+  });
+
+  it('★★ 阶段不对就说清是哪一档：还没开始就结束 / 已经开始又按开始', () => {
+    const store = createRecordStore();
+    store.begin(pact('s1', 1000));
+
+    expect(store.finished('s1', 1500, 1500)).toEqual({ ok: false, code: 'not-recording' });
+
+    store.started('s1', 2000, 2000);
+    expect(store.started('s1', 2100, 2100)).toEqual({ ok: false, code: 'already-recording' });
+
+    store.finished('s1', 3000, 3000);
+    expect(store.started('s1', 3100, 3100)).toEqual({ ok: false, code: 'not-armed' });
+  });
+
+  it('★★ 一场就一个周期：finished 之后回不去了（没有「再录一段」，要重录就重新 begin 一场）', () => {
+    const store = createRecordStore();
+    store.begin(pact('s1', 1000));
+    store.started('s1', 2000, 2000);
+    store.finished('s1', 3000, 3000);
+
+    const state = store.live(3000);
+    expect(state?.phase).toBe('finished');
+    expect(state?.t0).toBe(2000);
+    expect(state?.t1).toBe(3000);
+    expect(store.started('s1', 3100, 3100)).toEqual({ ok: false, code: 'not-armed' });
+    expect(store.finished('s1', 3200, 3200)).toEqual({ ok: false, code: 'not-recording' });
+    expect(store.live(3300)?.phase).toBe('finished');
+  });
+
+  it('★ 收工把它清干净（取消那一拍也走它）', () => {
+    const store = createRecordStore();
+    store.begin(pact('s1', 1000));
+
+    const stopped = held(store.stop('s1', 1500));
+    expect(stopped.unit).toBe('demo');
+    expect(store.live(1500)).toBeNull();
+    expect(store.stop('s1', 1600)).toEqual({ ok: false, code: 'none' });
+  });
+
+  it('★★ 别人不许动我这一场（not-owner）；没开过 ⇒ none', () => {
+    const store = createRecordStore();
+
+    expect(store.started('s1', 1000, 1000)).toEqual({ ok: false, code: 'none' });
+    expect(store.finished('s1', 1000, 1000)).toEqual({ ok: false, code: 'none' });
+    expect(store.stop('s1', 1000)).toEqual({ ok: false, code: 'none' });
+
+    store.begin(pact('s1', 1000));
+    expect(store.started('s2', 1100, 1100)).toEqual({ ok: false, code: 'not-owner' });
+    expect(store.finished('s2', 1100, 1100)).toEqual({ ok: false, code: 'not-owner' });
+    expect(store.stop('s2', 1100)).toEqual({ ok: false, code: 'not-owner' });
+    expect(store.live(1100)?.sessionId).toBe('s1');
+  });
+
+  it('★ 过期当它不存在（15 分钟没人管就放别人进来）', () => {
+    const store = createRecordStore();
+    store.begin(pact('s1', 1000));
+
+    expect(store.live(1000 + RECORD_STALE_MS)).not.toBeNull();
+    expect(store.live(1001 + RECORD_STALE_MS)).toBeNull();
+    expect(store.begin(pact('s2', 1001 + RECORD_STALE_MS)).ok).toBe(true);
+    expect(store.live(1001 + RECORD_STALE_MS)?.sessionId).toBe('s2');
+  });
+
+  it('★ 录制中不被 TTL 拽走：at 每动一次就续上（他正在那一页上操作）', () => {
+    const store = createRecordStore();
+    store.begin(pact('s1', 1000));
+
+    const late = 1000 + RECORD_STALE_MS;
+    const state = held(store.started('s1', late, late));
+    expect(state.phase).toBe('recording');
+    expect(state.startedAt).toBe(1000);
+    expect(store.live(late + RECORD_STALE_MS)).not.toBeNull();
+    expect(store.live(late + RECORD_STALE_MS + 1)).toBeNull();
+  });
+
+  it('★ 占着的那句话里有会话、时间和要录的是什么（另一场要看得懂是谁占的）', () => {
+    const store = createRecordStore();
+    const state = held(store.begin(pact('s1', 1000)));
+    const text = recordOwnerText(state);
+
+    expect(text).toContain('s1');
+    expect(text).toContain('demo');
+    expect(text).toContain('发布');
+  });
+});
+
+describe('用户在左栏按的三个键：意图词表只此一份', () => {
+  it('★ 认得出三个，其余一律 null（别把别的字当成指令）', () => {
+    expect(parseRecordIntent('peek')).toBe('peek');
+    expect(parseRecordIntent('halt')).toBe('halt');
+    expect(parseRecordIntent('stop')).toBe('stop');
+    for (const bad of ['', 'PEEK', 'Peek', 'cancel', 'kill', 'end', null, undefined, 1, {}, []]) {
+      expect(parseRecordIntent(bad)).toBeNull();
+    }
+  });
+});