@mstar-harness/dsh 3.8.0 → 3.8.2

package/harness-skills/mstar-host/references/dsh.md

@@ -34,226 +34,94 @@ or a custom profile).
 - Web client plugin (workflow panel): the same `mstar` bundle row carries a
   browser client half (`dsh.client` + `exports["./client"]`) discovered
   automatically by `ClientModuleHostService` — no separate profile layer or
-  install step. It registers a **`conversation.view`** view-ring tab
-  (`id: 'mstar-workflow'`, `order: 20`) labeled **"MStar 工作流" / "MStar
-  Workflow"** rendering the latest `mstar-engine-status` catalog **anchor** row
+  install step. It registers a **right-Sidebar page tab type** (`id:
+  '@mstar-harness/dsh'`, `kind: 'mstar-workflow'`, one guide-page capsule at
+  `order: 20`) labeled **"启明星工作流" / "Morning
+  Star Workflow"** rendering the latest `mstar-engine` catalog **anchor** row
   — the persisted source is the bare first-party `plugin` arm
-  (`{ kind: 'plugin', plugin: 'mstar-engine-status', form: 'catalog' }`, no
-  payload members), and the payload is fetched from the host's
+  (`{ kind: 'plugin', plugin: 'mstar-engine', form: 'catalog' }`, no
+  payload members; the anchor reader also accepts the legacy
+  `mstar-engine-status` identity from persisted logs), and the payload is fetched from the host's
   `/api/mstar/engineStatus` endpoint (the gateway owns the route; the 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 in time-desc order +
-  `+N more`, open residual findings ≤10 with severity chips + overflow hint,
-  policy with **enforcement first** then push / worktree / control worktree,
-  leases, knowledge, direction) over a bottom **fixed meta dock** (version +
-  harness dir; small muted, hairline-separated, does NOT scroll with the
-  sidebar digest — the former header row was removed), and an **HTML/CSS zone
-  dashboard** (the react-flow cyclic graph was removed in plan
-  `20260810-panel-canvas-zones`): the canvas fills the Tab (the page never
-  scrolls; the zone container is the only scroll body) with an **iteration
-  zone** (Step 1–5 stepper + `Step N/5` badge + active-highlight / inactive
-  dimmed state; the steps carry a FOUR-STATE machine — `current` / `next` /
-  `done` / `idle` (plan `20260812-panel-f5-iteration-zone-fix` Task 1): every
-  step BEFORE the current one projects `done`「已完成」(completed — a finished
-  Step 1 must not read as idle while Step 2 is current), `next` is the single
-  forward target, `idle` is schema-only + the branch panel — iteration base /
-  target / spec integration, rendered only while active; the expanded head is
-  a LEFT-RIGHT SPLIT — branches (small left half, WIDTH-CAPPED — `flex: 0 1
-  260px` + `max-width: 280px`, never stretches with the container; the <860px
-  column stack resets to content height) + steps (large right half, `flex: 1 1
-  0` absorbing the remaining width) via `data-iteration-head-split`, stacking
-  on narrow widths, and NO branch panel
-  when there is no active iteration; the current step follows the steering
-  compass: `compassStatus: 'active'` (Phase 1 in flight) → Step 1
-  (iteration-start) is CURRENT with verdict `unknown` — no PASS/FAIL badge,
-  plan `20260811-panel-f4-iteration-zone`; **the iteration info section is
-  SHARED by the tasks AND agents tabs** (plan
-  `20260812-panel-f5-design-system` Task 8, user round-4 decision #4 — one
-  `IterationInfoSection` component, both tabs render the same `view.iteration`
-  block: summary + steps + branches), a **tasks zone** (5-column
-  kanban: Todo / InProgress / InReview / Done / `blocked-unknown` — the
-  Blocked state and the former `unknown` catch-all fold into ONE merged
-  column titled「受阻/未知」/「Blocked / Unknown」, plan
-  `20260813-panel-quick-fixes` Task 1 — with count badges; every column
-  caps its rendered rows at `PLAN_CAP` and shows a clickable 「更多」/「收起」
-  expand button (`data-kanban-more` anchor) unfolding the full column — the
-  projection keeps ALL plan rows, the cap is a render concern never a
-  discard), an **agent-execution zone** (the FOUR EXPECTED_ROLE_FLOW stage/phase
-  columns — review-edit-chain → sdd-implement → qc-tri → qa-gate, the
-  terminal stage; the former `sdd-task-review` stage is removed and its SDD
-  L2 reviewer is now the PIPELINE role `code-reviewer` (v2.1.1, the former
-  `generalPurpose` seat) — a strict FOUR-column layout with NO standalone
-  unknown column (plan `20260812-panel-f5-design-system` Task 5, user
-  2026-08-12 round-2 decision — the former rightmost UNKNOWN column of plan
-  `20260812-panel-f5-agent-layout` is superseded): the `general` bucket
-  sinks into an **unknown SUB-PARTITION at the bottom of the `qa-gate`
-  column** (a `data-sub-bucket="unknown"` caption row 「unknown / 未匹配角色」
-  after the last qa-gate card, then the general cards; the standalone
-  on-demand column was already removed in the agent-layout plan); `explore`
-  is removed — no card, no column. The columns are laid out in **TWO
-  side-by-side Phase groups** (plan `20260812-panel-f5-design-system` Task 8,
-  user round-4 decision #2; side-by-side layout per plan
-  `20260813-panel-agent-canvas-legend-layout` Task 2): the **Phase 1 group
-  on the LEFT** (review-edit-chain — the sequential Review & Edit chain:
-  product-manager → architect → writing-specialist) and the **Phase 2 group
-  on the RIGHT** (sdd-implement → qc-tri → qa-gate — the iterative plan
-  loop), top-aligned (all group label rows share the same `y = PAD_Y`), each
-  with its group label row; the **Phase-2 label annotates the CURRENT PLAN**
-  (projected `agents.activePlanId` = the first InProgress `state.plans[]`
-  row, `data-canvas-group-plan`; `+N more` when several plans run in
-  parallel, muted「无进行中 plan」when none). The `sdd-implement` column is split into SUB-BUCKETS by
-  the PROJECTED `entity.bucket` (never a render guess): the **implementor**
-  partition ABOVE — the flow roles in the stage's original order
-  (fullstack-dev / fullstack-dev-2 / frontend-dev), then the on-demand
-  roles (ops-engineer / prompt-engineer, carrying the **on-demand badge** —
-  the standalone on-demand column is gone) — and the **sdd-reviewer**
-  partition BELOW (code-reviewer, idle included), with the implementor /
-  sdd-reviewer caption labels; `zone: 'on-demand'` entities live in the
-  implementor partition, `zone: 'general'` entities render in the qa-gate
-  column's bottom unknown sub-partition. The subagent ENTITY cards aggregate **by role** from actual
-  dispatch evidence: the same role across sessions folds into one card ×N,
-  and every off-roster dispatch (the former `generalPurpose` SDD reviewer,
-  `scout`, anonymous `role === ''`) folds into the single `general` bucket
-  entity — the card is ROLE-TITLED (the role id, e.g. `fullstack-dev`); the
-  agent session id / task tag (`planId#taskId`) ride the RECORD line, never
-  the title. Cards show the role chip / status point / ×N count; running
-  entities carry the business glow-pulse
-  highlight, un-evidenced stages render the dashed "待执行" pending
-  placeholder with their expected role chips, un-evidenced KNOWN_AGENTS
-  members render dashed idle cards (the full 14-role roster is never
-  hidden), and the header shows the `N executing · M pending` summary.
-  Cards carry the projected **emphasis tier** (plan
-  `20260812-panel-f5-design-system` Task 4, design doc §3): `emphasis:
-  'current' | 'next' | 'off' | null` — the iteration's current-phase roles
-  render at **100%** chrome intensity, later-phase expected roles at **75%**,
-  already-passed / stage-less (on-demand, general) roles at **45%**, and
-  `null` (no iteration / unresolved transition) applies NO override — always
-  a chrome **alpha mix** (`--mstar-canvas-emphasis-*` tokens; never a
-  whole-card `opacity`, so the status point + running glow stay opaque).
-  Settled entities get a **standalone GREEN done frame + green ✓** (plan
-  `20260812-panel-f5-design-system` Task 8, user round-4 decisions #1/#3:
-  `data-agent-done="true"` — a full-strength success border + 1px ring on
-  the rounded card body + the ✓ in the status point) **ONLY when
-  `emphasis ≠ 'off'`** — an off-tier role (already-passed / stage-less
-  on-demand + general) renders the muted dot instead and NEVER shows the
-  completion marker (the completed state never appears on a stage-less
-  role). The canvas filters to the CURRENT iteration only (plan
-  `20260813-panel-quick-fixes` Task 2): dispatch evidence projects for the
-  current iteration's plans — the steering compass `iterationId` when
-  active, else the nearest iteration derived from the catalog
-  `plans[].iterationRefs` (the most-recent plan's refs by 8-digit id date
-  prefix + doneAt); provably cross-iteration events produce no entity/edge
-  (the roster keeps its idle cards); plan-less / unknown-plan / standalone
-  dispatches are never hidden. Status honesty (Task 2): `advisory` is NO
-  LONGER terminal — a soft-enforcement dispatch falls through to its paired
-  settle (green ✓ when a settle exists, `running` when none) while `denied`
-  stays terminal; the advisory verdict still renders in the event log. The
-  canvas legend sits BELOW the viewport (Task 3 — moved from above, user
-  2026-08-13 feedback).
-  Edges (plan `20260812-panel-f5-design-system` Task 5, design doc §2):
-  the `expected` stage skeleton arrows AND the ANIMATED **next** edge (the
-  former `@keyframes agent-dash-flow` dash-flow arrow of plan
-  `20260810-panel-agent-flow-zone`) are **REMOVED** — flow order is implied
-  by the fixed column order + column labels, the current position by the
-  running card glow + status point — leaving TWO semantic kinds: the
-  evidence-driven **`actual` handoff** edges (same-plan ts-adjacent dispatch
-  entity-key pairs, `general` endpoints filtered, ≤1 per entity pair) drawn
-  as **bezier `C` curves** anchored to card **PORTS** — 4 fixed
-  edge-midpoint ports (north / south / east / west; static-invisible,
-  hover-revealed as small dots) with the arrow tip pulled back to a **10px
-  standoff** off the port — the arrow follows the line's local tangent at
-  the anchor (**H1**), and no line's stroke or arrow crosses any text
-  (**H2**: standoff + side-gap routing, design doc §2.0/§2.5/§2.6;
-  tightened in plan `20260813-panel-quick-fixes` Task 3 — same-column
-  vertical flows whose center-x line would cross an in-between card body
-  (e.g. fullstack-dev → frontend-dev skipping an idle fullstack-dev-2)
-  reroute into the column's LEFT side gap, forward AND reverse, and reverse
-  horizontal beziers keep direction-aware control points BETWEEN the
-  endpoints so they never bulge into the adjacent column) — plus
-  the **bidirectional supervise line** (plan `20260812-panel-f5-agent-layout`
-  Task 1/2) — ONE static design-knowledge sub-bucket edge inside the
-  `sdd-implement` column (implementor ↔ sdd-reviewer — the mstar-sdd
-  mutual-supervision contract), now anchored at the **side-gap vertical
-  anchor** (`x = card right edge + 18px`, vertical bezier flow, arrows along
-  the vertical tangent — design doc §2.5/§2.7); dim dashed by default, lit
-  business SOLID when the projected `evidenced` flag is true —
-  evidence-driven lighting, never a fabricated activation); the 事件记录 tab
-  (`EventLogPage`, spec panel-tabs §5, plan `20260811-panel-event-log`) is a
-  NON-canvas log page with two partitions — **Agent 流转事件** (`view.events`
-  ≤50 latest-first; off-pipeline unexpected dispatches fold in once via
-  `expected: false` and carry a dispatch-only 「未匹配角色」 badge — settle
-  rows are completion records and never flag as unexpected) and **违规记录**
-  (`view.violations`, gate violations with severity/code/message); every row
-  is an expandable native `<details>` (no-JS, keyboard-accessible) whose body
-  shows the full catalog fields — missing fields render「—」, never a guessed
-  value. Layout (plan `20260811-panel-f3-agent-general`): the two partitions
-  render SIDE BY SIDE in a locked-height two-column grid
-  (`repeat(2, minmax(0, 1fr))` — the page never scrolls as a whole; each
-  partition pins its title and owns an internal `overflow-y` scroll on its
-  row list; plan `20260813-panel-quick-fixes` Task 4 root-caused the
-  whole-page scroll — the panel root opts into the host
-  `data-conversation-composer-overlay` (the host's documented full-height
-  opt-in), so the host `.viewArea` becomes a definite-height container and
-  `height:100%` resolves: `.rowList`'s `overflow-y: auto` now scrolls
-  INSIDE the partition and the host page no longer scrolls, with bottom
-  clearance reserving the floating composer via the host-published
-  `--dsh-composer-height`), falling back to two stacked 50/50 locked rows
-  below 1200px —
-  the `data-event-log-*` anchor family is unchanged. The canvas-corner **`AgentEventDock`** is REMOVED with the page
-  (无双份日志 — its row layout + status chips migrated into `EventLogPage`);
-  the fixed footer bar (zone legend + gate summary + violations) died with
-  the WorkflowCanvas in plan `20260811-panel-tabs-shell` — the footer that
-  remains is the freshness marker. Empty branches (spec §2 — plan
-  `20260812-panel-f5-agent-layout` Task 3): waiting keeps the muted hint,
-  and NO harness renders a **CENTERED inactive-state card** (folder icon +
-  「No Morning Star harness detected」 title + the hint copy — the detail
-  panel stays inactive, no tabs / no sidebar, activating automatically once
-  a harness is detected; the `data-mstar-empty="no-harness"` anchor stays on
-  the title, `data-mstar-graph` on the main container). Below 1200px
-  the zones stack vertically. Pure `projectGraph` projection (never throws,
-  explicit degraded states — muted empty states, never orange warn boxes).
-  The branches block left the sidebar in plan `20260810-panel-sidebar-info`
-  (its anchor fields ride the row's per-session snapshot payload, NOT the
-  persisted source — the source is the bare first-party `plugin` arm; the
-  iteration zone renders them via plan `20260810-panel-canvas-zones`); refresh
-  follows the session snapshot, no polling — while the main agent is ACTIVELY
-  orchestrating, a
-  ledger record (dispatch/settle) invalidates the workspace's TTL-cached
-  catalog row so the next pre-step rebuilds and (digest text change)
-  re-injects it, and the panel refreshes per step (seconds, not the 60 s TTL);
-  while the main agent IDLES (waiting, no tool calls) the panel keeps the
-  LAST snapshot — no live push channel (documented limit, plan
-  `20260811-panel-f4-timeliness`). Bundle served at
-  `/plugins/@mstar-harness/dsh/client.js` (closure-factory CJS with NO graph
-  library inlined — react-flow removed; the build asserts the bundle contains
-  no `xyflow`/`reactflow` markers, no `@deepseek-ai/*` value imports, and no
-  `import.meta` / ESM statements — the loader runs plugin bundles as classic
-  scripts). **Known limitations**: the stepper's Step 1 (iteration-start) IS
-  the current step while the steering compass is `status: active` (Phase 1 in
-  flight — catalog `compassStatus` field), carrying NO PASS/FAIL badge (Phase
-  1 has no gate verdict); Step 5 (merge-ready) can never be the CURRENT step —
-  the engine phase gate only evaluates Phase 2→3→4 (merge-ready is never a gate
-  transition); it renders `next` only while Step 4 (pr-delivery) is current,
-  idle otherwise;
-  the current step follows the TTL-refreshed `compassStatus` — up to one
-  catalog interval (60 s) behind a mid-session `active`→`locked` flip (bounded,
-  documented staleness, never a wrong verdict); the agent-entity
-  status derivation pairs a PAIRED settle exactly by its dispatch identity
-  (`agent`, `role`, `planId`, `taskId` — under QC-tri N=3 concurrency each
-  settle lands on ITS dispatch), and an unpaired dispatch stays `running`
-  (no paired settle — never guessed, never faked); the current-iteration
-  filter with NO steering compass infers the iteration from plan ids
-  (8-digit date prefix) + doneAt — deterministic, documented heuristic, and
-  only provably cross-iteration events are dropped; no historical back-scan of
-  resumed long logs; no custom
-  top-level slot (the `conversation.view` tab is the only session-level panel
-  seat without dsh-private layout changes); no-session → shell hero
-  (strict-session view ring). Panel acceptance is dual-track: in-loop browser
-  harness verification (agent-browser/CDP against the rebuilt bundle,
-  iteration guides record the verified runs) plus user-restart final GUI
-  acceptance.
+  and renders the session's stored snapshot, or an explicit unavailable
+  reason). **Morning Star Workflow layout**: a narrow-column shell bound to the
+  sidebar pane's definite height — exactly three zones: the **section nav**
+  (任务迭代 / 代理执行 / 事件记录; `data-mstar-tab-nav`), the panel-owned
+  **single scroll body** (`[data-mstar-scroll]` — the ONLY `overflow-y`
+  element in the panel; nothing scrolls horizontally; `data-mstar-graph`
+  rides it), and the pinned **meta dock** (version + harness dir; never
+  scrolls). The workspace-state digest (plans ≤5 time-desc + `+N more`,
+  open residual findings ≤10 with severity chips + overflow hint, policy
+  with **enforcement first** then push / worktree / control worktree,
+  leases, knowledge, direction) renders IN FLOW at the end of the scroll
+  body, closed by the freshness footer (`snapshot {time} · turn {turn}` —
+  the served snapshot's own timestamp + turn, never "live"). The three
+  sections stack in the scroll body: the tasks page (iteration head +
+  **vertical** 5-step stepper with the FOUR-STATE `current` / `next` /
+  `done` / `idle` machine + the branch panel + five stacked status groups
+  — the merged「受阻/未知」/「Blocked / Unknown」column kept, `PLAN_CAP`
+  render caps + the clickable 「更多」/「收起」 expand button
+  (`data-kanban-more`); the projection keeps ALL plan rows — then the
+  project rollup), the events page (two partitions — Agent 流转事件 /
+  违规记录 — as flow rows, every row an expandable native `<details>`
+  carrying the full catalog fields, missing fields render 「—」 never a
+  guessed value), and the agents page — a **vertical grouped list** (the
+  react-flow canvas, its SVG edge layer, card ports and pointer pan are
+  REMOVED): two Phase groups in constant order (Phase 1 review-edit-chain
+  above; Phase 2 sdd-implement → qc-tri → qa-gate below, its label
+  annotating the CURRENT plan — `data-agent-group-plan` + `+N more`),
+  `sdd-implement` split into implementor / reviewer sub-partitions, the
+  `general` bucket sunk into an `unknown` sub-bucket, the full 14-role
+  roster as full-width flow rows (idle rows dashed muted — the roster is
+  never hidden) with role chip / status point / `×N` count / record line,
+  the `N executing · M pending` summary, and the three-entry legend in
+  flow below the list; rows carry the projected **emphasis tier**
+  (`--mstar-canvas-emphasis-*` chrome alpha mix — never a whole-row
+  `opacity`, so the status point + running glow stay opaque), settled
+  entities get the standalone GREEN done frame + ✓
+  (`data-agent-done="true"`) ONLY when `emphasis ≠ 'off'`; the agents page
+  contains zero `<svg>`, zero `data-agent-port` / `data-canvas-*` anchors
+  and no pan transform. The **iteration info section is shared by the
+  tasks AND agents pages** (one `IterationInfoSection`, both render the
+  same `view.iteration` block). Empty branches are explicit states —
+  `waiting` / `loading` / `unavailable` (with its reason) / no-harness
+  each carry their OWN anchor and copy and render no tabs, no digest and
+  no meta dock; no harness renders a CENTERED inactive-state card that
+  activates automatically once a harness is detected (inside the same
+  single scroll zone). Projection is the pure `projectGraph(source)`
+  function (schema constants vs catalog evidence strictly separated; never
+  throws; explicit degraded states — muted empty states, never orange warn
+  boxes). Refresh follows the session snapshot, no polling — while the
+  main agent is ACTIVELY orchestrating, a ledger record (dispatch/settle)
+  invalidates the workspace's TTL-cached catalog row so the next pre-step
+  rebuilds and (digest text change) re-injects it, and the panel refreshes
+  per step (seconds, not the 60 s TTL); while the main agent IDLES the
+  panel keeps the LAST snapshot — no live push channel. Bundle served at
+  `/plugins/@mstar-harness/dsh/client.js` (closure-factory CJS with NO
+  graph library inlined — react-flow removed; the build asserts the bundle
+  contains no `xyflow`/`reactflow` markers, no `@deepseek-ai/*` value
+  imports, and no `import.meta` / ESM statements — the loader runs plugin
+  bundles as classic scripts). Full realized layout detail:
+  `packages/dsh/README.md` (§ Web client plugin). **Known limitations**:
+  the stepper's Step 1 (iteration-start) IS the current step while the
+  steering compass is `status: active` (Phase 1 in flight — catalog
+  `compassStatus` field), carrying NO PASS/FAIL badge (Phase 1 has no gate
+  verdict); Step 5 (merge-ready) can never be the CURRENT step — the
+  engine phase gate only evaluates Phase 2→3→4; the current step follows
+  the TTL-refreshed `compassStatus` — up to one catalog interval (60 s)
+  behind a mid-session `active`→`locked` flip (bounded, documented
+  staleness, never a wrong verdict); the agent-entity status derivation
+  pairs a PAIRED settle exactly by its dispatch identity (`agent`, `role`,
+  `planId`, `taskId`), and an unpaired dispatch stays `running` (never
+  guessed, never faked); with NO steering compass the current-iteration
+  filter infers the iteration from plan ids (8-digit date prefix) +
+  doneAt — deterministic, documented heuristic, only provably
+  cross-iteration events are dropped, no historical back-scan of resumed
+  long logs; the sidebar chip title is captured at open time; a docked
+  body renders nothing while `tab.visible === false`. Panel acceptance is
+  dual-track: in-loop browser harness verification against the rebuilt
+  bundle plus user-restart final GUI acceptance.
 
 ## Skill loading
 
@@ -270,6 +138,7 @@ or a custom profile).
 | dsh tool | Harness use |
 |----------|-------------|
 | **`subagent`** | Primary dispatch — the model-facing delegation tool the dispatch gate matches (default `toolName`; a renamed instance must be declared via Config `dispatchTools`) |
+| **`workflow`** | Read-only N≥3 fan-out — one run, one conversation `workflow-run` node (§ Read-only fan-out via the `workflow` tool; scripts → `references/dsh-workflow-scripts.md`) |
 | **`mstar_iteration_gate`** | Evaluate the iteration phase gate in-app (`evaluatePhaseGate` — `mstar iteration gate` parity) |
 | **`mstar_sdd_workspace`** / **`mstar_sdd_task_brief`** | SDD workspace resolve + task brief extraction (`mstar sdd …` parity) |
 | **`mstar_*_validate`** | On-demand seam validators (design-md / audit / compound / roles) |
@@ -324,10 +193,8 @@ build (`catalogTtlMs`, default 60 s).
 
 The plugin records ACTUAL subagent dispatch and real-completion settle events —
 the evidence of what really happened, distinct from the client-side expected
-role flow. The workflow panel's agent-execution zone (the stage/entity
-projection — plan `20260810-panel-agent-flow-zone`) and the 事件记录 tab's
-`EventLogPage` log page (plan `20260811-panel-event-log`) are pure consumers
-of this evidence.
+role flow. The workflow panel's 代理执行 (agents) page and the 事件记录
+tab's `EventLogPage` log page are pure consumers of this evidence.
 
 - **Recording point (one core)**: `DshHostAdapter.dispatchGate` is the SINGLE
   record path behind both dispatch surfaces — the `tools/pre-execute` listener
@@ -342,59 +209,107 @@ of this evidence.
   `beforeDispatch` followed by the identical text as an in-loop subagent tool
   call) records two dispatch events — the surfaces are mutually exclusive by
   design; the double record is documented, not deduplicated.
-- **File / bounds**: events append to `{HARNESS_DIR}/agent-flow.jsonl` (JSON
-  Lines, one event per line; harness dirs are gitignored by convention). The
-  ledger assumes ONE dsh process writes each harness dir (single-writer):
-  concurrent dsh sessions on the same repo can lose events (the append itself
-  is near-atomic O_APPEND, but truncation is a read-modify-write) — the loss
-  only under-reports actual flow in the panel, never a gate impact. After each
-  append the file truncates to the most recent **500** events; truncation is
-  size-gated (≈500 lines' typical size — small files stay append-only) and
-  performed as an atomic temp-file rename. The catalog read returns the
-  latest-first view with a default window of **50** and a role × outcome
-  summary. A MISSING file reads as the empty view ("no actual dispatches yet"
-  — recording starts at plan merge); an unreadable file is absent evidence;
-  malformed lines are skipped, never fatal.
-- **Settle = real completion pairing, never faked** (plan
-  `20260811-panel-f4-timeliness`): `tools/post-execute` IS part of the
+- **File / bounds**: events append to the ACTIVE workflow dir —
+  `{HARNESS_DIR}/workflows/<id>/agent-flow.jsonl` (JSON Lines, one event per
+  line; harness dirs are gitignored by convention) — never the harness root:
+  with no active lifecycle the record is SKIPPED with a one-time warn. The
+  append and the size-gated truncating read-modify-write form ONE critical
+  section behind a per-workflow lockdir, so a second dsh session sharing the
+  active lifecycle cannot silently drop the other writer's lines (steady state
+  stays one writer per workflow dir); any loss only under-reports actual flow
+  in the panel, never a gate impact. After each append the file truncates to
+  the most recent **500** events; truncation is size-gated (≈500 lines'
+  typical size — small files stay append-only) and performed as an atomic
+  temp-file rename. The catalog read returns the latest-first view with a
+  default window of **50** and a role × outcome summary. A MISSING file reads
+  as the empty view ("no actual dispatches yet" — recording starts at plan
+  merge); an unreadable file is absent evidence; malformed lines are skipped,
+  never fatal.
+- **Settle = real completion pairing, never faked**: `tools/post-execute`
+  IS part of the
   verified dsh-tools registry surface (`runPostExecute` dispatches the
   waterfall for every tool call — verified against the upstream source and
   pinned by a real-call probe). The pairing listener matches dispatch TOOLS
-  (Config `dispatchTools`, default `['subagent']`), looks up the exec's
-  `callId` in the apply-scoped pairing store, and branches on the verified
-  result shapes:
-  - `{ kind: 'background', taskId }` → store `taskId → dispatchRef`; the REAL
-    settle arrives via `ctx.tasks.onTaskDone` (terminal mapping
-    completed → ok / killed → denied / failed → error, `durationMs` when
-    available), wired through `ctx.inject(['tasks'])`.
+  (Config `dispatchTools`, default `['subagent', 'subagent_fork']`), looks up
+  the exec's agent-namespaced call key in the apply-scoped pairing store, and
+  branches on the verified result shapes:
+  - `{ kind: 'background', jobId }` (the registry job id, `<kind>-N`) → store
+    `jobId → dispatchRef` and the bounded job id as the ref's `taskRef`; the
+    REAL settle arrives via `ctx.inject(['jobs'])` → `jobs.onJobDone`
+    (terminal mapping completed → ok / killed → denied / failed → error,
+    `durationMs` when available). A background value without a valid `jobId` →
+    nothing mappable (no settle).
   - `{ kind: 'continuable', subagentId }` → no terminal signal this round →
-    no settle (documented limit — the child owns its turns).
+    no settle (documented limit — the child owns its turns); the value
+    authorizes the child-identity join below and nothing is copied onto a
+    settle.
   - any other successful value (foreground included) → settle `ok`; a failed
-    result (`isError`) → settle `error`.
+    result (`isError` or an `error` payload) → settle `error`. A returned
+    foreground `runId` is the settle's `childId`, extracted independently of
+    the outcome (an error settle keeps its identity without becoming `ok`).
   Pairing is apply-scoped (in-memory `callId → dispatchRef` /
-  `taskId → dispatchRef` maps created in the entry `apply`; an HMR restart
+  `jobId → dispatchRef` maps created in the entry `apply`; an HMR restart
   resets them, and completions outside the window stay unpaired). Every
   PAIRED settle carries the paired dispatch's identity (`role`/`planId`/
   `taskId` — same field names + semantics as the dispatch event; the registry
-  background-task id is never written as `taskId`, `taskRef` is reserved for
-  it). Unpaired payloads (non-dispatch tools, calls outside the pairing
-  window) record NOTHING — the ledger stays dispatch-only, never a
-  fabricated settle.
+  job id is never written as `taskId` — `taskId` stays the Assignment `Task N`
+  tag, `taskRef` is reserved for the registry id). Unpaired payloads
+  (non-dispatch tools, calls outside the pairing window) record NOTHING — the
+  ledger stays dispatch-only, never a fabricated settle.
+- **Child identity (`subagent-link`, nonterminal)**: the child session id is
+  published upstream as a PARENT-OWNED `subagent/catalog` session event
+  (`{ version: 0, childId, childCreatedAt, mode, label }`; `label` = the
+  delegation `description`), appended by the tool body — for the continuable
+  path BEFORE the tool returns. The join spans a per-dispatch CALL WINDOW: the
+  pre-execute reserves the first raw-label slot under the live parent Session
+  object and captures its `seq` as the window start; a valid `background` /
+  `continuable` result at `tools/post-execute` makes that exact candidate
+  eligible (every other outcome retires it to a tombstone; a duplicate label
+  was already refused a candidate at reservation). Eligibility walks
+  `eventAt(seq)` over `[fromSeq, end)`, where `end` is the session's `seq`
+  CAPTURED when the candidate became eligible — recovering a catalog appended
+  before the tool returned — while ONE root-context `session/event` observer
+  feeds the same matcher for later arrivals against the session's CURRENT
+  `seq`: only that live observer follows the session forward, so a catalog
+  appended after eligibility still joins through it (the catch-up scan stays
+  frozen at its captured endpoint). A matched
+  candidate is consumed once and appends `{ v: 1, ts, kind: 'subagent-link',
+  agent?, childId, label, role, planId?, taskId?, taskRef? }` to the
+  DISPATCH's own workflow dir (`ts` = observation time), correlating the
+  catalog child back to the dispatch identity mstar recorded. It is an
+  IDENTITY record, NOT a completion: no `outcome`, no `verdict`, no `paired`
+  marker. A background one-shot link also carries its registry `taskRef`; a
+  continuable link omits it. Settle rows carry an optional `childId` — a
+  foreground `runId`, or for background only when the join has already
+  supplied one.
+- **Join bounds (honest degrade)**: NO row when the label is missing/empty,
+  the dispatch unpaired, a background result carries no valid `jobId` (the
+  reserved candidate is retired — nothing mappable: no settle, no link),
+  the catalog version unknown, the mode not matching the result kind,
+  a continuable catalog naming a different child than the tool returned,
+  the slot map at capacity (500 labels per parent Session), or the slot
+  already consumed. The join is apply-scoped: no whole-history cold
+  scan and no `session/created` backfill — a catalog written before apply
+  (constructor seeds) can never label a new dispatch. Duplicate labels are
+  deterministic best-effort (first reservation + first matching catalog wins),
+  NOT proof of unique ownership. Not every provider emits a catalog — a remote
+  run without a `localAgent` produces none, so a dispatch may legitimately
+  have no link row.
 - **Catalog**: `state.agentFlow` carries the ledger view (`events` ≤ 50,
   latest-first, + `summary`); the model-facing `<mstar_engine_status>` text
   renders ONE compact `agent flow: …` line only when events > 0 (role totals
   top-5 + latest dispatch with HH:MM — the event detail lives in the
-  structured source, never the model text). A ledger record (dispatch/settle)
-  invalidates the affected workspace's TTL cache entry IMMEDIATELY
-  (apply-scoped `harnessDir → cache key` reverse map + invalidation closure,
-  plan `20260811-panel-f4-timeliness`) → the next pre-step rebuilds and (digest
-  text change) re-injects the row — the 60 s TTL no longer bounds
-  ledger-change latency; it still bounds non-ledger staleness.
+  structured source, never the model text). A ledger record
+  (dispatch/settle/link) invalidates the affected workspace's TTL cache entry
+  IMMEDIATELY (apply-scoped `harnessDir → cache key` reverse map +
+  invalidation closure) → the next pre-step rebuilds and (digest text change)
+  re-injects the row — the 60 s TTL no longer bounds ledger-change latency; it
+  still bounds non-ledger staleness.
 - **Maintainer view**: change the ledger shape (event schema, bounds, settle
   seam) and update the projections together — `gates/agent-flow.ts` (record /
-  read / settle listener), `gates/catalog.ts` (agent-flow line + `source`
-  view) and `client/panel/graph/project-graph.ts` (the ZoneView flow/agents
-  projection) — the panel renders ONLY what the evidence shows.
+  read / settle / catalog-join listeners), `gates/catalog.ts` (agent-flow line
+  + `source` view) and `client/panel/graph/project-graph.ts` (the ZoneView
+  flow/agents projection) — the panel renders ONLY what the evidence shows.
 
 ## PM dispatch
 
@@ -433,15 +348,36 @@ the "queued messages" dock instead of reaching the parent (observed on dsh).
 The closing message is the guaranteed delivery channel; reserve `report` for
 MID-turn findings that change what the parent should do next.
 
+### Progress discipline — native workflow, never `/goal`
+
+dsh progress is driven by the **native workflow**: the workflow snapshot phases
++ the dispatch gates + **subagent settle notifications**. mstar **stops arming**
+a goal on dsh — the surviving bridge is advisory-only (no `create` / `edit` /
+`complete` / `pause` / `resume`, no goal read) — so no goal round loop drives
+mstar work here. Never drive a dsh session with a `/goal` objective or a goal
+round loop: `goal-round-driver` opens a round whenever the goal is active +
+armed and the agent is idle, and it knows nothing about running subagents, so
+an operator who arms `/goal` manually can still get rounds firing while a
+dispatched child owns the critical path.
+
+**Phase 2 continuous execution is a PM-local loop**: dispatch → **wait for the
+child's settle notification** → next dispatch. When a dispatched child owns the
+critical path, the correct action is to **wait** — not to open another unit of
+work against the same worktree.
+
 ### QC default
 
-- **`Execution mode: sdd`**: **N=3** `subagent` dispatches — one per QC seat
-  (`qc-specialist`, `qc-specialist-2`, `qc-specialist-3`), each body **Act as**
-  the respective QC role + QC skill load. **MUST dispatch all three with
-  `run_in_background: true` in one message** → the seats run CONCURRENTLY
-  (background children; wall ≈ single seat); foreground (no
-  `run_in_background`) runs serially (wall ≈ 3× single seat) and does NOT
-  count as parallel tri. Cannot emit required **N** → **`Blocked`**.
+- **`Execution mode: sdd`**: **N=3** seats — one per QC seat (`qc-specialist`,
+  `qc-specialist-2`, `qc-specialist-3`), each body **Act as** the respective QC
+  role + QC skill load. Read-only fan-out of N≥3 on dsh uses the native
+  **`workflow`** tool (the `mstar-qc-tri` script — § Read-only fan-out via the
+  `workflow` tool): one run, three concurrent children, one conversation
+  `workflow-run` node. When the tool is not mounted (the `ptc` preset hides it),
+  fall back to the `subagent` path below. **The `subagent` path MUST dispatch all
+  three with `run_in_background: true` in one message** → the seats run
+  CONCURRENTLY (background children; wall ≈ single seat); foreground (no
+  `run_in_background`) runs serially (wall ≈ 3× single seat) and does NOT count
+  as parallel tri. Cannot emit required **N** → **`Blocked`**.
 - **`inline`**: **N=1**.
 
 ### SDD implement (serial)
@@ -450,6 +386,63 @@ MID-turn findings that change what the parent should do next.
   task reviewer = a separate dispatch (SDD review role) — no sticky resume
   unless the host's continuable-subagent id is available and recorded.
 
+## Read-only fan-out via the `workflow` tool
+
+dsh also exposes the upstream **`workflow`** tool
+(`@deepseek-ai/dsh-tool-workflow`, mounted by the shipped agent presets; the
+`ptc` preset disables it in favour of its own orchestration surface). It runs a
+model-written plain-JavaScript script that fans children out inside ONE run; the
+run is recorded as durable `tool-workflow/*` session events and the stock dsh UI
+(`dsh-client-ui-workflow-run`) folds them into one conversation **`workflow-run`**
+node the operator expands by phase and member. Use it for **read-only fan-out of
+N ≥ 3 seats** — plan QC tri, large-repo audit categories, `/amazing-pr-review
+deep` seats — and copy the `script` + `meta` + `args` from this skill →
+`references/dsh-workflow-scripts.md`. For **1–2** delegations keep **`subagent`**
+(the tool's own guidance): the two-seat default tier of `/amazing-pr-review`
+shows two subagent cards and no `workflow-run` node, and that is expected.
+
+**Read-only only.** A workflow child is a delegated child (the shipped `spawn`
+provider pins `approval: never` for the whole delegation), and the run has **no
+per-child pre-start veto seam** — so a script is never the channel for writable
+work; writable fan-out stays on `subagent` behind the dispatch and lease gates.
+Seats return findings in their result payload and must never depend on writing
+files — the caller persists the seat reports.
+
+**Every `agent()` prompt starts with the Assignment header** — `## Assignment`
+plus `Execute as` / `Delegation` / `Task category` as the first lines:
+
+```markdown
+## Assignment
+
+Execute as: qc-specialist
+Delegation: forbidden
+Task category: audit
+```
+
+Role binding on dsh is prompt-only (there is no `agent` field), and the same
+engine grammar is what the role-persona channel parses
+(`packages/dsh/src/gates/role-persona.ts` reads only the header region) — so
+`Execute as: qc-specialist` resolves the QC role persona for that child. Keep
+body-quoted field examples out of the header region, and never pass the deferred
+`agentType` option: the engine rejects it loudly.
+
+| Operator types | N | Tool | `meta.name` | Operator sees |
+|---|---|---|---|---|
+| `/codebase-audit` (large repo) | ≥3 | native `workflow` | `mstar-audit-fanout` | conversation `workflow-run` node |
+| `/amazing-pr-review deep` | ≥3 | native `workflow` | `mstar-pr-seats` | same |
+| `/amazing-pr-review` default tier | 2 | `subagent` | — | two subagent cards, no node (expected) |
+| Plan QC tri (PM already in session, no extra slash) | 3 | native `workflow` | `mstar-qc-tri` | conversation `workflow-run` node |
+| Any 1–2 read-only delegation | 1–2 | `subagent` | — | expected |
+
+`meta.name` is the gate identity — keep it kebab-case and on the recommended
+list. With the default Config (`workflowNames` unset) every name is *unknown*,
+which under the default `workflowGate: warn` is one `workflow.name.unknown`
+**advisory that the run survives** — acceptable on a first run, not a failure. A
+production overlay may set `workflowNames: ['mstar-qc-tri', 'mstar-audit-fanout',
+'mstar-pr-seats']` (and, separately, `workflowGate: hard`); both are operator
+choices, never mstar defaults. The same run also reaches the panel's 事件记录 tab
+through the agent-flow ledger (§ Agent-flow ledger).
+
 ## Commands and skills paths
 
 | Surface | Path / invocation |