@mstar-harness/dsh 3.7.2 → 3.8.0

package/README.i18n.yaml

@@ -2,5 +2,5 @@
 # Blob hashes (git hash-object) of each side as of the last confirmation that
 # both languages say the same thing (dsh i18n contract: a pair is three
 # sibling files; editing either side obligates re-confirming and re-recording).
-README.md: 189bec515fe5fce73de5afad7e2d1678e0f55ea5
-README.zh.md: 05affb493e99da9b45d0b8dd2743ccedaecc0b11
+README.md: 5d6f594ff5a64d84c2e5900d3118f744351cf32b
+README.zh.md: 054b5415b2fa53e5bfae1e78d22e3a9625886b4a

package/README.md

@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-![dsh](https://img.shields.io/badge/dsh-0.1.2--rc.1-4B32C3.svg)
+![dsh](https://img.shields.io/badge/dsh-0.1.5--rc.1-4B32C3.svg)
 
 [Morning Star](https://github.com/btspoony/mstar-harness) as a first-class dsh (DeepSeek Harness) host — a cordis function plugin that mounts the mstar engine in-process, implements the engine `HostAdapter` (`host: 'dsh'`), guards `{HARNESS_DIR}/status.json` writes (validate + advisory; repair-escape under hard), blocks disallowed subagent dispatches when `Enforcement: hard` is on, lints `SKILL.md` writes under the mounted skill roots, mounts the mstar `skills/` mirror through the dsh skill-filesystem provider (single canonical mount), and appends a durable `mstar-engine-status` catalog row to every composed agent step. Boot with a dsh Loader app; everything acts through the seam's refusal/advisory channels, never by patching the tools.
 
@@ -233,7 +233,7 @@ Every engine module attaches to a dsh surface — delivered except the lint modu
 | host (resolveSkillRoot, HostAdapter) | engine host.ts detection row + plugin adapter (`host: 'dsh'`) | delivered (P2) |
 | skill-authoring (lintFrontmatter, lintFiveQuestion) | skill-filesystem roots + `fs/write-intent` on SKILL.md | delivered (P2) |
 | lint (lintSkillFrontmatter, planQualityBar, assertSddTddTriple) | not wired — plan/tdd fs gates are a deferral; `lintSkillFrontmatter` runs only in the skills-mount test suite | deferred |
-| agent catalog | MessageSourceMap `mstar-engine-status` (model-visible ⟺ logged) | delivered (P2) |
+| agent catalog | first-party `plugin` catalog source (the anchor) + `/api/mstar/engineStatus` snapshot read (model-visible ⟺ logged) | delivered (P2) |
 | sdd (sddWorkspace, taskBrief) | `defineTool` wrappers registered on `ctx.tools` | delivered (P3) |
 | iteration (evaluatePhaseGate, parseCompassFrontmatter) | `agent/pre-step` + iteration gate | delivered (P3) |
 | worktree (l1PreDispatchCheck, l2PreDispatchCheck) | `tools/pre-execute` L1/L2 (inside the dispatch gate) | delivered (P3) |
@@ -241,7 +241,7 @@ Every engine module attaches to a dsh surface — delivered except the lint modu
 
 ## Engine-status catalog
 
-An advisory `agent/pre-step` waterfall listener appends ONE **`mstar-engine-status`** catalog MessageSource to every composed step (the `kind`/`form: 'catalog'` contract, mirroring the dsh tool-skill precedent): the model-visible `<mstar_engine_status>` block renders the watermark fields — **mstar version** (plugin own manifest; the single-version invariant pins the bundled engine to the same version), **harness dir** (resolved `{HARNESS_DIR}`, `none` when absent), and **enforcement** (compass mode, `soft` / `hard (compass)`) — plus the **iteration phase-gate section** (when a steering compass + `status.json` resolve: iteration id, transition, all-plans-done, gate verdict + violation codes — the `mstar iteration gate` tool result shape) and the **workspace-state digest section** (when the workspace has a `status.json`): **plans** (`id(status)` registry), **residuals** (open counts by severity), **branch** (base → target, spec integration), **policy** (push policy, worktree mode, control root), **leases** (active plan execution leases: holder + worktree), **knowledge** (knowledge-index doc count + categories) and **direction** (the steering compass's problem-statement one-liner). The listener calls `next()` first and builds on the delegated decision — it never vetoes a step and never replaces the composed messages. Model-visible ⟺ logged: the durable `catalog`-form source records the facts it published beside the model-facing prose, so the session log reconstructs the row without re-parsing the block (dsh packages/AGENTS.md). Fiber disposal removes the listener (HMR-safe).
+An advisory `agent/pre-step` waterfall listener appends ONE **`mstar-engine-status`** catalog MessageSource to every composed step — the first-party `plugin` arm, exactly `{ kind: 'plugin', plugin: 'mstar-engine-status', form: 'catalog' }` and **no other member** (mirroring the dsh tool-skill precedent): the model-visible `<mstar_engine_status>` block renders the watermark fields — **mstar version** (plugin own manifest; the single-version invariant pins the bundled engine to the same version), **harness dir** (resolved `{HARNESS_DIR}`, `none` when absent), and **enforcement** (compass mode, `soft` / `hard (compass)`) — plus the **iteration phase-gate section** (when a steering compass + `status.json` resolve: iteration id, transition, all-plans-done, gate verdict + violation codes — the `mstar iteration gate` tool result shape) and the **workspace-state digest section** (when the workspace has a `status.json`): **plans** (`id(status)` registry), **residuals** (open counts by severity), **branch** (base → target, spec integration), **policy** (push policy, worktree mode, control root), **leases** (active plan execution leases: holder + worktree), **knowledge** (knowledge-index doc count + categories) and **direction** (the steering compass's problem-statement one-liner). The listener calls `next()` first and builds on the delegated decision — it never vetoes a step and never replaces the composed messages. Model-visible ⟺ logged: the persisted source carries no facts — the row is the durable **anchor** and the exact emitted payload is snapshotted per session at `{HARNESS_DIR}/snapshots/engine-status.json` in this same digest-gated emission, so the session log plus that store reconstruct the row without re-parsing the block (dsh packages/AGENTS.md). No released session-format edge admits extra members on a message source, so nothing but the `plugin` arm is ever written there. The workflow panel reads that snapshot on demand over the host's shared `/api` typert gateway: the **host gateway owns the route** (a plugin cannot register one; a plain `connection.rpc.handle` channel mounts through `webServer` on the calling fiber and would pend this row's boot — the mechanism this package deliberately does not use) and this package contributes the `mstar/engineStatus` endpoint descriptor through an optional `ctx.typert.register(...)` child. The browser half calls `connection.rpc.call('/api', 'mstar/engineStatus', { args: { sessionId, cwd } })` and receives that session's stored snapshot, or an explicit `unavailable` reason (never another session's data, never silently-empty fields). **Trust boundary, stated plainly:** the endpoint authenticates nothing of its own — the transport fence (host/origin + browser auth) establishes only that the caller is a page this host served, so *possession of a `(sessionId, cwd)` pair plus reachability of the local `/api` gateway is the capability*. An answer is scoped to the REQUEST: the lookup is keyed by the asserted id, the stored record's `cwd` must equal both the asserted and the server-resolved session `cwd`, and the client re-checks the echoed id and workspace before rendering — so one session's request can never be served another session's row. The payload is a workspace digest (version, harness dir, enforcement, plan/residual/lease counters) that the panel's own session transcript already exposes; it is not treated as a secret, and the distinct `unavailable` reasons make the endpoint a weak session-existence oracle for a caller who already holds the id. Fiber disposal removes the listener (HMR-safe).
 
 The row is **digest-gated**: per agent+workspace it is injected once per turn and re-injected only when its rendered text changed — a 20-step turn shows the catalog once, not 20 times. The source shares ONE per-workspace cache entry, built at boot for an explicit `harnessDir` (else on the workspace's first pre-step) and TTL-refreshed (`catalogTtlMs`, default 60 s) — the hot path is a timestamp compare + Map lookup between refreshes, and a mid-session plan/compass/residual change lands within one interval.
 

package/README.zh.md

@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-![dsh](https://img.shields.io/badge/dsh-0.1.2--rc.1-4B32C3.svg)
+![dsh](https://img.shields.io/badge/dsh-0.1.5--rc.1-4B32C3.svg)
 
 让 [Morning Star](https://github.com/btspoony/mstar-harness) 成为一等公民的 dsh（DeepSeek Harness）宿主——一个 cordis 函数插件，将 mstar engine 进程内挂载，实现 engine `HostAdapter`（`host: 'dsh'`），守护 `{HARNESS_DIR}/status.json` 写入（校验 + 咨询；hard 下按修复逃生放行），在 `Enforcement: hard` 开启时阻止被禁止的 subagent 派发，对挂载技能根下的 `SKILL.md` 写入执行技能撰写 lint，通过 dsh skill-filesystem 提供者挂载 mstar `skills/` 镜像（单一规范挂载），并向每个组合后的 agent 步骤追加一条持久化的 `mstar-engine-status` catalog 行。随 dsh Loader 应用启动；一切均通过 seam 的拒绝/咨询通道行使职责，从不改动工具本身。
 
@@ -232,7 +232,7 @@ mstar 技能通过 dsh skill-filesystem 提供者以**单一规范挂载**接入
 | host（resolveSkillRoot、HostAdapter） | engine host.ts 检测行 + 插件适配器（`host: 'dsh'`） | 已交付（P2） |
 | skill-authoring（lintFrontmatter、lintFiveQuestion） | skill-filesystem 根 + 对 SKILL.md 的 `fs/write-intent` | 已交付（P2） |
 | lint（lintSkillFrontmatter、planQualityBar、assertSddTddTriple） | 未接线——plan/tdd 的 fs 闸门为延后项；`lintSkillFrontmatter` 仅运行于 skills-mount 测试套件 | 延后 |
-| agent catalog | MessageSourceMap `mstar-engine-status`（模型可见 ⟺ 已记录） | 已交付（P2） |
+| agent catalog | 一方 `plugin` catalog source（锚点）+ `/api/mstar/engineStatus` 快照读取（模型可见 ⟺ 已记录） | 已交付（P2） |
 | sdd（sddWorkspace、taskBrief） | 注册在 `ctx.tools` 上的 `defineTool` 包装 | 已交付（P3） |
 | iteration（evaluatePhaseGate、parseCompassFrontmatter） | `agent/pre-step` + iteration 闸门 | 已交付（P3） |
 | worktree（l1PreDispatchCheck、l2PreDispatchCheck） | `tools/pre-execute` L1/L2（派发闸门内） | 已交付（P3） |
@@ -240,7 +240,7 @@ mstar 技能通过 dsh skill-filesystem 提供者以**单一规范挂载**接入
 
 ## Engine-status catalog
 
-一个咨询式 `agent/pre-step` 瀑布监听器向每个组合后的步骤追加**一条** **`mstar-engine-status`** catalog MessageSource（`kind`/`form: 'catalog'` 契约，镜像 dsh tool-skill 先例）：模型可见的 `<mstar_engine_status>` 块渲染水印字段——**mstar 版本**（插件自身清单；单一版本不变量把打包的 engine 钉在同一版本）、**harness 目录**（解析后的 `{HARNESS_DIR}`，缺失为 `none`）、**enforcement**（compass 模式，`soft` / `hard (compass)`）——以及 **迭代相位闸门段**（当 steering compass + `status.json` 可解析时：迭代 id、transition、all-plans-done、闸门判定 + 违规码——即 `mstar iteration gate` 工具结果形态）与 **工作区状态摘要段**（当工作区有 `status.json` 时）：**plans**（`id(status)` 注册表）、**residuals**（按 severity 的 open 计数）、**branch**（base → target、spec 集成）、**policy**（push 政策、worktree 模式、control 根）、**leases**（活跃 plan 执行租约：持有者 + worktree）、**knowledge**（知识索引文档数与分类）与 **direction**（steering compass 的 problem statement 一句话）。监听器先调用 `next()` 并基于委托后的决策追加——从不否决步骤、从不替换已组合的消息。模型可见 ⟺ 已记录：持久化的 `catalog` 形态 source 在模型面向的散文旁记录了其发布的事实，会话日志无需重新解析该块即可重建该行（dsh packages/AGENTS.md）。fiber 销毁即移除监听器（HMR 安全）。
+一个咨询式 `agent/pre-step` 瀑布监听器向每个组合后的步骤追加**一条** **`mstar-engine-status`** catalog MessageSource——一方 `plugin` 臂，即恰好 `{ kind: 'plugin', plugin: 'mstar-engine-status', form: 'catalog' }`、**不含任何其它成员**（镜像 dsh tool-skill 先例）：模型可见的 `<mstar_engine_status>` 块渲染水印字段——**mstar 版本**（插件自身清单；单一版本不变量把打包的 engine 钉在同一版本）、**harness 目录**（解析后的 `{HARNESS_DIR}`，缺失为 `none`）、**enforcement**（compass 模式，`soft` / `hard (compass)`）——以及 **迭代相位闸门段**（当 steering compass + `status.json` 可解析时：迭代 id、transition、all-plans-done、闸门判定 + 违规码——即 `mstar iteration gate` 工具结果形态）与 **工作区状态摘要段**（当工作区有 `status.json` 时）：**plans**（`id(status)` 注册表）、**residuals**（按 severity 的 open 计数）、**branch**（base → target、spec 集成）、**policy**（push 政策、worktree 模式、control 根）、**leases**（活跃 plan 执行租约：持有者 + worktree）、**knowledge**（知识索引文档数与分类）与 **direction**（steering compass 的 problem statement 一句话）。监听器先调用 `next()` 并基于委托后的决策追加——从不否决步骤、从不替换已组合的消息。模型可见 ⟺ 已记录：持久化的 source 不携带任何事实——该行是持久化的**锚点**，其**实际发出**的 payload 在同一次 digest 门控发射时按会话快照到 `{HARNESS_DIR}/snapshots/engine-status.json`，因此「会话日志 + 该存储」无需重新解析该块即可重建该行（dsh packages/AGENTS.md）。任何已发布的会话格式边界都不接受 message source 上的多余成员，故 `source` 上永远只写 `plugin` 臂。工作流面板通过宿主共享的 `/api` typert 网关按需读取该快照：**路由由宿主网关持有**（插件无法注册路由；`connection.rpc.handle` 的普通信道会经由调用 fiber 上的 `webServer` 挂载、并使本行的 boot 挂起——本包刻意不走该机制），本包只经可选 `ctx.typert.register(...)` 子单元贡献 `mstar/engineStatus` 端点描述符。浏览器半体调用 `connection.rpc.call('/api', 'mstar/engineStatus', { args: { sessionId, cwd } })`，得到该会话自己的已存快照，或带原因的显式 `unavailable`（绝不返回其它会话的数据、绝不静默空字段）。**信任边界，如实说明：**该端点自身不做任何鉴权——传输层围栏（host/origin + 浏览器鉴权）只证明调用方是本宿主自己服务的页面，因此*持有 `(sessionId, cwd)` 组合 + 能访问本机 `/api` 网关即为能力*。应答按**请求**限定：查询以被断言的 id 为键，存储记录的 `cwd` 必须同时等于断言值与服务端解析出的会话 `cwd`，客户端在渲染前还会复核回显的 id 与工作区——因此一个会话的请求绝不会被返回另一个会话的记录。payload 是工作区摘要（版本、harness 目录、enforcement、plan/residual/lease 计数），面板自身的会话记录本就暴露这些信息；它不被当作机密，而不同的 `unavailable` 原因会让该端点对已持有 id 的调用方成为一个弱的「会话是否存在」探针。fiber 销毁即移除监听器（HMR 安全）。
 
 该行是 **digest 门控**的：按 agent+workspace，每个 turn 只注入一次，仅当渲染文本变化时重新注入——20 步的 turn 只显示一次 catalog，而不是 20 次。source 共享**同一**按工作区缓存条目：显式 `harnessDir` 时在 boot 构建（否则在工作区首次 pre-step 构建），并按 TTL 刷新（`catalogTtlMs`，默认 60 秒）——刷新间隔之间热路径只是时间戳比较 + Map 命中，会话中 plan/compass/residual 的变化在一个间隔内落地。
 

package/bundle/README.md

@@ -99,7 +99,14 @@ boot the web app serves the closure-factory CJS bundle at
 
 The client entry registers a `conversation.view` view-ring tab
 (`id: 'mstar-workflow'`, `order: 20`), labeled **"MStar 工作流" / "MStar
-Workflow"**, rendering the latest `mstar-engine-status` catalog row as the
+Workflow"**, rendering the latest `mstar-engine-status` catalog **anchor** row
+— the persisted source is the bare first-party `plugin` arm
+(`{ kind: 'plugin', plugin: 'mstar-engine-status', form: 'catalog' }`), and the
+payload is fetched from the host's `/api/mstar/engineStatus` endpoint (the
+shared `/api` typert gateway owns the route; the panel's browser half calls
+`connection.rpc.call('/api', 'mstar/engineStatus', { args: { sessionId, cwd } })`
+and renders the session's stored snapshot, or an explicit unavailable reason) —
+as the
 **MStar Workflow layout**: a right sidebar (plans ≤5 time-desc + `+N more`,
 open residual findings ≤10 with severity chips + overflow hint, policy with
 enforcement first, leases, knowledge, direction) over a bottom **fixed meta

package/dist/client/index.d.ts

@@ -2,13 +2,19 @@
  * Morning Star workflow panel — dsh client plugin entry (spec §4.1):
  * `inject` (cordis service waits) + `apply(ctx: ClientContext)`.
  *
- * On apply: registers the `mstar-panel` dictionaries, then waits for the
- * ui-conversation `conversation.view` declaration and registers the panel as
- * a view tab (`id: 'mstar-workflow'`, `order: 20`, locale-following label
- * thunk — the trajectory precedent shape). The tab label re-reads through
- * `ctx.locale.bind(NS)` so a locale switch flips it without re-registering.
+ * On apply: creates the engine-status client over the client `connection`
+ * service (the panel's data path is the host's shared `/api` typert gateway —
+ * the persisted catalog row is only the anchor), registers the `mstar-panel`
+ * dictionaries, then waits for the ui-conversation `conversation.view`
+ * declaration and registers the panel as a view tab (`id: 'mstar-workflow'`,
+ * `order: 20`, locale-following label thunk — the trajectory precedent shape).
+ * The tab label re-reads through `ctx.locale.bind(NS)` so a locale switch
+ * flips it without re-registering.
+ *
+ * The client is created ONCE per apply and disposed with the fiber, so a
+ * reloaded plugin starts from a clean snapshot cache.
  */
 import type { Context as ClientContext } from '@deepseek-ai/cordis';
-/** Cordis service faces the plugin waits for (spec §4.4: slots + sessions + locale). */
+/** Cordis service faces the plugin waits for (spec §4.4: slots + sessions + locale + the wire). */
 export declare const inject: string[];
 export declare function apply(ctx: ClientContext): void;

package/dist/client/panel/PanelView.d.ts

@@ -1,11 +1,13 @@
 /**
  * Morning Star workflow panel page — the `conversation.view` tab component
- * (spec §4.2): pure render of the latest `mstar-engine-status` catalog row.
+ * (spec §4.2): render of the session's engine-status snapshot.
  *
- * Inputs: the session standard kit (`ConvViewProps`) and the typed `t` seat
- * (`locale: 'mstar-panel'`). The catalog row + message time come from the
- * `useMstarEngineStatus()` hook riding the kit's `useChat` selector (spec
- * §5) — the render body is a pure function of (source, lastUpdated, t).
+ * Inputs: the session standard kit (`ConvViewProps` + the session-list seat),
+ * the plugin's engine-status client (bound to the client `connection` service
+ * by the plugin entry) and the typed `t` seat (`locale: 'mstar-panel'`). The
+ * `useMstarEngineStatus()` hook turns the anchor row + the served snapshot
+ * into ONE explicit render state (spec §5) — the render body is a pure
+ * function of (state, payload, snapshot `at`, t).
  *
  * Layout (spec panel-tabs §2): root grid
  * `"main sidebar"` fills the Tab (height 100%, overflow hidden — the page
@@ -26,27 +28,47 @@
  * `<details>` expansion, replacing
  * the muted placeholder AND the AgentEventDock — 无双份日志).
  *
- * Empty branches (spec §2): waiting / no-harness render no tabs / no
- * sidebar. Waiting keeps the muted hint; the no-harness branch renders a
- * CENTERED inactive-state card (icon + title + hint, plan
- *  T3 — replaces the left-aligned hint) with
- * the freshness footer; the no-harness main keeps `data-mstar-graph` on its
- * content container. Degradation stays total: `projectGraph` never throws;
- * no iteration → the IterationTaskPage's collapsed muted head (spec §8);
- * `state` null / plans missing → muted kanban skeleton.
+ * Empty branches (spec §2): waiting / loading / unavailable / no-harness render
+ * no tabs and no sidebar — each with its OWN anchor and copy, so a degraded
+ * read is never mistakable for an empty workspace. Waiting keeps the muted
+ * hint; loading states the pending read; unavailable carries the
+ * machine-readable reason; the no-harness branch renders a CENTERED
+ * inactive-state card (icon + title + hint) with the freshness footer, and its
+ * main keeps `data-mstar-graph` on the content container. Degradation stays
+ * total: `projectGraph` never throws; no iteration → the IterationTaskPage's
+ * collapsed muted head (spec §8); `state` null / plans missing → muted kanban
+ * skeleton.
  */
 import * as React from 'react';
 import type { ConvViewProps } from '@deepseek-ai/dsh-client-ui-conversation/client';
 import type { TranslateNS } from '@deepseek-ai/dsh-client-ui-slots';
-import type { MstarEngineStatusSource } from '../../types.ts';
+import type { SessionId } from '@deepseek-ai/dsh-session';
+import type { MstarEngineStatusPayload } from '../../types.ts';
+import type { MstarEngineStatusClient } from './engine-status-client.ts';
 import { type PanelTab } from './TabNav.tsx';
+import { type UseSessions } from './use-mstar-engine-status.ts';
 export interface MstarPanelViewProps extends ConvViewProps {
     /** Namespace-bound translate seat (`locale: 'mstar-panel'`). */
     t: TranslateNS<'mstar-panel'>;
+    /**
+     * Current session identity — the session standard kit's own prop. Declared
+     * here (rather than inherited) because this package does not depend on the
+     * ui-session adapter that merges the session-kit declarations into
+     * `ConvViewProps`; the view ring always supplies it at runtime.
+     */
+    sessionId?: SessionId;
+    /** Host session-list selector hook (the global standard seat, same reason). */
+    useSessions?: UseSessions;
+    /**
+     * The plugin's engine-status client (bound to the client `connection`
+     * service by the plugin entry). Absent only in a composition that injects
+     * no transport — the panel then reports the explicit `unavailable` state.
+     */
+    engineStatus?: MstarEngineStatusClient;
 }
 export interface PanelContentProps {
     tab: PanelTab;
-    source: MstarEngineStatusSource;
+    source: MstarEngineStatusPayload;
     t: TranslateNS<'mstar-panel'>;
 }
 /**
@@ -61,4 +83,4 @@ export interface PanelContentProps {
  * AgentEventDock — 无双份日志, the dock is removed with this plan).
  */
 export declare function PanelContent({ tab, source, t }: PanelContentProps): React.JSX.Element;
-export declare function PanelView({ t, useChat }: MstarPanelViewProps): React.JSX.Element;
+export declare function PanelView({ t, useChat, useSessions, sessionId, engineStatus }: MstarPanelViewProps): React.JSX.Element;

package/dist/client/panel/engine-status-client.d.ts

@@ -0,0 +1,187 @@
+/**
+ * Client half of the engine-status channel: the per-session snapshot cache the
+ * panel reads and the `/api/mstar/engineStatus` fetch that fills it.
+ *
+ * WHY a cache outside React: the panel is a browser bundle and the payload
+ * lives on the HOST filesystem (the persisted catalog row is only the anchor —
+ * its `source` is the frozen three-member first-party arm). The data therefore
+ * arrives over the host's shared typert `/api` gateway, asynchronously and
+ * repeatedly (every new anchor row asks again). Keeping that state in a small
+ * observable store — rather than component state — gives one request per
+ * (session, anchor) across re-renders, survives the panel unmounting, and lets
+ * the render path read it synchronously.
+ *
+ * KEYING, not adjacency: entries are keyed by session id, and a response is
+ * validated against the session that was REQUESTED
+ * ({@link parseEngineStatusResult}) — session A's panel can never render
+ * session B's snapshot.
+ *
+ * GENERATIONS: a new connection generation makes every wire-derived byte
+ * suspect, so `invalidate()` bumps a generation counter, drops the cache and
+ * clears the in-flight registry; a request answered after the bump is discarded
+ * on arrival ({@link MstarEngineStatusClient.write}) and the next render
+ * re-issues it. Without the fence an in-flight pre-reconnect answer would
+ * repopulate the cache and then suppress the repull the invalidation exists to
+ * force.
+ *
+ * DEADLINES: the gateway is a network hop, so one request is bounded
+ * ({@link MstarEngineStatusClientOptions.timeoutMs}) and a request that
+ * outlives its budget degrades to the explicit `unavailable('timeout:…')`
+ * reason instead of pinning `loading` for a whole turn. A served snapshot is
+ * likewise re-pulled on a modest interval
+ * ({@link MstarEngineStatusClientOptions.refreshIntervalMs}) — D3's "explicit
+ * refresh", never per agent-flow event. A refresh asks for the anchor it saw,
+ * so it never overwrites a newer anchor's answer ({@link
+ * MstarEngineStatusClient.write}).
+ *
+ * The store is written ONLY from a response continuation (never during a
+ * render), so reading it through `useSyncExternalStore` stays within React's
+ * snapshot contract.
+ *
+ * @module @mstar-harness/dsh/client/panel/engine-status-client
+ */
+import type { ConnectionRpcResult } from '@deepseek-ai/dsh-client-connection/client';
+import { ENGINE_STATUS_CHANNEL, ENGINE_STATUS_ENDPOINT } from '../../engine-status-wire.ts';
+import { type MstarEngineStatusFetch } from './guards.ts';
+export { ENGINE_STATUS_CHANNEL, ENGINE_STATUS_ENDPOINT };
+/** Deadline for one `/api/mstar/engineStatus` request (a hanging gateway must not pin `loading`). */
+export declare const ENGINE_STATUS_REQUEST_TIMEOUT_MS = 5000;
+/** How often a served snapshot is re-pulled (D3's "explicit refresh", modest interval). */
+export declare const ENGINE_STATUS_REFRESH_INTERVAL_MS = 30000;
+/**
+ * Structural face of the client `connection` service the panel needs — the
+ * generic RPC caller of the shared gateway. Declared structurally (not
+ * imported) so the bundle stays free of any runtime dependency on the
+ * transport package: the host injects `@deepseek-ai/dsh-client-connection`
+ * through the client manifest.
+ */
+export interface MstarEngineStatusConnection {
+    readonly rpc: {
+        call(channel: string, endpoint: string, payload: unknown, signal?: AbortSignal): Promise<ConnectionRpcResult<unknown>>;
+    };
+    /**
+     * Connection generations: a new generation means every wire-derived byte is
+     * suspect, so the cache is dropped and the panel repulls.
+     */
+    readonly generation?: {
+        subscribe(listener: () => void): () => void;
+    };
+}
+/** Optional timings (test seams; production uses the two constants above). */
+export interface MstarEngineStatusClientOptions {
+    /** Per-request deadline in ms (`0` disables the bound). */
+    readonly timeoutMs?: number;
+    /** Refresh interval in ms (`0` disables the interval). */
+    readonly refreshIntervalMs?: number;
+}
+/** One session's cached answer, tagged with the anchor row it answers. */
+export interface MstarEngineStatusEntry {
+    /** Message time of the anchor row this answer belongs to (staleness key). */
+    readonly anchorTime: number;
+    /** The workspace directory the answer was requested for (reused by a refresh). */
+    readonly cwd: string;
+    /** When the answer landed — the refresh clock (never the anchor row's time). */
+    readonly fetchedAt: number;
+    readonly fetch: MstarEngineStatusFetch;
+}
+/** The observable store value: at most one entry per session. */
+export interface MstarEngineStatusSnapshot {
+    readonly entries: ReadonlyMap<string, MstarEngineStatusEntry>;
+}
+/**
+ * The panel's engine-status client: one `/api/mstar/engineStatus` request per
+ * (session, anchor row), cached per session and observable by React.
+ */
+export declare class MstarEngineStatusClient {
+    private readonly connection;
+    private snapshot;
+    private readonly listeners;
+    private readonly inFlight;
+    private readonly abort;
+    /** Refreshes in flight, keyed by session (one per session, alongside the anchor requests). */
+    private readonly refreshing;
+    private readonly timeoutMs;
+    private readonly refreshIntervalMs;
+    private refreshTimer;
+    private generationDisposer;
+    /** Connection generation: bumped by {@link invalidate}; a mismatched answer is dropped. */
+    private generation;
+    private disposed;
+    /**
+     * @param connection - the client `connection` service, or undefined in a
+     *   composition without one (the panel then reports `unavailable`).
+     * @param options - request deadline / refresh interval (test seams).
+     */
+    constructor(connection: MstarEngineStatusConnection | null | undefined, options?: MstarEngineStatusClientOptions);
+    /** Current store value (stable reference until a response lands). */
+    getSnapshot: () => MstarEngineStatusSnapshot;
+    /** Subscribe to store writes (`useSyncExternalStore` face). */
+    subscribe: (listener: () => void) => (() => void);
+    /**
+     * Ensure the session's snapshot for ONE anchor row is being fetched. Safe to
+     * call on every render: an entry that already answers this anchor, and a
+     * request already in flight for it, are both no-ops.
+     * @param sessionId - the session the panel is showing.
+     * @param cwd - the session's workspace directory (the host cross-checks it
+     *   against the session and the stored snapshot; an unknown cwd is not
+     *   asserted, the panel degrades explicitly instead).
+     * @param anchorTime - message time of the anchor row this request answers.
+     */
+    ensure(sessionId: string, cwd: string, anchorTime: number): void;
+    /**
+     * Drop every cached answer (a new connection generation invalidates the wire
+     * data) and fence off the requests already on the wire: their answers belong
+     * to the previous generation and must never repopulate the cache, or the
+     * repull this invalidation exists to force would be suppressed by them.
+     */
+    invalidate(): void;
+    /** Stop accepting writes, abort in-flight requests and end the refresh interval (plugin teardown). */
+    dispose(): void;
+    /**
+     * Re-pull every served snapshot on a modest interval: the host keeps emitting
+     * on each digest-gated `agent/pre-step`, and a panel left open on an idle
+     * session would otherwise never see a newer snapshot. Deliberately NOT tied to
+     * agent-flow events, and never in flight twice for one session.
+     */
+    private startRefreshTimer;
+    /**
+     * One refresh pass over the cache: every entry older than the refresh
+     * interval is re-pulled for the SAME anchor (the anchor only moves when the
+     * host appends a newer row, which already triggers its own request). Public
+     * as the interval's deterministic test seam; the interval calls it.
+     */
+    refresh(): void;
+    /**
+     * One request → one validated entry. Never throws: a fault, a missing
+     * connection and an exceeded deadline are all explicit reasons.
+     * @returns the answer (also published through {@link write} when the
+     *   generation it was issued under is still current).
+     */
+    private fetch;
+    /**
+     * Bound one request: the request is aborted at the deadline and the caller
+     * gets the explicit timeout reason. A gateway that never answers must not pin
+     * `loading` (and with it the panel) for a whole turn.
+     */
+    private withDeadline;
+    /**
+     * Publish one answer (the only writer — always outside a render).
+     *
+     * An answer issued under a superseded connection generation is DROPPED: it
+     * describes the connection that is gone, and publishing it would both render
+     * pre-reconnect data as `ok` and suppress the repull `invalidate()` forces
+     * (the stale answer would satisfy `ensure`'s anchor check).
+     *
+     * An answer for a SUPERSEDED anchor is dropped for the same class of reason:
+     * a refresh issues its request for the anchor it saw, and a newer anchor row
+     * can be answered in the meantime, so publishing on arrival would overwrite a
+     * newer snapshot with an older one under a refreshed cache clock and no
+     * staleness marker. `ensure` already refuses an older anchor, which is why
+     * this only ever happens through {@link refresh}.
+     */
+    private write;
+    /** The store write itself (no generation test — see {@link write}). */
+    private writeEntry;
+    /** Notify subscribers, isolating a throwing listener. */
+    private notify;
+}

package/dist/client/panel/graph/project-graph.d.ts

@@ -74,7 +74,7 @@
  * with a transition past Phase 2 (an inconsistent harness state) degrades to the existing transition-driven current-step logic
  * (Step 2→4) — backward compatible, `active` semantics unchanged.
  */
-import type { MstarEngineStatusSource } from '../../../types.ts';
+import type { MstarEngineStatusPayload } from '../../../types.ts';
 import { type AgentZone, type PhaseId, type PlanStateId } from './schema.ts';
 /** Current-step verdict from `gate.ok` (spec §3). */
 export type PhaseVerdict = 'pass' | 'fail' | 'unknown';
@@ -441,7 +441,7 @@ export interface ZoneView {
         plans: boolean;
     };
 }
-export declare function projectGraph(source: MstarEngineStatusSource | null): ZoneView;
+export declare function projectGraph(source: MstarEngineStatusPayload | null): ZoneView;
 /**
  * `projectAgents(source, currentStep): AgentZoneView` — the agents zone (spec
  * §4 + §6.2). `currentStep` is the ITERATION's current step (1-based into
@@ -481,7 +481,7 @@ export declare function projectGraph(source: MstarEngineStatusSource | null): Zo
  * annotates the current plan; degraded/empty branches include the note too
  * (it is a state.plans annotation, independent of the ledger evidence).
  */
-export declare function projectAgents(source: MstarEngineStatusSource | null, currentStep: number | null): AgentZoneView;
+export declare function projectAgents(source: MstarEngineStatusPayload | null, currentStep: number | null): AgentZoneView;
 /** One row of the pairing walk — the identity a PAIRED settle carries (spec R1: exact identity pairing,
  * never owner+time guessing). The kind is the FULL projected kind union:
  * workflow/unknown rows are walk no-ops (they carry no paired marker) —
@@ -525,7 +525,7 @@ export declare function pairSettleIndexes(rows: readonly PairingRow[]): Readonly
  *   the server's empty view → present with 0 events → no events either (the
  *   `agents` skeleton carries `empty`).
  */
-export declare function projectFlowEvents(source: MstarEngineStatusSource | null): {
+export declare function projectFlowEvents(source: MstarEngineStatusPayload | null): {
     events: FlowEventView[];
     unexpected: FlowEventView[];
 };

package/dist/client/panel/guards.d.ts

@@ -1,12 +1,61 @@
 /**
- * Field-level degradation guards for the runtime `mstar-engine-status` source
+ * Field-level degradation guards for the runtime `mstar-engine-status` payload
  * (spec §2.4): the client does not exhaustively validate the union — it
- * narrows by `kind`, then degrades per field. Unknown/missing values render
- * as `unknown`, never as guessed values.
+ * narrows, then degrades per field. Unknown/missing values render as
+ * `unknown`, never as guessed values.
+ *
+ * This module ALSO carries the one place that validates untrusted input
+ * exhaustively: {@link parseEngineStatusResult}, which turns the
+ * `/api/mstar/engineStatus` wire envelope into the panel's explicit state. The
+ * payload is a remote answer the panel never authored, so a malformed
+ * envelope degrades to `unavailable` — never to a half-parsed view.
  */
+import type { MstarEngineStatusPayload } from '../../types.ts';
 /** String field: non-empty string, else null (missing → `unknown`). */
 export declare function str(value: unknown): string | null;
 /** Boolean field: real boolean, else null. */
 export declare function bool(value: unknown): boolean | null;
 /** Count field: finite number, else null. */
 export declare function count(value: unknown): number | null;
+/** Plain-object record (null and arrays are not records), else null. */
+export declare function record(value: unknown): Record<string, unknown> | null;
+/**
+ * The engine-status state the panel renders from: either the host's stored
+ * snapshot emission, or the explicit reason the snapshot is unavailable.
+ * There is deliberately no third "empty" shape — a degraded read is ALWAYS an
+ * `unavailable` carrying a reason, never a silently-empty payload.
+ */
+export type MstarEngineStatusFetch = {
+    readonly status: 'ok';
+    /** The exact catalog payload the host stored for this session. */
+    readonly payload: MstarEngineStatusPayload;
+    /** ISO timestamp of the served snapshot — the panel's freshness marker. */
+    readonly at: string;
+    /** The agent turn the row was emitted for. */
+    readonly turn: number;
+} | {
+    readonly status: 'unavailable';
+    readonly reason: string;
+};
+/**
+ * Validate one `/api/mstar/engineStatus` response into the panel's state.
+ *
+ * The whole envelope is untrusted: the transport result (`{ok, value}` /
+ * `{ok: false, error}`), the endpoint result (`status` + its fields) and the
+ * payload object. Every branch that cannot be read in full answers the
+ * explicit `unavailable` state with a machine-readable reason; the host's own
+ * `unavailable` reason is surfaced verbatim.
+ *
+ * @param raw - the value returned by `connection.rpc.call` (untrusted).
+ * @param sessionId - the session this client ASKED for; a response naming any
+ *   other session is refused (`session-mismatch`) — one session's request can
+ *   never render another session's data.
+ * @param cwd - the workspace this client ASSERTED in the same request; the host
+ *   echoes the record's `cwd`, so a response naming another workspace is refused
+ *   (`cwd-mismatch`) rather than rendered as this session's snapshot. The
+ *   comparison is exact byte equality: the host matched the asserted string
+ *   against its own record verbatim, so a normalising comparison here would
+ *   accept a workspace the host itself refused.
+ * @returns the validated snapshot state, or the explicit unavailable state.
+ */
+export declare function parseEngineStatusResult(raw: unknown, sessionId: string, cwd?: string): MstarEngineStatusFetch;

package/dist/client/panel/locale.d.ts

@@ -122,7 +122,7 @@ import type { LocaleDictOf } from '@deepseek-ai/dsh-client-ui-slots';
 /** Locale namespace id for the workflow-viz panel. */
 export declare const NS = "mstar-panel";
 /** Panel dictionary keys (union of every translatable string the panel renders). */
-export type PanelKey = 'view.mstar-workflow' | 'tab.tasks' | 'tab.agents' | 'tab.events' | 'page.iteration.not-started' | 'page.iteration.expand' | 'page.iteration.collapse' | 'event-log.section.events' | 'event-log.section.violations' | 'event-log.empty' | 'event-log.empty.events' | 'event-log.empty.violations' | 'event-log.field.role' | 'event-log.field.agent' | 'event-log.field.stage' | 'event-log.field.plan' | 'event-log.field.task' | 'event-log.field.category' | 'event-log.field.time' | 'event-log.field.kind' | 'event-log.field.status' | 'event-log.field.expected' | 'event-log.field.settled' | 'event-log.field.duration' | 'event-log.field.run-id' | 'event-log.field.name' | 'event-log.field.members' | 'event-log.field.stop-reason' | 'event-log.field.severity' | 'event-log.field.code' | 'event-log.field.message' | 'event-log.kind.dispatch' | 'event-log.kind.settle' | 'event-log.yes' | 'event-log.no' | 'empty.waiting' | 'empty.no-harness' | 'empty.no-harness-hint' | 'watermark.version' | 'watermark.harness' | 'watermark.none' | 'panel.unknown' | 'graph.pass' | 'graph.fail' | 'zone.legend.title' | 'zone.legend.agent-running' | 'zone.legend.agent-settled' | 'zone.legend.agent-idle' | 'zone.iteration.step-label' | 'zone.iteration.step-badge' | 'zone.iteration.step.current' | 'zone.iteration.step.next' | 'zone.iteration.step.done' | 'zone.iteration.step.idle' | 'zone.phase.iteration-start' | 'zone.phase.autonomous-execute' | 'zone.phase.iteration-close' | 'zone.phase.pr-delivery' | 'zone.phase.merge-ready' | 'zone.branches.title' | 'zone.branches.iteration-base' | 'zone.branches.target' | 'zone.branches.spec-integration' | 'zone.tasks.title' | 'zone.tasks.total' | 'zone.tasks.no-plans' | 'zone.tasks.more' | 'zone.tasks.collapse' | 'zone.project.title' | 'zone.project.milestones' | 'zone.project.residuals' | 'zone.project.none' | 'zone.state.Todo' | 'zone.state.InProgress' | 'zone.state.InReview' | 'zone.state.Done' | 'zone.state.blocked-unknown' | 'zone.agents.title' | 'zone.agents.summary' | 'zone.agents.on-demand' | 'zone.agents.unknown-sub' | 'zone.agents.bucket.implementor' | 'zone.agents.bucket.reviewer' | 'zone.agents.group.phase-1' | 'zone.agents.group.phase-2' | 'zone.agents.group.phase-n' | 'zone.agents.group.plan' | 'zone.agents.group.no-plan' | 'zone.agents.group.plan-more' | 'flow.empty' | 'flow.settle-only' | 'flow.degraded' | 'flow.unexpected' | 'flow.in-flight' | 'flow.settled-ok' | 'flow.error' | 'flow.advisory' | 'flow.denied' | 'state.title' | 'state.selection' | 'state.selection.history' | 'state.plans' | 'state.residuals' | 'state.policy' | 'state.leases' | 'state.knowledge' | 'state.direction' | 'state.none' | 'state.enforcement' | 'state.enforcement.hard' | 'state.enforcement.soft' | 'state.plans.more' | 'state.residual.more' | 'state.policy.push' | 'state.policy.worktree' | 'state.policy.control-worktree' | 'state.knowledge.docs' | 'freshness.last-updated' | 'freshness.refresh-note';
+export type PanelKey = 'view.mstar-workflow' | 'tab.tasks' | 'tab.agents' | 'tab.events' | 'page.iteration.not-started' | 'page.iteration.expand' | 'page.iteration.collapse' | 'event-log.section.events' | 'event-log.section.violations' | 'event-log.empty' | 'event-log.empty.events' | 'event-log.empty.violations' | 'event-log.field.role' | 'event-log.field.agent' | 'event-log.field.stage' | 'event-log.field.plan' | 'event-log.field.task' | 'event-log.field.category' | 'event-log.field.time' | 'event-log.field.kind' | 'event-log.field.status' | 'event-log.field.expected' | 'event-log.field.settled' | 'event-log.field.duration' | 'event-log.field.run-id' | 'event-log.field.name' | 'event-log.field.members' | 'event-log.field.stop-reason' | 'event-log.field.severity' | 'event-log.field.code' | 'event-log.field.message' | 'event-log.kind.dispatch' | 'event-log.kind.settle' | 'event-log.yes' | 'event-log.no' | 'empty.waiting' | 'empty.loading' | 'empty.unavailable' | 'empty.no-harness' | 'empty.no-harness-hint' | 'watermark.version' | 'watermark.harness' | 'watermark.none' | 'panel.unknown' | 'graph.pass' | 'graph.fail' | 'zone.legend.title' | 'zone.legend.agent-running' | 'zone.legend.agent-settled' | 'zone.legend.agent-idle' | 'zone.iteration.step-label' | 'zone.iteration.step-badge' | 'zone.iteration.step.current' | 'zone.iteration.step.next' | 'zone.iteration.step.done' | 'zone.iteration.step.idle' | 'zone.phase.iteration-start' | 'zone.phase.autonomous-execute' | 'zone.phase.iteration-close' | 'zone.phase.pr-delivery' | 'zone.phase.merge-ready' | 'zone.branches.title' | 'zone.branches.iteration-base' | 'zone.branches.target' | 'zone.branches.spec-integration' | 'zone.tasks.title' | 'zone.tasks.total' | 'zone.tasks.no-plans' | 'zone.tasks.more' | 'zone.tasks.collapse' | 'zone.project.title' | 'zone.project.milestones' | 'zone.project.residuals' | 'zone.project.none' | 'zone.state.Todo' | 'zone.state.InProgress' | 'zone.state.InReview' | 'zone.state.Done' | 'zone.state.blocked-unknown' | 'zone.agents.title' | 'zone.agents.summary' | 'zone.agents.on-demand' | 'zone.agents.unknown-sub' | 'zone.agents.bucket.implementor' | 'zone.agents.bucket.reviewer' | 'zone.agents.group.phase-1' | 'zone.agents.group.phase-2' | 'zone.agents.group.phase-n' | 'zone.agents.group.plan' | 'zone.agents.group.no-plan' | 'zone.agents.group.plan-more' | 'flow.empty' | 'flow.settle-only' | 'flow.degraded' | 'flow.unexpected' | 'flow.in-flight' | 'flow.settled-ok' | 'flow.error' | 'flow.advisory' | 'flow.denied' | 'state.title' | 'state.selection' | 'state.selection.history' | 'state.plans' | 'state.residuals' | 'state.policy' | 'state.leases' | 'state.knowledge' | 'state.direction' | 'state.none' | 'state.enforcement' | 'state.enforcement.hard' | 'state.enforcement.soft' | 'state.plans.more' | 'state.residual.more' | 'state.policy.push' | 'state.policy.worktree' | 'state.policy.control-worktree' | 'state.knowledge.docs' | 'freshness.last-updated' | 'freshness.refresh-note';
 declare module '@deepseek-ai/dsh-client-ui-slots' {
     interface LocaleNamespaceMap {
         'mstar-panel': PanelKey;

package/dist/client/panel/panel-meta.d.ts

@@ -10,9 +10,9 @@
  */
 import * as React from 'react';
 import type { TranslateNS } from '@deepseek-ai/dsh-client-ui-slots';
-import type { MstarEngineStatusSource } from '../../types.ts';
+import type { MstarEngineStatusPayload } from '../../types.ts';
 export interface PanelMetaProps {
     t: TranslateNS<'mstar-panel'>;
-    source: MstarEngineStatusSource;
+    source: MstarEngineStatusPayload;
 }
 export declare function PanelMeta({ t, source }: PanelMetaProps): React.JSX.Element;

package/dist/client/panel/sidebar.d.ts

@@ -8,10 +8,10 @@
  */
 import * as React from 'react';
 import type { TranslateNS } from '@deepseek-ai/dsh-client-ui-slots';
-import type { MstarEngineStatusSource, MstarHarnessState } from '../../types.ts';
+import type { MstarEngineStatusPayload, MstarHarnessState } from '../../types.ts';
 export interface SidebarProps {
     t: TranslateNS<'mstar-panel'>;
     state: MstarHarnessState | null;
-    source: MstarEngineStatusSource;
+    source: MstarEngineStatusPayload;
 }
 export declare function Sidebar({ t, state, source }: SidebarProps): React.JSX.Element;

package/dist/client/panel/state-section.d.ts

@@ -13,11 +13,11 @@
  */
 import * as React from 'react';
 import type { TranslateNS } from '@deepseek-ai/dsh-client-ui-slots';
-import type { MstarEngineStatusSource, MstarHarnessState } from '../../types.ts';
+import type { MstarEngineStatusPayload, MstarHarnessState } from '../../types.ts';
 export interface StateSectionProps {
     t: TranslateNS<'mstar-panel'>;
     state: MstarHarnessState;
     /** Top-level enforcement flag (spec §2.1) — NOT part of the state digest. */
-    enforcement: MstarEngineStatusSource['enforcement'];
+    enforcement: MstarEngineStatusPayload['enforcement'];
 }
 export declare function StateSection({ t, state, enforcement }: StateSectionProps): React.JSX.Element;