@mstar-harness/dsh 3.8.1 → 3.8.2

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

@@ -138,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) |
@@ -208,59 +209,107 @@ tab's `EventLogPage` log page are pure consumers 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.
+- **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)
-  → 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
 
@@ -299,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)
@@ -316,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 |

package/harness-skills/mstar-roles/references/project-manager.md

@@ -104,6 +104,8 @@ In invoke-based hosts (OpenCode / Cursor Task / Codex with callable multi-agent
 
 Host invoke/dispatch details: `mstar-host` → active host reference and `references/parallel-dispatch.md`.
 
+**dsh:** mstar **stops arming** a goal — dsh progress is the native workflow (workflow snapshot phases + dispatch gates + **subagent settle notifications**), never a `/goal` objective or goal round loop. Phase 2 is a PM-local loop (dispatch → wait for the child's settle notification → next dispatch); a dispatched child owning the critical path means **wait**, not a duplicate work unit. Rule → `mstar-host` → `references/dsh.md`.
+
 Dispatch mechanics and templates:
 `references/project-manager/dispatch-and-assignment.md`.
 

package/harness-skills/mstar-sdd/SKILL.md

@@ -94,6 +94,8 @@ Host mapping → **`mstar-host`** references (`model` / Task field).
     - **Honest non-convergence**: open findings at wave close → list them in detail and state the disposition — re-feed to the next fix round **or** transfer to residual tracking — never silently close.
 4. QA gate → **`mstar-harness-core`** Done rules; PM **`mstar-roles/references/project-manager/qa-trigger-matrix.md`**
 
+> **On dsh:** the plan QC tri MAY run through the native **`workflow`** tool instead of three `subagent` dispatches — take the `script` + `meta` (`meta.name: mstar-qc-tri`) from skill **`mstar-host`** → `references/dsh-workflow-scripts.md` (§ `mstar-qc-tri`); the three seats stay read-only and PM persists `{SDD_DIR}/review/qc1.md`…`qc3.md` from their returned envelopes. Per-task implementers stay **serial `subagent`** — the `workflow` channel is read-only fan-out only; when the tool is unmounted (`ptc` preset) dispatch the three seats as background `subagent` calls (skill **`mstar-host`** → `references/dsh.md`).
+
 ## Progress ledger（Evidence）
 
 At start: `cat {SDD_DIR}/progress.md`. Tasks marked complete are DONE — do not re-dispatch after compaction.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mstar-harness/dsh",
-  "version": "3.8.1",
+  "version": "3.8.2",
   "description": "Morning Star harness dsh (DeepSeek Harness) cordis function plugin — in-process engine gates (status/dispatch/lease) with hard refusal channels.",
   "keywords": [
     "dsh",
@@ -145,7 +145,7 @@
     "anser": "^2.3.5",
     "bun-types": "^1.2.17",
     "clsx": "^2.0.0",
-    "dsh-llm-fallbacks": "0.4.1",
+    "dsh-llm-fallbacks": "0.5.2",
     "immer": "^10.1.1",
     "js-yaml": "^4.1.0",
     "katex": "^0.16.47",