@mstar-harness/dsh 3.7.3 → 3.8.1

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

@@ -1,64 +1,90 @@
 /**
- * Morning Star workflow panel page — the `conversation.view` tab component
- * (spec §4.2): pure render of the latest `mstar-engine-status` catalog row.
+ * Morning Star workflow panel page — the right-Sidebar pane body (the keyed
+ * `sidebar.right.pane.tab` seat component, plan sidebar §L1.5): 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 sidebar seat's props (`MstarPanelBodyProps` — the seat's
+ * runtime share incl. the framework-injected `useTabInfo()` + the session
+ * standard kit + the entry store share (`useStore` + baked `select`, backed
+ * by the registration's `store` option) + the plugin's engine-status client
+ * bound by the plugin entry + 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
- * never scrolls); the right sidebar is RESIDENT (all tabs share it, its props
- * `{ t, state, source }` unchanged); main = the fixed header nav (TabNav, 3
- * MenuTabs) + the content region (switches per tab) + the freshness footer.
- * The `data-mstar-graph` anchor now marks the CONTENT container (spec §6.1 —
- * previously the canvas container), so tests pin the layout contract, not the
- * per-tab page internals.
+ * Visibility (plan sidebar §L2.6): a docked body is projected only while its
+ * sidebar column is expanded and the tab is active —
+ * `useTabInfo().tab.visible` — so a collapsed column renders NOTHING (no
+ * projection, no DOM). A floating pane is always visible.
  *
- * Tab state (spec §6.2): local `useState<PanelTab>` (default 'tasks', D1, no
- * routing) — `renderToStaticMarkup` renders the default tasks page, keeping
- * SSR assertions stable. The tasks tab renders the IterationTaskPage (Content
- * Head + Steps 横排/收拢 + full-width kanban, spec §3 —
- * replacing the WorkflowCanvas zone dashboard); the agents tab renders the
- * draggable AgentCanvasPage (spec §4 — replacing the muted placeholder + the AgentFlowZone); the events tab
- * renders the EventLogPage (spec §5 — the non-canvas log page with per-row
- * `<details>` expansion, replacing
- * the muted placeholder AND the AgentEventDock — 无双份日志).
+ * Layout (plan sidebar §L2.1): the narrow-column shell is a single flex
+ * column with exactly three zones — the section nav (`flex: none`), the
+ * panel-owned scroll body (`[data-mstar-scroll]`, flex: 1 1 auto ·
+ * min-height: 0 · the ONLY `overflow-y: auto` element in the panel; it also
+ * carries the `data-mstar-graph` content-container anchor), and the pinned
+ * meta dock (`flex: none`). The workspace-state digest renders IN FLOW at the
+ * end of the scroll body (the old 300px sibling column and its nested
+ * scroller are gone); the freshness footer follows it in the same flow.
  *
- * 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.
+ * Section state (plan sidebar §L2.4): the entry store, keyed by
+ * `tabInfo.tab.id` (default `'tasks'`, D1) — it survives the body's unmount
+ * when another pane tab activates, which `useState` cannot. The render is
+ * SSR-stable: an untouched store reads `undefined` → the default tasks page.
+ *
+ * Empty branches (spec §2): waiting / loading / unavailable / no-harness
+ * render no tabs, no digest and no meta dock — each with its OWN anchor and
+ * copy, so a degraded read is never mistakable for an empty workspace.
+ * 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 PanelTab } from './TabNav.tsx';
-export interface MstarPanelViewProps extends ConvViewProps {
+import type { PropsLocale, PropsRuntime, TranslateNS } from '@deepseek-ai/dsh-client-ui-slots';
+import type { SessionId } from '@deepseek-ai/dsh-session';
+import type { MstarEngineStatusPayload } from '../../types.ts';
+import type { PropsStore } from '@deepseek-ai/dsh-client-store';
+import type { MstarEngineStatusClient } from './engine-status-client.ts';
+import { type UseSessions } from './use-mstar-engine-status.ts';
+import { createPanelStore, type PanelSection } from './panel-store.ts';
+/**
+ * The sidebar body seat's props (plan sidebar §L1.5): the seat's runtime
+ * share (owner + keyed + the seat's inject face — `useTabInfo()` — + the
+ * session standard kit, incl. the ui-chat-merged `useChat`) + the entry
+ * store share (plan §L2.4 — the registration's `store` option) + the typed
+ * `t` seat from the registration's `locale:` option.
+ */
+export interface MstarPanelBodyProps extends PropsRuntime<'sidebar.right.pane.tab'>, PropsStore<ReturnType<typeof createPanelStore>>, PropsLocale<'mstar-panel'> {
     /** 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
+     * `SessionStandardProps`; the seat's session scope 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;
+    /** The active panel section (plan sidebar §L1.5 vocabulary — not a sidebar tab record). */
+    section: PanelSection;
+    source: MstarEngineStatusPayload;
     t: TranslateNS<'mstar-panel'>;
 }
 /**
- * Tab → page mapping (spec §6.2): the only per-tab-switching part of the
- * layout. tasks = the IterationTaskPage (spec §3 — Content Head + Steps
- * 横排/收拢 + full-width kanban, it replaced the
- * WorkflowCanvas zone dashboard, whose file is removed by the plan close);
- * agents = the draggable AgentCanvasPage (spec §4 — full KNOWN_AGENTS roster
- * + idle states + AgentEdge collaboration edges; it replaced the muted placeholder and the AgentFlowZone); events =
- * the real EventLogPage (spec §5 — non-canvas log page: Agent 流转事件 +
- * 违规记录 partitions with per-row `<details>` expansion; it replaced the muted placeholder AND the
- * AgentEventDock — 无双份日志, the dock is removed with this plan).
+ * Section → page mapping (spec §6.2): the only per-section-switching part of
+ * the layout. tasks = the IterationTaskPage (spec §3 — Content Head + Steps
+ * + the plan board); agents = the AgentListPage (spec §4 — the vertical
+ * grouped list, plan sidebar §L3); events = the EventLogPage (spec §5 — the
+ * log page with per-row `<details>` expansion).
  */
-export declare function PanelContent({ tab, source, t }: PanelContentProps): React.JSX.Element;
-export declare function PanelView({ t, useChat }: MstarPanelViewProps): React.JSX.Element;
+export declare function PanelContent({ section, source, t }: PanelContentProps): React.JSX.Element;
+export declare function PanelView({ t, useChat, useSessions, sessionId, engineStatus, useTabInfo, useStore, actions }: MstarPanelBodyProps): React.JSX.Element | null;

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

@@ -1,28 +1,31 @@
 /**
  * TabNav (spec panel-tabs §2/§6.1) —
- * the fixed header nav: 3 MenuTabs (任务迭代 / 代理执行 / 事件记录, F1.2)
- * switching the main content. Tab state is owned by PanelView
- * (`useState<PanelTab>`, default 'tasks', no routing — SSR-stable under
- * `renderToStaticMarkup`); TabNav is a controlled component receiving
- * `active` + `onChange` (spec §6.1 interface contract).
+ * the section nav, the shell's first flex zone (`flex: none`): the three
+ * internal sections (任务迭代 / 代理执行 / 事件记录) of the one sidebar tab.
+ * Section state is owned by the panel entry store (plan sidebar §L2.4 —
+ * keyed by the sidebar tab record, default 'tasks', no routing); TabNav is a
+ * controlled component receiving `active` + `onChange` (spec §6.1 interface
+ * contract).
  *
  * Anchors: `data-mstar-tab-nav` (the nav frame), `data-mstar-tab="{id}"` on
  * every tab and `data-mstar-tab-active="true|false"` (activation state). The
  * active tab gets the business-token underline; inactive tabs stay secondary.
+ * Visual language (plan sidebar §L2.3): the strip ABOVE this nav is the dsh
+ * tab chrome (chips with borders — the host's, untouched); this nav is
+ * content — `role="tablist"`, `role="tab"` + `aria-selected`, the underline
+ * via `box-shadow`, no borders on the tabs.
  *
- * A11y: the nav is a WAI-ARIA tablist and each tab is a
- * `role="tab"` button with `aria-selected` (APG Tabs pattern, replacing the
- * former `aria-pressed` toggle). Deliberately minimal: every tab stays Tab-
- * reachable (no roving tabindex / arrow-key handling — that behavior would
- * be scope creep without an explicit keyboard contract).
+ * A11y: WAI-ARIA tablist, each tab a `role="tab"` button with
+ * `aria-selected` (APG Tabs pattern). Deliberately minimal: every tab stays
+ * Tab-reachable (no roving tabindex / arrow-key handling — that behavior
+ * would be scope creep without an explicit keyboard contract).
  */
 import * as React from 'react';
 import type { TranslateNS } from '@deepseek-ai/dsh-client-ui-slots';
-/** The three fixed panel tabs (spec §2 — D1 default = 'tasks'). */
-export type PanelTab = 'tasks' | 'agents' | 'events';
+import type { PanelSection } from './panel-store.ts';
 export interface TabNavProps {
-    active: PanelTab;
-    onChange: (tab: PanelTab) => void;
+    active: PanelSection;
+    onChange: (tab: PanelSection) => void;
     t: TranslateNS<'mstar-panel'>;
 }
 export declare function TabNav({ active, onChange, t }: TabNavProps): React.JSX.Element;

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

@@ -0,0 +1,23 @@
+/**
+ * The panel's right-Sidebar tab-type definition (plan sidebar §L1.2) — stage
+ * one of the two-stage seat registration: what the panel IS in the tab
+ * system. Stage two (the keyed `sidebar.right.pane.tab` body and
+ * `sidebar.right.pane.tab.title` chip under the same `id`) lives in the
+ * plugin entry (`src/client/index.ts`).
+ *
+ * A page type: `patterns`/`canOpen` omitted (it recognizes no resource
+ * address — it is opened by `kind`), `priority` omitted (defaults to the
+ * `extension` band, the right band for a type from outside the product), and
+ * exactly one guide entry so the start page carries the MStar capsule. The
+ * `title` thunk is re-read on every use, so the guide capsule follows the
+ * current locale; the chip's copy is captured at open time by the host.
+ */
+import type { SidebarRightTabDefinition } from '@deepseek-ai/dsh-client-ui-sidebar-right/client';
+import type { TranslateNS } from '@deepseek-ai/dsh-client-ui-slots';
+/** This implementation's identity in the tab system — the key its body and title register under. */
+export declare const MSTAR_PANEL_ID = "@mstar-harness/dsh";
+/** The page kind the panel owns (U2: one sidebar tab). */
+export declare const MSTAR_PANEL_KIND = "mstar-workflow";
+/** The guide capsule's position among every registered type's entries (files ships order 10). */
+export declare const MSTAR_GUIDE_ORDER = 20;
+export declare function mstarPanelDefinition(t: TranslateNS<'mstar-panel'>): SidebarRightTabDefinition;

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

@@ -35,8 +35,7 @@
  *   (the stage skeleton + entities/edges now live in the `agents` projection —
  *   spec §4);
  * - added: `iteration.steps / currentStep / branches`, `tasks.columns / total
- *   / truncated`, `agents` (entities + actual/supervise edges + executing/
- *   pending counts — spec §4).
+ *   / truncated`, `agents` (entities + executing/pending counts — spec §4).
  *
  * Agent-entity semantics (the per-role aggregation): entities aggregate by ROLE, not by session
  * — a KNOWN_AGENTS roster role keys its own card (same role across sessions
@@ -48,8 +47,8 @@
  * RENDER places `zone: 'general'` entities in an unknown sub-partition at
  * the bottom of the LAST column (the standalone rightmost unknown column
  * is superseded: 4 columns total). The SDD loop back-edge (sdd-implement →
- * general) stays REMOVED from the projection; the supervise line is a SEPARATE sub-bucket edge
- * (`kind: 'supervise'`, see `superviseEdges`). The event-log `unexpected`
+ * general) and the sub-bucket supervise line are both REMOVED from the
+ * projection — the agents zone projects entities only. The event-log `unexpected`
  * badge is a SEPARATE, unchanged semantic (`expected` ⟺ role ∈
  * EXPECTED_ROLE_FLOW union). The `sdd-implement` column is further split
  * into implementor / reviewer SUB-BUCKETS: every entity carries a projected `bucket` field ('implementor' /
@@ -74,7 +73,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';
@@ -215,7 +214,7 @@ export interface AgentEntityView {
      * non-roster dispatch); the KNOWN_AGENTS role id for idle cards. INVARIANT
      * (spec §6.2): keys are UNIQUE across the whole `entities` array —
      * an evidence-derived `general` key suppresses the idle general twin in
-     * `idleEntities`, so the React `key` / `layoutAgents` `cards.set` never see
+     * `idleEntities`, so the render layer's entity `key` space never sees
      * duplicates.
      */
     key: string;
@@ -291,44 +290,6 @@ export type AgentEmphasis = 'current' | 'next' | 'off' | null;
 export type AgentEntityStatus = 'running' | 'settled' | 'error' | 'denied'
 /** Retained for shape compat; the derivation (entityStatus) no longer emits it. */
  | 'advisory' | 'idle';
-/** Edge kinds (spec §4 — the finalized line semantics, design doc §2.2): handoff / sub-bucket
- * supervision arrows. `expected` (stage skeleton) and `next` (running
- * animation) are REMOVED — the column order implies the flow, the running
- * card glow/status point carries the position. */
-export type AgentEdgeKind = 'actual' | 'supervise';
-/**
- * One agents-zone arrow (spec §4):
- * - `actual`: same-plan handoff between ts-adjacent dispatch ENTITY keys
- *   (source/target = entity key — role-based). The line set filters
- *   general-bucket endpoints
- *   (a general handoff is noise, not a meaningful transfer) and keeps at most
- *   ONE edge per entity-key pair (the latest direction) — design doc §2.2;
- * - `supervise`: ONE static sub-bucket line inside the `sdd-implement`
- *   column — implementor ↔ reviewer mutual supervision (the mstar-sdd
- *   mutual-supervision contract; the render draws it as a bidirectional
- *   double arrow).
- *   source/target embed the column id as an anchor prefix:
- *   `<stage-id>:implementor` / `<stage-id>:reviewer`. NOT per-entity pairs —
- *   drawing per-role pairs would fabricate concrete supervision relations
- *   where no evidence exists (evidence-level handoffs are covered by
- *   `actualEdges`). STATIC presence (design knowledge) + evidence-driven
- *   lighting via `evidenced` (dim without implement/review dispatch
- *   evidence, lit with it — never a fabricated activation).
- */
-export interface AgentEdge {
-    kind: AgentEdgeKind;
-    /** actual: entity key; supervise: `<stage-id>:implementor|reviewer`. */
-    source: string;
-    target: string;
-    /** Unused by the line edge set (the removed `next` arrow carried the
-     * running entity key); kept for shape stability — always null. */
-    entityKey: string | null;
-    /** Supervise edges only:
-     * evidence-driven lighting — true when any dispatch row's role belongs to
-     * an SDD sub-bucket (implementor ∪ reviewer), false otherwise (dim).
-     * Absent (undefined) for actual. */
-    evidenced?: boolean;
-}
 /**
  * The canvas degradation-note classification (spec §8): the projection
  * decides the note from the RAW ledger (never a UI-side heuristic on the
@@ -341,8 +302,8 @@ export interface AgentEdge {
 export type AgentZoneNote = 'empty' | 'settle-only' | null;
 /**
  * The projected agents zone (spec §4 + §6.2): the EXPECTED_ROLE_FLOW stage
- * skeleton plus the dispatch-derived entity cards and the actual/supervise
- * arrows. Total function — NEVER throws and NEVER fabricates: the KNOWN_AGENTS
+ * skeleton plus the dispatch-derived entity cards. Total function — NEVER
+ * throws and NEVER fabricates: the KNOWN_AGENTS
  * roster always projects as entities (idle cards when there is no evidence) —
  * agentFlow missing/unreadable → `degraded` (full idle roster + no
  * executing/pending claims); 0 events → `empty` (full idle roster + pending
@@ -360,8 +321,6 @@ export interface AgentZoneView {
     note: AgentZoneNote;
     /** Evidence-derived dispatch entities ∪ idle KNOWN_AGENTS cards — the full roster is NEVER hidden (spec §6.2). */
     entities: readonly AgentEntityView[];
-    /** expected (stage skeleton) + actual (same-plan handoffs) + at most one next (latest running). */
-    edges: readonly AgentEdge[];
     /** `running` entity count — the summary "N 执行中" (idle cards never count). */
     executing: number;
     /** Sum of expected roles of stages with no dispatch evidence — the summary "M 待执行". */
@@ -441,7 +400,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
@@ -458,8 +417,7 @@ export declare function projectGraph(source: MstarEngineStatusSource | null): Zo
  *   role is pending);
  * - otherwise: entities aggregated from dispatch rows (with `idle: false`),
  *   statuses via the shared pairing walk, the un-evidenced KNOWN_AGENTS
- *   members appended as idle cards, actual/supervise edges (design doc §2.2 —
- *   the `expected` skeleton and `next` animation edges are REMOVED), and the
+ *   members appended as idle cards, and the
  *   executing (running entities — idle never counts) / pending
  *   (un-evidenced stage roles) counts.
  *
@@ -468,8 +426,8 @@ export declare function projectGraph(source: MstarEngineStatusSource | null): Zo
  * suppresses a known role's idle card when its id already exists as an
  * evidence-derived entity key (a NON-roster dispatch produces a lit `general`
  * key while the roster `general` id stays un-evidenced — the twin is
- * suppressed via `litKeys`), so the render layer's `key`/`cards.set` never
- * collide.
+ * suppressed via `litKeys`), so the render layer's entity `key` space never
+ * collides.
  *
  * Canvas note: `note` classifies the readable ledger in
  * the projection ('empty' / 'settle-only' / null — see `AgentZoneNote`); the
@@ -481,7 +439,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 +483,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/graph/schema.d.ts

@@ -82,8 +82,7 @@ export declare const TRANSITION_TO_PHASE: Readonly<Record<string, PhaseId>>;
  * placement (BOTTOM INSIDE the `sdd-implement` column bucket) is
  * superseded by the F5; the former SDD implement ↔ review
  * skeleton EDGE (sdd-implement → general back-edge, the `loop: true` arrow)
- * stays REMOVED from the projection ; the F5 supervise line is a SEPARATE sub-bucket edge (see
- * project-graph.ts `superviseEdges`).
+ * and the F5 sub-bucket supervise line are both REMOVED from the projection.
  *
  * Matching rules (spec §2.3 — implemented by `projectGraph`'s flow
  * projection): `expected` ⟺ `event.role` ∈ the union of ALL `roles` below

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;