@dsh-workbench/shared 0.3.5 → 0.3.7

package/dist/host/diy-debug.d.ts

@@ -0,0 +1,80 @@
+/**
+ * 调试约定的两个相位：`debugging` 正占着用户的屏，`paused` 已暂停但仍持着约定。
+ */
+export type DebugPhase = 'debugging' | 'paused';
+/**
+ * 调试约定收得下的三个人话动作：暂停 / 继续 / 结束。
+ */
+export type DebugIntent = 'pause' | 'resume' | 'stop';
+/**
+ * 把工具入参收成人话动作。
+ * @param value - 任意入参值。
+ * @returns `'pause'` / `'resume'` / `'stop'` 原样；别的值（含 `undefined`、多余空白、大小写不同）给 `null`，由调用方拒。
+ */
+export declare function parseDebugIntent(value: unknown): DebugIntent | null;
+/**
+ * 调试约定的有效期（4 小时，毫秒）：超过它没动静的约定算过期、当场让人。
+ */
+export declare const DEBUG_STALE_MS: number;
+/**
+ * 一份活着的调试约定：相位 + 谁的会话 + 哪个工作区 / 板 / 单元 + 起于何时（`at` 是最后一次动作）。
+ */
+export interface DebugState {
+    readonly phase: DebugPhase;
+    readonly sessionId: string;
+    readonly workspacePath: string;
+    readonly title: string;
+    readonly board: string;
+    readonly unit: string;
+    readonly name: string;
+    readonly startedAt: number;
+    readonly at: number;
+}
+/**
+ * 建立约定要交的那几件：会话、工作区、板、单元、名字，以及此刻的时间戳。
+ */
+export interface DebugPact {
+    readonly sessionId: 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' | 'not-owner' | 'none' | '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;
+    pause(sessionId: string, now: number): DebugMove;
+    resume(sessionId: string, now: number): DebugMove;
+    stop(sessionId: string, now: number): DebugMove;
+    settle?(): Promise<void>;
+}
+/**
+ * 造一份新的调试约定存储（进程内存，同一时刻只可能有一份有效约定）。
+ * @returns 存取口；动作成不成都在返回的 `DebugMove` 里，不抛异常。
+ */
+export declare function createDebugStore(): DebugStore;
+/**
+ * 「谁还占着」的一句话，用于别人来抢时说清现况。
+ * @param state - 当前有效的那份约定。
+ * @returns 形如「会话 x（自 HH:mm:ssZ 起在调试 y）」的中文串。
+ */
+export declare function debugOwnerText(state: DebugState): string;

package/dist/host/diy-debug.js

@@ -0,0 +1,88 @@
+/**
+ * 把工具入参收成人话动作。
+ * @param value - 任意入参值。
+ * @returns `'pause'` / `'resume'` / `'stop'` 原样；别的值（含 `undefined`、多余空白、大小写不同）给 `null`，由调用方拒。
+ */
+export function parseDebugIntent(value) {
+    return value === 'pause' || value === 'resume' || value === 'stop' ? value : null;
+}
+/**
+ * 调试约定的有效期（4 小时，毫秒）：超过它没动静的约定算过期、当场让人。
+ */
+export const DEBUG_STALE_MS = 4 * 60 * 60 * 1000;
+function alive(state, now) {
+    if (state === null)
+        return null;
+    return now - state.at <= DEBUG_STALE_MS ? state : null;
+}
+function ownerOf(state, sessionId, now) {
+    const held = alive(state, now);
+    if (held === null)
+        return 'none';
+    return held.sessionId === sessionId ? held : 'not-owner';
+}
+/**
+ * 造一份新的调试约定存储（进程内存，同一时刻只可能有一份有效约定）。
+ * @returns 存取口；动作成不成都在返回的 `DebugMove` 里，不抛异常。
+ */
+export function createDebugStore() {
+    let held = null;
+    const live = (now) => alive(held, now);
+    return {
+        live,
+        begin(pact) {
+            const current = alive(held, pact.now);
+            if (current !== null) {
+                return { ok: false, code: current.sessionId === pact.sessionId ? 'already-held' : 'held-by-other' };
+            }
+            const state = {
+                phase: 'debugging',
+                sessionId: pact.sessionId,
+                workspacePath: pact.workspacePath,
+                title: pact.title,
+                board: pact.board,
+                unit: pact.unit,
+                name: pact.name,
+                startedAt: pact.now,
+                at: pact.now,
+            };
+            held = state;
+            return { ok: true, state };
+        },
+        pause(sessionId, now) {
+            const found = ownerOf(held, sessionId, now);
+            if (typeof found === 'string')
+                return { ok: false, code: found };
+            if (found.phase === 'paused')
+                return { ok: false, code: 'already-paused' };
+            const state = { ...found, phase: 'paused', at: now };
+            held = state;
+            return { ok: true, state };
+        },
+        resume(sessionId, now) {
+            const found = ownerOf(held, sessionId, now);
+            if (typeof found === 'string')
+                return { ok: false, code: found };
+            if (found.phase === 'debugging')
+                return { ok: false, code: 'already-debugging' };
+            const state = { ...found, phase: 'debugging', at: now };
+            held = state;
+            return { ok: true, state };
+        },
+        stop(sessionId, now) {
+            const found = ownerOf(held, sessionId, now);
+            if (typeof found === 'string')
+                return { ok: false, code: found };
+            held = null;
+            return { ok: true, state: found };
+        },
+    };
+}
+/**
+ * 「谁还占着」的一句话，用于别人来抢时说清现况。
+ * @param state - 当前有效的那份约定。
+ * @returns 形如「会话 x（自 HH:mm:ssZ 起在调试 y）」的中文串。
+ */
+export function debugOwnerText(state) {
+    return `会话 ${state.sessionId}（自 ${new Date(state.startedAt).toISOString().slice(11, 19)}Z 起在调试 ${state.unit}）`;
+}

package/dist/host/diy-record.d.ts

@@ -0,0 +1,135 @@
+/**
+ * 录制交接的三个相位：`armed` 等用户在外站页面上动手，`recording` 正在录，`finished` 录完待取。
+ */
+export type RecordPhase = 'armed' | 'recording' | 'finished';
+/**
+ * 录制约定的有效期（15 分钟，毫秒）：超过它没动静的约定算过期、当场让人。
+ */
+export declare const RECORD_STALE_MS: number;
+/**
+ * 这次录制要找的那一次写：HTTP 方法 + URL 里必须含的一段（不填就是只认方法）。
+ */
+export interface RecordExpect {
+    readonly method: string;
+    readonly urlContains: string;
+}
+/**
+ * 一次「截图」在宿主台账里的那一行：页面上的计数、落图那一刻、落盘路径；没落下来时带 `error` 原文（落成的那条没有它）。
+ */
+export interface RecordShot {
+    readonly n: number;
+    readonly at: number;
+    readonly path: string;
+    readonly error?: string;
+}
+/**
+ * 某个页面计数已经试过几次：初拍算一次，失败再试一次；计数一换就从头数。
+ */
+export interface RecordShotTries {
+    readonly n: number;
+    readonly tries: number;
+}
+/**
+ * 一张图最多试几次（初拍 + 一次重试）：失败如实报过就停，不每拍重试到底。
+ */
+export declare const RECORD_SHOT_TRIES = 2;
+/**
+ * 一份活着的录制约定：相位 + 谁的会话 + 哪个工作区 / 单元 + 页面 URL 与标题 + 要找的那一次写 +
+ * 落盘文件 + 三个时间戳，以及两份台账：按计数落图的 `shots`（`shotsSeen` 只记落成的那个计数）
+ * 与门铃的 `beats` / `beatMs`（命中几次、最近一次等了多久）。
+ */
+export interface RecordState {
+    readonly phase: RecordPhase;
+    readonly sessionId: string;
+    readonly workspace: string;
+    readonly unit: string;
+    readonly name: string;
+    readonly url: string;
+    readonly title: string;
+    readonly action: string;
+    readonly expect: RecordExpect | null;
+    readonly captureFile: string;
+    readonly startedAt: number;
+    readonly t0: number | null;
+    readonly t1: number | null;
+    readonly shots: readonly RecordShot[];
+    readonly shotsSeen: number;
+    readonly shotTries: RecordShotTries | null;
+    readonly beats: number;
+    readonly beatMs: number;
+    readonly at: number;
+}
+/**
+ * 开一次录制要交的那几件：会话、工作区、单元、名字、页面 URL 与标题、动作名、期望、落盘文件，以及此刻时间。
+ */
+export interface RecordPact {
+    readonly sessionId: string;
+    readonly workspace: string;
+    readonly unit: string;
+    readonly name: string;
+    readonly url: string;
+    readonly title: string;
+    readonly action: string;
+    readonly expect: RecordExpect | null;
+    readonly captureFile: string;
+    readonly now: number;
+}
+/**
+ * 录制被拒的原因码：自己已持有 / 别人持着 / 不是持有者 / 没有约定 / 已在录 / 还没 arm / 不在录 / 还没录完。
+ */
+export type RecordRefusal = 'already-held' | 'held-by-other' | 'not-owner' | 'none' | 'already-recording' | 'not-armed' | 'not-recording' | 'not-finished';
+/**
+ * 一次录制动作的结果：成功带新状态，失败带拒绝码。
+ */
+export type RecordMove = {
+    readonly ok: true;
+    readonly state: RecordState;
+} | {
+    readonly ok: false;
+    readonly code: RecordRefusal;
+};
+/**
+ * 录制约定收得下的三个人话动作：看看进度 / 停手 / 结束并取回。
+ */
+export type RecordIntent = 'peek' | 'halt' | 'stop';
+/**
+ * 把工具入参收成人话动作。
+ * @param raw - 任意入参值。
+ * @returns `'peek'` / `'halt'` / `'stop'` 原样；别的值（含 `undefined`、多余空白）给 `null`，由调用方拒。
+ */
+export declare function parseRecordIntent(raw: unknown): RecordIntent | null;
+/**
+ * 录制约定的存取口（外壳持有一份）：相位随 `begin → started → finished` 推进，`release` 是收尾时放掉浏览器那一跳。
+ */
+export interface RecordStore {
+    readonly release?: ((state: RecordState) => Promise<{
+        readonly tab: boolean;
+        readonly capture: boolean;
+    }>) | undefined;
+    live(now: number): RecordState | null;
+    begin(pact: RecordPact): RecordMove;
+    started(sessionId: string, at: number, now: number): RecordMove;
+    finished(sessionId: string, at: number, now: number): RecordMove;
+    shotTaken(sessionId: string, shot: RecordShot, now: number): RecordMove;
+    shotFailed(sessionId: string, shot: RecordShot, now: number): RecordMove;
+    beat(sessionId: string, ms: number, now: number): RecordMove;
+    stop(sessionId: string, now: number): RecordMove;
+}
+/**
+ * 这一拍该不该落图：页面计数涨过 `shotsSeen` 才算；同一个计数已经试满就先放下，等他自己再按。
+ * @param state - 当前有效的那份约定。
+ * @param pageShots - 页面浮条上那个「已拍」计数。
+ * @returns 该落的那个计数；不该落给 `null`（没涨 / 试满了 / 不是个正经数）。
+ */
+export declare function shotDueOf(state: RecordState, pageShots: number): number | null;
+/**
+ * 造一份新的录制约定存储（进程内存，同一时刻只可能有一份有效约定）。
+ * @returns 存取口；动作成不成都在返回的 `RecordMove` 里，不抛异常。
+ */
+export declare function createRecordStore(): RecordStore;
+/**
+ * 「谁还占着、在录哪个动作」的一句话，用于别人来抢时说清现况。
+ * @param state - 当前有效的那份约定。
+ * @returns 形如「会话 x（自 HH:mm:ssZ 起在录 y 的「动作」）」的中文串。
+ */
+export declare function recordOwnerText(state: RecordState): string;

package/dist/host/diy-record.js

@@ -0,0 +1,162 @@
+/**
+ * 录制约定的有效期（15 分钟，毫秒）：超过它没动静的约定算过期、当场让人。
+ */
+export const RECORD_STALE_MS = 15 * 60 * 1000;
+/**
+ * 一张图最多试几次（初拍 + 一次重试）：失败如实报过就停，不每拍重试到底。
+ */
+export const RECORD_SHOT_TRIES = 2;
+/**
+ * 把工具入参收成人话动作。
+ * @param raw - 任意入参值。
+ * @returns `'peek'` / `'halt'` / `'stop'` 原样；别的值（含 `undefined`、多余空白）给 `null`，由调用方拒。
+ */
+export function parseRecordIntent(raw) {
+    return raw === 'peek' || raw === 'halt' || raw === 'stop' ? raw : null;
+}
+/**
+ * 这一拍该不该落图：页面计数涨过 `shotsSeen` 才算；同一个计数已经试满就先放下，等他自己再按。
+ * @param state - 当前有效的那份约定。
+ * @param pageShots - 页面浮条上那个「已拍」计数。
+ * @returns 该落的那个计数；不该落给 `null`（没涨 / 试满了 / 不是个正经数）。
+ */
+export function shotDueOf(state, pageShots) {
+    if (!Number.isFinite(pageShots))
+        return null;
+    const n = Math.floor(pageShots);
+    if (n <= state.shotsSeen)
+        return null;
+    if (state.shotTries !== null && state.shotTries.n === n && state.shotTries.tries >= RECORD_SHOT_TRIES)
+        return null;
+    return n;
+}
+function alive(state, now) {
+    if (state === null)
+        return null;
+    return now - state.at <= RECORD_STALE_MS ? state : null;
+}
+function ownerOf(state, sessionId, now) {
+    const held = alive(state, now);
+    if (held === null)
+        return 'none';
+    return held.sessionId === sessionId ? held : 'not-owner';
+}
+/**
+ * 造一份新的录制约定存储（进程内存，同一时刻只可能有一份有效约定）。
+ * @returns 存取口；动作成不成都在返回的 `RecordMove` 里，不抛异常。
+ */
+export function createRecordStore() {
+    let held = null;
+    const live = (now) => alive(held, now);
+    const withShot = (found, shot, now, error) => {
+        const row = error === undefined ? shot : { n: shot.n, at: shot.at, path: shot.path, error };
+        const kept = found.shots.filter((one) => one.n !== shot.n);
+        const tries = found.shotTries !== null && found.shotTries.n === shot.n ? found.shotTries.tries : 0;
+        return {
+            ...found,
+            shots: [...kept, row].sort((one, two) => one.n - two.n),
+            shotsSeen: error === undefined ? Math.max(found.shotsSeen, shot.n) : found.shotsSeen,
+            shotTries: error === undefined ? null : { n: shot.n, tries: tries + 1 },
+            at: now,
+        };
+    };
+    return {
+        live,
+        begin(pact) {
+            const current = alive(held, pact.now);
+            if (current !== null) {
+                return { ok: false, code: current.sessionId === pact.sessionId ? 'already-held' : 'held-by-other' };
+            }
+            const state = {
+                phase: 'armed',
+                sessionId: pact.sessionId,
+                workspace: pact.workspace,
+                unit: pact.unit,
+                name: pact.name,
+                url: pact.url,
+                title: pact.title,
+                action: pact.action,
+                expect: pact.expect,
+                captureFile: pact.captureFile,
+                startedAt: pact.now,
+                t0: null,
+                t1: null,
+                shots: [],
+                shotsSeen: 0,
+                shotTries: null,
+                beats: 0,
+                beatMs: 0,
+                at: pact.now,
+            };
+            held = state;
+            return { ok: true, state };
+        },
+        started(sessionId, at, now) {
+            const found = ownerOf(held, sessionId, now);
+            if (typeof found === 'string')
+                return { ok: false, code: found };
+            if (found.phase === 'recording')
+                return { ok: false, code: 'already-recording' };
+            if (found.phase !== 'armed')
+                return { ok: false, code: 'not-armed' };
+            const state = { ...found, phase: 'recording', t0: at, at: now };
+            held = state;
+            return { ok: true, state };
+        },
+        finished(sessionId, at, now) {
+            const found = ownerOf(held, sessionId, now);
+            if (typeof found === 'string')
+                return { ok: false, code: found };
+            if (found.phase !== 'recording')
+                return { ok: false, code: 'not-recording' };
+            const state = { ...found, phase: 'finished', t1: at, at: now };
+            held = state;
+            return { ok: true, state };
+        },
+        shotTaken(sessionId, shot, now) {
+            const found = ownerOf(held, sessionId, now);
+            if (typeof found === 'string')
+                return { ok: false, code: found };
+            const state = withShot(found, shot, now, undefined);
+            held = state;
+            return { ok: true, state };
+        },
+        shotFailed(sessionId, shot, now) {
+            const found = ownerOf(held, sessionId, now);
+            if (typeof found === 'string')
+                return { ok: false, code: found };
+            const state = withShot(found, shot, now, shot.error === undefined ? '落图失败' : shot.error);
+            held = state;
+            return { ok: true, state };
+        },
+        beat(sessionId, ms, now) {
+            const found = ownerOf(held, sessionId, now);
+            if (typeof found === 'string')
+                return { ok: false, code: found };
+            const state = {
+                ...found,
+                beats: found.beats + 1,
+                beatMs: Math.max(0, Math.floor(ms)),
+                at: now,
+            };
+            held = state;
+            return { ok: true, state };
+        },
+        stop(sessionId, now) {
+            const found = ownerOf(held, sessionId, now);
+            if (typeof found === 'string')
+                return { ok: false, code: found };
+            held = null;
+            return { ok: true, state: found };
+        },
+    };
+}
+/**
+ * 「谁还占着、在录哪个动作」的一句话，用于别人来抢时说清现况。
+ * @param state - 当前有效的那份约定。
+ * @returns 形如「会话 x（自 HH:mm:ssZ 起在录 y 的「动作」）」的中文串。
+ */
+export function recordOwnerText(state) {
+    const at = new Date(state.startedAt).toISOString().slice(11, 19);
+    return `会话 ${state.sessionId}（自 ${at}Z 起在录 ${state.unit} 的「${state.action}」）`;
+}

package/dist/host/events.d.ts

@@ -0,0 +1,9 @@
+import type { DshHostContext, DshRequest, DshResponse } from '@dsh-workbench/shared';
+import type { FactLog } from './facts';
+export interface FactStream {
+    handler(req: DshRequest, res: DshResponse): void;
+    closeAll(): void;
+    size(): number;
+}
+export declare function createFactStream(log: FactLog): FactStream;
+export declare function registerFactStream(ctx: DshHostContext, log: FactLog): () => void;

package/dist/host/events.js

@@ -0,0 +1,70 @@
+import { EVENTS_PATH } from '@dsh-workbench/shared';
+const HEARTBEAT_MS = 25_000;
+function frame(payload) {
+    return `data: ${JSON.stringify(payload)}\n\n`;
+}
+export function createFactStream(log) {
+    const connections = new Set();
+    const cleanups = new Map();
+    const drop = (res) => {
+        cleanups.get(res)?.();
+        cleanups.delete(res);
+        connections.delete(res);
+    };
+    return {
+        size: () => connections.size,
+        closeAll() {
+            for (const res of [...connections]) {
+                drop(res);
+                res.end?.();
+            }
+        },
+        handler(req, res) {
+            if (req.method !== undefined && req.method !== 'GET') {
+                res.statusCode = 405;
+                res.end();
+                return;
+            }
+            const url = req.url ?? '/';
+            const cut = url.indexOf('?');
+            const since = Number(new URLSearchParams(cut === -1 ? '' : url.slice(cut + 1)).get('since') ?? 0) || 0;
+            const opening = log.since(since);
+            if (typeof res.write !== 'function') {
+                res.statusCode = 200;
+                res.setHeader('content-type', 'application/json; charset=utf-8');
+                res.end(JSON.stringify({ ok: true, ...opening }));
+                return;
+            }
+            const headers = {
+                'content-type': 'text/event-stream; charset=utf-8',
+                'cache-control': 'no-store, no-transform',
+                connection: 'keep-alive',
+            };
+            if (typeof res.writeHead === 'function')
+                res.writeHead(200, headers);
+            else {
+                res.statusCode = 200;
+                for (const [name, value] of Object.entries(headers))
+                    res.setHeader(name, value);
+            }
+            res.write(': connected\n\n');
+            res.write(frame({ type: 'sync', ...opening }));
+            connections.add(res);
+            const timer = setInterval(() => res.write?.(': ping\n\n'), HEARTBEAT_MS);
+            const unsubscribe = log.subscribe((change) => res.write?.(frame({ type: 'bump', ...change })));
+            cleanups.set(res, () => {
+                clearInterval(timer);
+                unsubscribe();
+            });
+            res.on?.('close', () => drop(res));
+        },
+    };
+}
+export function registerFactStream(ctx, log) {
+    const stream = createFactStream(log);
+    const unregister = ctx.webServer.register({ kind: 'exact', path: EVENTS_PATH, handler: stream.handler });
+    return () => {
+        stream.closeAll();
+        unregister();
+    };
+}

package/dist/host/facts.d.ts

@@ -22,3 +22,9 @@ export interface ToolUnit {
 }
 export declare function toolUnits(manifests: readonly UnitManifest[]): Map<string, ToolUnit>;
 export declare function wroteNow(result: unknown): boolean | undefined;
+/**
+ * 由单元 id 拼出它那一族事实的范围名。
+ * @param unit 单元 id，不带后缀。
+ * @returns <unit>* —— 永远是范围名，不是某一条事实。
+ */
+export declare function unitFactScope(unit: string): string;

package/dist/host/facts.js

@@ -1,3 +1,4 @@
+import { FACT_SCOPE_SUFFIX } from '../api/facts.js';
 export function createFactLog(options = {}) {
     const epoch = options.epoch ?? `e${Date.now().toString(36)}${Math.random().toString(36).slice(2, 8)}`;
     let rev = 0;
@@ -42,3 +43,11 @@ export function wroteNow(result) {
     const wrote = value?.wrote;
     return typeof wrote === 'boolean' ? wrote : undefined;
 }
+/**
+ * 由单元 id 拼出它那一族事实的范围名。
+ * @param unit 单元 id，不带后缀。
+ * @returns <unit>* —— 永远是范围名，不是某一条事实。
+ */
+export function unitFactScope(unit) {
+    return `${unit}${FACT_SCOPE_SUFFIX}`;
+}

package/dist/host/git.js

@@ -1,4 +1,4 @@
-import { quoteShellArg, tailLines } from '../lib/text.js';
+import { quoteShellArg, tailLines } from './shell-text.js';
 import { runShell } from './shell.js';
 export function createHeadReader(options) {
     const { shell, logger } = options;

package/dist/host/http.d.ts

@@ -1,5 +1,5 @@
 import type { DshHostContext } from '../api/dsh.js';
-import { type PanelStateStore } from '../lib/panel-state.js';
+import { type PanelStateStore } from './panel-state.js';
 import { type ProvisionHandler } from './provision.js';
 export type RouteHandler = (search: URLSearchParams) => Promise<unknown> | unknown;
 export type RouteTable = Record<string, RouteHandler>;
@@ -27,7 +27,7 @@ export declare function changesHandler(log: {
 }): RouteHandler;
 export declare function preflightHandler(preflight: {
     run(options?: {
-        force?: boolean;
+        hard?: boolean;
     }): Promise<unknown>;
     snapshot(): unknown;
 }): RouteHandler;

package/dist/host/http.js

@@ -1,5 +1,5 @@
-import { unitFactScope } from '../api/facts.js';
-import { parseCardsReport, parseCrashReport } from '../lib/panel-state.js';
+import { unitFactScope } from './facts.js';
+import { parseCardsReport, parseCrashReport } from './panel-state.js';
 import { ACTIONS_PREFIX, API_PREFIX, DIY_DEBUG_PATH, DIY_RECORD_PATH, PANEL_STATE_PREFIX, PLUGIN_ID, PREFS_PREFIX, PROVISION_PREFIX } from '../config/constants.js';
 import { parseProvisionBody, } from './provision.js';
 import { WorkbenchDataError } from '../host/opencli.js';
@@ -179,7 +179,7 @@ export function changesHandler(log) {
 }
 export function preflightHandler(preflight) {
     return (search) => {
-        void preflight.run({ force: flag(search, 'force') });
+        void preflight.run({ hard: flag(search, 'hard') });
         return { ok: true, ...preflight.snapshot() };
     };
 }

package/dist/host/long-task.d.ts

@@ -10,35 +10,46 @@ export interface LongTaskBase {
     readonly why?: string | undefined;
     readonly startedAt: string;
     readonly at: string;
+    readonly session?: string | undefined;
 }
 export interface LongTaskStart {
     readonly workspace: string;
     readonly target: string;
     readonly payload?: unknown;
+    readonly session?: string | undefined;
 }
 export interface LongTaskChange<S extends LongTaskBase> {
     readonly kind: 'start' | 'step' | 'settle';
     readonly snapshot: S;
     readonly step?: LongTaskStep | undefined;
+    readonly by?: string | undefined;
 }
 export interface LongTaskDeps<S extends LongTaskBase> {
     readonly run: (options: {
         readonly payload: unknown;
         readonly onStep: (step: LongTaskStep) => void;
+        readonly signal: AbortSignal;
     }) => Promise<unknown>;
     readonly step?: ((step: LongTaskStep, current: S) => Partial<S>) | undefined;
     readonly outcome?: ((result: unknown, current: S) => Partial<S>) | undefined;
+    readonly stopped?: ((current: S) => Partial<S>) | undefined;
     readonly view: (snapshot: S) => Readonly<Record<string, unknown>>;
     readonly now?: (() => string) | undefined;
     readonly nextId?: (() => string) | undefined;
     readonly facts?: ((change: LongTaskChange<S>) => readonly string[] | undefined) | undefined;
     readonly recentMs?: number | undefined;
 }
+/**
+ * 一个单元的长任务注册表：`current(workspace)` 是面板那一行要的投影，`live()` 是外壳侧栏那颗
+ * loading 点要的（**不分工作区、不分目标**，把现在活着的每一趟交出来），`stop` 只把中断信号转给生产方。
+ */
 export interface LongTaskRegistry<S extends LongTaskBase> {
     start(options: LongTaskStart): S;
     snapshot(id: string): S | null;
     active(workspace: string, target: string): S | null;
     current(workspace: string): readonly Readonly<Record<string, unknown>>[];
+    live(): readonly S[];
+    stop(id: string, by?: string): boolean;
     onChange(listener: (change: LongTaskChange<S>) => void): () => void;
 }
 export declare function createLongTaskRegistry<S extends LongTaskBase>(deps: LongTaskDeps<S>): LongTaskRegistry<S>;
@@ -52,6 +63,7 @@ export declare function createLongTaskHost(options: {
     readonly scope: string;
     readonly unit: string;
     readonly bump: (facts: readonly string[]) => void;
+    readonly notify?: ((change: LongTaskChange<LongTaskBase>) => void) | undefined;
 }): {
     readonly host: LongTaskHost;
     dispose(): void;