@mstar-harness/dsh 2.4.1 → 3.1.0

package/dist/gates/agent-flow.d.ts

@@ -214,8 +214,15 @@ export type AgentFlowEvent = {
  * settle carrying the SAME identity fields as its dispatch event.
  */
 export interface AgentFlowDispatchRef {
-    /** The resolved `{HARNESS_DIR}` the dispatch recorded into (settles record into the same ledger). */
+    /** The resolved `{HARNESS_DIR}` the dispatch was attributed to. */
     harnessDir: string;
+    /**
+     * The ACTIVE workflow dir the dispatch event was appended to
+     * (`<harnessDir>/workflows/<id>` — v3 layout). The settle records into
+     * the SAME file (settle pairing reads/writes the same ledger), even if
+     * the active set changed between dispatch and settle.
+     */
+    workflowDir: string;
     /** The dispatching session's stable id ('' when the exec carried none). */
     agent?: string;
     /** Assignment `Execute as` ('' when missing — the dispatch event's grammar). */
@@ -293,6 +300,74 @@ export declare function setAgentFlowLogger(sink: AgentFlowLogSink | undefined):
  * @param prompt - the full Assignment text.
  */
 export declare function taskIdOf(prompt: string): string | undefined;
+/**
+ * Resolve the agent-flow WRITE target dir for one harness dir: the ACTIVE
+ * workflow's dir (root v2 `workflows[]` first entry — the shared active-set
+ * resolver; the terminal-mtime fallback is catalog-read-only and MUST NOT
+ * enter the writer's module graph). The active set is defined by root
+ * `workflows[]` MEMBERSHIP — non-terminal lifecycles (`running` AND
+ * `paused`; terminal lifecycles are removed at terminal) — so a paused
+ * lifecycle stays a valid append target (explicit decision, plan
+ * `20260819-workflow-dsh-viz` Task 2).
+ *
+ * No active entry → `null`: the record is SKIPPED with a one-time warn
+ * (per sink binding) — never a silent write into the root v1 file, never a
+ * write into a terminal snapshot dir (compass v3.0.0 § Catalog selection
+ * rule — the writer appends only to an active lifecycle).
+ * @param harnessDir - the resolved `{HARNESS_DIR}`.
+ * @returns the absolute workflow dir (`<harnessDir>/workflows/<id>`), or
+ *   `null` when no active lifecycle resolves.
+ */
+export declare function resolveAgentFlowWriteDir(harnessDir: string): string | null;
+/**
+ * Lock-directory name for the per-workflow write lock (qc3 W-1 fix-wave):
+ * guards the ledger append + size-gated truncating read-modify-write AND
+ * the workflow-ledger cursor sidecar read-modify-write against concurrent
+ * dsh processes sharing one active lifecycle (compass ruling 3). The
+ * lockdir lands INSIDE the workflow dir — dirname of the ledger — so it
+ * never pollutes the harness root (same placement rule as the engine's
+ * `withStatusWriteLock` lockdir).
+ */
+export declare const WORKFLOW_LEDGER_LOCKDIR = ".ledger-write.lockdir";
+/**
+ * Run `fn` under the per-workflow inter-process write lock (qc3 W-1
+ * fix-wave): atomic `mkdir` on `<workflowDir>/.ledger-write.lockdir/`
+ * acquires (success acquires; existing dir → another writer holds the
+ * lock); while another writer holds it, wait up to
+ * {@link WORKFLOW_LOCKER_TIMEOUT_MS} and then THROW (Blocked — the
+ * lockdir is never removed for another holder). Ownership guard
+ * (double-unlock safety): the lockdir's `(dev, ino)` is captured at
+ * acquisition; `finally` re-stats the path and removes the directory ONLY
+ * when the identity is unchanged. Sync reentrancy detection: a nested
+ * acquisition on the same lockdir within this process throws immediately
+ * (sync code cannot interleave — a held dir is a bug, not contention).
+ * Crash diagnosis: a `holder.pid` file (acquiring process id) is written
+ * inside the lockdir on acquisition and removed on release; a hard crash
+ * leaks the lockdir and the timeout error names the recovery step.
+ *
+ * SAME PATTERN as the engine's `withStatusWriteLock` (packages/engine/src/
+ * lease.ts) — atomic-mkdir lockdir, the SSOT-documented alternative to
+ * `flock` on Bun (no `node:fs` flock); unlike flock, a hard crash leaks
+ * the lockdir (documented residual, recovery = remove when no writer is
+ * alive).
+ *
+ * Steady state: ONE writer per workflow dir (one dsh process per
+ * lifecycle). The lock serializes the multi-session shared-lifecycle case
+ * (compass ruling 3) and is held ONLY around the bounded critical section
+ * (append+truncate, or the cursor read-modify-write) — never across scans.
+ * @param workflowDir - the workflow dir whose ledger/cursor files the
+ *   critical section touches.
+ * @param fn - the critical section (sync; the lock is sync by design — the
+ *   ledger record paths are called from sync gate hooks).
+ * @param opts - `timeoutMs` / `pollMs` overrides (defaults 30 s / 10 ms) —
+ *   the same testable options as the engine's `withStatusWriteLock`
+ *   (`lease.ts`); production callers never set them.
+ * @returns the critical section's return value.
+ */
+export declare function withWorkflowDirLock<T>(workflowDir: string, fn: () => T, opts?: {
+    timeoutMs?: number;
+    pollMs?: number;
+}): T;
 /**
  * Record one dispatch event (spec §2.1.3). Fully try/catch-contained — NEVER
  * throws into the gate; a failing record logs only (`mstar/agent-flow`).
@@ -327,14 +402,21 @@ export declare function recordDispatch(input: {
 /**
  * Record one settle event (spec §2.1.3). Fully try/catch-contained; a failing
  * record logs only. Callers resolve the harness dir from the PAIRED dispatch
- * (the pairing store's dispatchRef — never a payload probe).
- * @param input - harness dir + agent id + outcome + optional duration + the
- * PAIRED dispatch's identity (`role`/`planId`/`taskId` — same field names +
- * semantics as the dispatch event; written for every paired settle, so the
- * client can exactly pair the settle back to its dispatch).
+ * (the pairing store's dispatchRef — never a payload probe). The settle
+ * appends to the ACTIVE workflow dir (v3 layout); a PAIRED settle carries
+ * the dispatchRef's `workflowDir` so it lands in the SAME file as its
+ * dispatch even if the active set changed in between. An unpaired direct
+ * call resolves the active workflow from `harnessDir`; no active lifecycle
+ * → skipped with a one-time warn (never a root v1 write).
+ * @param input - harness dir + optional paired workflow dir + agent id +
+ * outcome + optional duration + the PAIRED dispatch's identity
+ * (`role`/`planId`/`taskId` — same field names + semantics as the dispatch
+ * event; written for every paired settle, so the client can exactly pair
+ * the settle back to its dispatch).
  */
 export declare function recordSettle(input: {
     harnessDir: string;
+    workflowDir?: string;
     agent?: string;
     outcome: SettleOutcome;
     durationMs?: number;
@@ -353,14 +435,24 @@ export declare function recordSettle(input: {
  * from the durable `tool-workflow/*` session event (`ts` takes the envelope's
  * `time`). Malformed input is a caller bug — the strict narrowing applies on
  * READ (`eventFromUnknown`), never here.
- * @param input - harness dir + the fully-shaped v1 workflow event.
+ *
+ * v3 write path: the event appends to the ACTIVE workflow dir (root v2
+ * `workflows[]` first entry). The consumer passes the already-resolved
+ * `workflowDir` (it needs it for the durable watermark anyway — one
+ * resolution per row); a direct caller without it resolves from
+ * `harnessDir`. No active lifecycle → `false` (skipped with a one-time warn
+ * — never a root v1 write, never a terminal snapshot write).
+ * @param input - harness dir + optional pre-resolved active workflow dir +
+ * the fully-shaped v1 workflow event.
  * @returns `true` when the row was appended (the caller may durably advance
- *   its watermark); `false` on a contained append failure — the caller must
- *   leave the cursor behind so the row is re-attempted at the next scan
- *   (qc3 R-401: advance-then-record made a failed append permanent loss).
+ *   its watermark); `false` on a contained append failure OR when no active
+ *   lifecycle resolves — the caller must leave the cursor behind so the row
+ *   is re-attempted at the next scan (qc3 R-401: advance-then-record made a
+ *   failed append permanent loss).
  */
 export declare function recordWorkflowEvent(input: {
     harnessDir: string;
+    workflowDir?: string;
     event: AgentFlowWorkflowEvent;
 }): boolean;
 /**
@@ -417,11 +509,24 @@ export declare function recordWorkflowVerdict(input: WorkflowVerdictInput): void
  * state instead of an evidence-missing degrade; only an UNREADABLE file
  * returns null (advisory degrade — the catalog renders no agent-flow line).
  * Malformed lines are skipped, never fatal.
- * @param harnessDir - the resolved `{HARNESS_DIR}`.
+ *
+ * v3 layout: the ledger lives in the WORKFLOW dir (`<harnessDir>/workflows/
+ * <id>`), never the harness root — the dir parameter IS the workflow dir
+ * (the catalog passes `join(harnessDir, selection.dir)`; the writer appends
+ * there via `resolveAgentFlowWriteDir`).
+ *
+ * Large-file reads (plan `20260820-dsh-ledger-tail-read`): ledgers above
+ * `AGENT_FLOW_TAIL_READ_THRESHOLD_BYTES` are read as a bounded latest-first
+ * tail — seek from EOF, aligned to a line boundary, doubling backward until
+ * the window holds `limit` complete lines — so the catalog pays O(window) at
+ * the byte layer instead of parsing every historical line. Both paths feed
+ * the SAME parse funnel below (`ledgerContent` yields a `content` string),
+ * so tail/full parity is structural.
+ * @param workflowDir - the workflow dir whose `agent-flow.jsonl` is read.
  * @param limit - explicit window bound: `undefined` → `AGENT_FLOW_DEFAULT_LIMIT`;
  * otherwise `Math.max(0, Math.floor(limit))` — `0` requests the EMPTY window.
  */
-export declare function readAgentFlow(harnessDir: string, limit?: number): AgentFlowView | null;
+export declare function readAgentFlow(workflowDir: string, limit?: number): AgentFlowView | null;
 /**
  * The `tools/post-execute` settle pairing (plan `20260811-panel-f4-timeliness`
  * Task 1 — replaces the old defensive payload probing): the VERIFIED

package/dist/gates/dispatch.d.ts

@@ -61,7 +61,8 @@ export declare function isAssignmentShaped(assignmentText: string): boolean;
  * Resolve the hard-enforcement flag for one dispatch: explicit Config override
  * wins, else the Assignment's OWN `Enforcement: hard` header flag (opencode
  * parity — header region only, a body-quoted example never hardens), else the
- * iteration compass frontmatter, else warn-only.
+ * repo `.mstarc` `[config] enforcement`, else the iteration compass
+ * frontmatter, else warn-only.
  */
 export declare function resolveDispatchHard(harnessDir: string | null, config: Config, assignmentText: string): boolean;
 /** A header value that means "no value" (placeholder conventions). Type guard so callers narrow to `string`. Shared with the agent-flow ledger (qc1 F-003 — one grammar, no copy-paste drift). */
@@ -93,8 +94,11 @@ export declare function sessionIdOf(exec: ToolExecution): string | undefined;
  * `dispatch.execution-mode.*` codes stay out of the parity field set) OR
  * whose plan row is `InProgress`.
  *
- * Contract (status-and-residuals.md § Pre-dispatch re-verify): before any
- * writable implement dispatch, reread `{HARNESS_DIR}/status.json` and confirm
+ * Contract (status-and-residuals.md § Pre-dispatch re-verify; v3
+ * relocation — plan `20260819-workflow-dsh-viz` Task 3): before any
+ * writable implement dispatch, reread the ACTIVE workflow snapshot
+ * (`workflows/<id>/snapshot.json` — the v1 root `plans[]` home is gone; the
+ * root v2 `status.json` supplies the active `workflows[]`) and confirm
  * the session still passes verify-held-lease — `holder`, `worktree_path` and
  * `working_branch` must match the Assignment; mismatch or absent lease →
  * STOP. Engine `verifyPlanExecutionLease` + `validateExecutionLease` carry
@@ -104,13 +108,15 @@ export declare function sessionIdOf(exec: ToolExecution): string | undefined;
  *
  * Degrade-allow cases (no false positives): no harness dir, unresolvable plan
  * id, and non-SDD assignments whose plan row is absent or not InProgress.
- * Unverifiable lease states (malformed status.json, MISSING status.json, plan
- * row not registered) are violations ONLY for sdd dispatches (the lease state
- * cannot be confirmed — the status gate already guards the next write);
- * unreadable docs never harden a soft workflow. Missing status.json is NOT a
- * silent fail-open for sdd: the claim-before-InProgress red line
- * needs the plan's execution_lease, and a missing status file cannot confirm
- * it — `lease.dispatch.unverifiable` fires (advisory in warn, deny under hard).
+ * Unverifiable lease states (unreadable/missing root status.json, a
+ * selection failure — v1/migration-required root, no active workflow — an
+ * unreadable/missing snapshot, plan row not registered) are violations ONLY
+ * for sdd dispatches (the lease state cannot be confirmed — the status gate
+ * already guards the next write); unreadable docs never harden a soft
+ * workflow. A missing status.json is NOT a silent fail-open for sdd: the
+ * claim-before-InProgress red line needs the plan's execution_lease, and a
+ * missing root/snapshot cannot confirm it — `lease.dispatch.unverifiable`
+ * fires (advisory in warn, deny under hard).
  */
 export declare function leaseGateViolations(harnessDir: string | null, exec: ToolExecution, writable: boolean | undefined, prompt: string): ValidationResult[];
 /**

package/dist/gates/goal-bridge.d.ts

@@ -133,7 +133,7 @@ export declare function rootAgentOf(agent: unknown, agents: AgentsView): unknown
  * compare when the mirror is in place — no churn) — plus a THIRD, advisory
  * listener on the `session/event` firehose (Task 3): a `goal/change`
  * envelope whose goal is blocked logs ONE warn (code + objective summary +
- * `{HARNESS_DIR}/status.json` residual pointer) with ZERO harness writes
+ * project-register residual pointer) with ZERO harness writes
  * (the one-way mirror; see {@link warnBlockedGoal}). The goals service is an
  * OPTIONAL seam (`ctx.get('goals')` structural read): absent → ONE debug log
  * + the mirror stays inert, never a boot failure — the blocked advisory is

package/dist/gates/status.d.ts

@@ -33,21 +33,66 @@ export interface StatusGateAdvisory {
     degraded?: boolean;
 }
 /**
- * Validate a PARSED status document through the status-gate pipeline
- * (engine `validateStatus` + `findingsCleanupGate` per plan row that
- * CONFIGURES a mode). Shared by {@link validateStatusDoc} (the on-disk
- * single-read path) and the host adapter's `beforeStatusWrite` (the
- * incoming document) — the fs-intent gate, the adapter hook and the repair
- * escape all surface the SAME violation codes.
+ * Canonical `{HARNESS_DIR}` coordination-document kinds the status gate
+ * covers (opencode-parity vocabulary — the SAME three kinds the P2-fixed
+ * opencode `harnessDocKindOfTarget` classifies): the v2 root `status.json`,
+ * `workflows/<id>/snapshot.json`, and `projects/<id>/residuals.json`. Each
+ * kind maps to its matching engine validator in
+ * {@link validateStatusValue}.
  */
-export declare function validateStatusValue(doc: unknown): GateResult;
+export type HarnessDocKind = 'status' | 'snapshot' | 'register';
 /**
- * Run the status gate over the CURRENT on-disk document. The fs intent
- * waterfall carries only `(target, actor)` — never the incoming content — so
- * the vetoable check is the pre-write state (the opencode hook's fallback for
- * the same reason). `findingsCleanupGate` runs per plan row that CONFIGURES a
- * mode (`plans[].metadata.findings_cleanup`); schema violations short-circuit
- * it (the doc must parse for the cleanup gate to be meaningful).
+ * Classify one fs target as a canonical `{HARNESS_DIR}` coordination
+ * document: basename ∈ {status.json, snapshot.json, residuals.json} AND the
+ * harness-relative path matches the canonical home (root `status.json`,
+ * `{WORKFLOW_DIR}/<id>/snapshot.json`, `{PROJECT_DIR}/<id>/residuals.json`
+ * — one path component each, mirroring the P2-fixed opencode
+ * `harnessDocKindOfTarget`).
+ *
+ * Phase-5 F1: the snapshot/register rel is computed against the RESOLVED
+ * layout dirs (`resolveWorkflowDir` / `resolveProjectDir` — a `.mstarc`
+ * `[config] workflow_dir` / `project_dir` declaration wins, defaults
+ * `workflows` / `projects` under the harness dir), so a custom layout
+ * classifies at the same location the runtime writes; resolver failure
+ * (never expected with the explicit harness dir) falls back to the default
+ * names.
+ *
+ * dsh divergence from the opencode probe (documented): opencode resolves
+ * the harness root by marker probe (W-REV-1) with a declared-root fallback;
+ * the dsh gates ALREADY resolve `{HARNESS_DIR}` per calling session
+ * workspace through the shared `HarnessResolver` BEFORE the intent slot
+ * runs, so classification here is against that resolved root — no second
+ * probe, no W-REV-3 rebuild. Returns the kind when gated, `null` otherwise
+ * (a non-coordination target, or a path outside the resolved harness dir —
+ * the gate is inert for them).
+ */
+export declare function harnessDocKindOfTarget(harnessDir: string, targetPath: string): HarnessDocKind | null;
+/**
+ * Validate a PARSED harness coordination document through the
+ * kind-matched engine validator (v2 root / workflow snapshot / project
+ * register — the P2-fixed "one validator per kind" shape) plus the
+ * snapshot-only `findingsCleanupGate` extension per plan row that
+ * CONFIGURES a mode (the v1 per-plan-row cleanup gate relocated: plan rows
+ * live on the snapshot, residuals on the project registers). Shared by
+ * {@link validateStatusDoc} (the on-disk single-read path) and the host
+ * adapter's `beforeStatusWrite` (the incoming document) — the fs-intent
+ * gate, the adapter hook and the repair escape all surface the SAME
+ * violation codes.
+ * @param kind - the target's {@link HarnessDocKind} (matching engine validator).
+ * @param harnessDir - the resolved `{HARNESS_DIR}`; required for the
+ * snapshot kind's cleanup extension (the registers it reads live under it),
+ * otherwise unused.
+ */
+export declare function validateStatusValue(doc: unknown, kind: HarnessDocKind, harnessDir?: string | null): GateResult;
+/**
+ * Run the status gate over the CURRENT on-disk document at a canonical
+ * harness coordination target. The fs intent waterfall carries only
+ * `(target, actor)` — never the incoming content — so the vetoable check
+ * is the pre-write state (the opencode hook's fallback for the same
+ * reason). The kind-matched validator runs via {@link validateStatusValue}
+ * (the snapshot kind's `findingsCleanupGate` extension included) — schema
+ * violations short-circuit it (the doc must parse for the cleanup gate to
+ * be meaningful).
  *
  * Single-read contract: the file is parsed exactly once and the
  * parsed doc is passed to {@link validateStatusValue} — the previous
@@ -57,8 +102,13 @@ export declare function validateStatusValue(doc: unknown): GateResult;
  * shape; never throws. Missing files are guarded by the callers
  * (`gateStatusIntent`, {@link DshHostAdapter.statusGate}) — first create has
  * no document to validate and passes before this function runs.
+ * @param path - the canonical coordination-document path (root status.json
+ * / workflow snapshot / project register — the caller classifies it).
+ * @param kind - the target's {@link HarnessDocKind}.
+ * @param harnessDir - the resolved `{HARNESS_DIR}` (the snapshot kind's
+ * cleanup extension needs it to locate the project registers).
  */
-export declare function validateStatusDoc(statusPath: string): GateResult;
+export declare function validateStatusDoc(path: string, kind: HarnessDocKind, harnessDir?: string | null): GateResult;
 /**
  * `fs/write-intent` listener. Registered with `prepend` so this decider runs
  * BEFORE dsh-fs-policy regardless of mount order: the slot is first-wins by

package/dist/gates/system-prompt.d.ts

@@ -38,9 +38,13 @@
  * - The context provider reuses the catalog's unified machine-summary
  *   source (`buildCatalogSources` — the SAME builder the engine-status
  *   pre-step catalog row uses) and projects a BOUNDED subset: watermark +
- *   iteration gate + compact state line. Full status.json content
+ *   iteration gate + compact state line. Full catalog content
  *   (residual detail, agent-flow events, knowledge digest, branch/policy
- *   anchors) stays out. The build is TTL-memoized PER RESOLVED HARNESS DIR
+ *   anchors) stays out. v3 (plan `20260819-workflow-dsh-viz` Task 3): the
+ *   digest reads ONLY the catalog row (`state` — itself aggregated from the
+ *   SELECTED workflow snapshot + project registers) — no direct
+ *   status.json / snapshot file reads to change. The build is TTL-memoized
+ *   PER RESOLVED HARNESS DIR
  *   (`DEFAULT_CATALOG_TTL_MS`) so the per-assembly hot path does not
  *   re-read status.json / the compass / the ledger on every prompt
  *   assembly (the catalog's documented staleness tradeoff).

package/dist/gates/workflow-ledger.d.ts

@@ -23,19 +23,34 @@
  *
  * DEDUPE (qc2 W-1 / qc3 F-301 fix-wave): ONE DURABLE per-session watermark —
  * the next expected envelope `seq` (session-log position) — persisted to
- * `{HARNESS_DIR}/workflow-ledger-cursors.json` (a small bounded sidecar next
- * to `agent-flow.jsonl`, written atomically temp-file + rename through the
- * same containment discipline). The watermark is consulted AND advanced by
- * every scan (cold / created-backfill / live): envelopes with `seq` below it
- * were already recorded — across cold+live overlap AND across plugin
- * re-applies (a re-registration no longer re-records the same live
- * sessions). The watermark advances only AFTER the ledger row appended
- * successfully (qc3 R-401 — a failing append leaves the cursor behind, so
- * the row is re-attempted at the next scan, never permanently lost). The
- * in-memory Map is the durable file's mirror (module-level
- * cache, bounded by the session cap); any watermark read/write failure
- * degrades to in-memory-only with one warn — a ledger row is never lost and
- * the workflow run is never affected.
+ * `{HARNESS_DIR}/workflows/<id>/workflow-ledger-cursors.json` (a small
+ * bounded sidecar next to the workflow-dir `agent-flow.jsonl`, written
+ * atomically temp-file + rename through the same containment discipline; the
+ * root cursor file is NOT read after migration — no read fallback). The
+ * watermark is consulted AND advanced by every scan (cold /
+ * created-backfill / live): envelopes with `seq` below it were already
+ * recorded — across cold+live overlap AND across plugin re-applies (a
+ * re-registration no longer re-records the same live sessions). The
+ * watermark advances only AFTER the ledger row appended successfully (qc3
+ * R-401 — a failing append leaves the cursor behind, so the row is
+ * re-attempted at the next scan, never permanently lost). The in-memory
+ * Map is the durable file's mirror (module-level cache keyed by WORKFLOW
+ * DIR, bounded by the session cap AND by a workflow-dir count cap — qc3
+ * S-4 — so a long-lived process across many workflow ids never grows the
+ * cache unbounded); a failed durable write keeps the in-memory mirror
+ * advanced (in-process dedupe — qc3 S-6) with one warn — a ledger row is
+ * never lost and the workflow run is never affected.
+ *
+ * INTER-PROCESS SERIALIZATION (qc3 W-1 fix-wave): the watermark
+ * read-modify-write (load fresh → mutate → whole-map save) runs inside the
+ * per-workflow write lock shared with the ledger append
+ * (`withWorkflowDirLock` from agent-flow.ts — the same lockdir pattern as
+ * the engine's `withStatusWriteLock`). Steady state is ONE writer per
+ * workflow dir; under multi-session shared lifecycle (compass ruling 3)
+ * the lock makes the cursor save read-modify-write atomic across
+ * processes — a whole-map save can no longer silently clobber another
+ * process's just-advanced cursor (the duplicate-row regression mode). The
+ * lock is held only around the bounded cursor update, never across scans.
  *
  * Mapping (Task 2 schema): `tool-workflow/run-start` → `workflow-run`
  * (`agent` = the carrying parent session id), `tool-workflow/agent-start` →
@@ -92,12 +107,15 @@ import type { WorkflowAskCache } from './workflow-policy.ts';
 /** Logger label for the workflow-ledger consumer (dsh logger naming: `<scope>/<subject>`). */
 export declare const WORKFLOW_LEDGER_LOGGER = "mstar/workflow-ledger";
 /**
- * The durable watermark file name under `{HARNESS_DIR}` (qc2 W-1 / qc3
+ * The durable watermark file name under the WORKFLOW dir (qc2 W-1 / qc3
  * F-301 fix-wave): `{ "v": 1, "cursors": { "<sessionId>": <nextSeq> } }` —
  * the next expected envelope seq per session id. Written atomically
  * (temp-file + rename) after every recorded workflow row; read lazily per
- * harness dir (module-level cache). Absent on first run (silent); a
- * present-but-corrupt file degrades to in-memory-only with one warn.
+ * workflow dir (module-level cache). v3 layout: the sidecar lives in the
+ * ACTIVE workflow dir (`workflows/<id>/workflow-ledger-cursors.json`) next
+ * to the ledger — the root cursor file is NOT read after migration (no read
+ * fallback). Absent on first run (silent); a present-but-corrupt file
+ * degrades to in-memory-only with one warn.
  */
 export declare const WORKFLOW_LEDGER_WATERMARK_FILE = "workflow-ledger-cursors.json";
 /**
@@ -107,6 +125,15 @@ export declare const WORKFLOW_LEDGER_WATERMARK_FILE = "workflow-ledger-cursors.j
  * evicted session re-records its rows; bounded by the cap).
  */
 export declare const WORKFLOW_LEDGER_WATERMARK_MAX_SESSIONS = 256;
+/**
+ * Workflow-dir count cap for the module-level watermark cache (qc3 S-4
+ * fix-wave): a long-lived process can touch many workflow ids over its
+ * lifetime (each iteration lifecycle creates a new workflow dir) — the
+ * cache evicts the OLDEST cached dir when it exceeds this cap. The file is
+ * the durable store; the cache is only a mirror, so an evicted dir is
+ * re-read (and re-cached) on its next visit — no correctness impact.
+ */
+export declare const WORKFLOW_LEDGER_WATERMARK_MAX_DIRS = 64;
 /** Consumer log levels the module sink understands. */
 export type WorkflowLedgerLogLevel = 'debug' | 'warn';
 /** Module-level consumer log sink — bound by `apply` to `ctx.logger(WORKFLOW_LEDGER_LOGGER)` (agent-flow ledger precedent). */
@@ -117,6 +144,49 @@ export type WorkflowLedgerLogSink = (level: WorkflowLedgerLogLevel, message: str
  * can restore it (test pattern: agent-flow `setAgentFlowLogger`).
  */
 export declare function setWorkflowLedgerLogger(sink: WorkflowLedgerLogSink): WorkflowLedgerLogSink;
+/** The number of workflow dirs currently mirrored in the module-level watermark cache (qc3 S-4 observability). */
+export declare function workflowLedgerWatermarkCacheSize(): number;
+/**
+ * Advance one session's watermark entry to `nextSeq` and persist. Runs the
+ * whole read-modify-write under the per-workflow inter-process lock
+ * (qc3 W-1 fix-wave — same lock as the ledger append): the fresh load
+ * starts from the latest durable cursors, so two processes sharing one
+ * lifecycle never clobber each other's advances; the session entry is
+ * monotonic (`Math.max` — a stale concurrent advance never regresses an
+ * already-higher cursor). When a NEW session would push the map past the
+ * cap, evict first: prefer an entry whose session is no longer live
+ * (`isEvictable` — a live session's cursor must never be dropped, or the
+ * next re-apply would re-record its rows); fall back to the oldest entry
+ * when every entry is live. The residual of eviction (a later restore of an
+ * evicted session re-records) is bounded by the cap and documented in the
+ * README.
+ *
+ * DEGRADED PATH (qc3 S-6 fix-wave): a lock timeout (another writer stuck
+ * for the full timeout — a crashed/stuck peer), a reentrancy error, or a
+ * throwing critical section leaves the durable file untouched, but the
+ * in-memory mirror is STILL advanced (the same monotonic `Math.max`;
+ * eviction skipped — the cap bounds the durable sidecar only), so
+ * re-applies in THIS process stay deduped. The durable file lags: the next
+ * successful locked advance re-reads it fresh and catches up; a restart
+ * reloads the stale file and re-records the outage rows ONCE (the accepted
+ * bounded-duplicate mode — the ledger row above was already appended). One
+ * warn names the actual state (durable cursor NOT advanced).
+ *
+ * Exported as the degraded-path test seam: {@link withWorkflowDirLock}'s
+ * `lockOpts` (`timeoutMs`) lets a test shorten the otherwise-30 s wait —
+ * the consumer itself cannot reach the catch (the ledger append takes the
+ * SAME lock and would fail first), so the post-append window is driven
+ * directly.
+ *
+ * @param isEvictable - `true` for a candidate session that is safe to evict
+ *   (not live in the sessions store).
+ * @param lockOpts - pass-through to {@link withWorkflowDirLock}
+ *   (`timeoutMs` / `pollMs` overrides; production callers never set them).
+ */
+export declare function advanceWatermark(workflowDir: string, sid: string, nextSeq: number, isEvictable: (candidate: string) => boolean, lockOpts?: {
+    timeoutMs?: number;
+    pollMs?: number;
+}): void;
 /**
  * Register the workflow-ledger consumer: (1) a `session/created` backfill
  * listener (registered FIRST — qc3 S-305 — so no apply-time window exists
@@ -126,7 +196,8 @@ export declare function setWorkflowLedgerLogger(sink: WorkflowLedgerLogSink): Wo
  * events never hit the firehose, `firstLiveSeq`); (3) a live
  * `ctx.events.on('session/event', …)` listener filtering the four types.
  * One DURABLE watermark per session id (session-log `seq` position,
- * persisted to `{HARNESS_DIR}/workflow-ledger-cursors.json`) — re-applies
+ * persisted to `{HARNESS_DIR}/workflows/<id>/workflow-ledger-cursors.json` —
+ * the ACTIVE workflow dir, never the root) — re-applies
  * never duplicate; no other cache. The watermark advances only AFTER a
  * successful ledger append (qc3 R-401 — a failing append leaves the cursor
  * behind so the row is re-attempted at the next scan, never lost). Every

package/dist/gates/workflow-policy.d.ts

@@ -189,7 +189,8 @@ export type WorkflowPolicyVerdict = {
  * before returning; `markAsked` never throws. NEVER throws.
  *
  * P-b: `input.uncoveredPlanId` (the dispatch gate computes it from the
- * calling workspace's status.json — see dispatch.ts `writableFanOutUncovered`)
+ * ACTIVE workflow snapshot — `workflows/<id>/snapshot.json`, the v3
+ * status.json consumer; see dispatch.ts `writableFanOutUncovered`)
  * → hard denies (reason cites the plan id), warn/ask emit the advisory
  * verdict; `off` always allows. Preempts P-a/P-c: an orphan InProgress plan
  * is a workspace red line independent of the workflow name.

package/dist/gates/workflow-selection.d.ts

@@ -0,0 +1,31 @@
+import type { WorkflowSelectionView } from '../types.ts';
+/** The active-set resolver result: the first active lifecycle or a clear error. */
+export type ActiveWorkflowSelection = WorkflowSelectionView;
+/**
+ * Resolve the ACTIVE lifecycle set (root v2 `status.json` `workflows[]` —
+ * the list holds non-terminal lifecycles only, removal-at-terminal). This
+ * is the ONLY resolver the agent-flow writer / ledger may use: no active
+ * entry → a clear error, never a terminal snapshot and never the root v1
+ * file.
+ *
+ * Active-set definition (explicit decision, plan `20260819-workflow-dsh-viz`
+ * Task 2): membership in `workflows[]` — the engine lifecycle enum's
+ * non-terminal states are `running` AND `paused` (terminal lifecycles are
+ * removed from the list at terminal). A PAUSED lifecycle therefore stays in
+ * the active set and the agent-flow writer / ledger append to its workflow
+ * dir (a paused lifecycle is still the operator's current lifecycle — its
+ * ledger must keep recording; only a TERMINAL lifecycle is never a write
+ * target).
+ * @param harnessDir - the resolved `{HARNESS_DIR}`.
+ */
+export declare function resolveActiveWorkflow(harnessDir: string): ActiveWorkflowSelection;
+/**
+ * Resolve the workflow the catalog/panel READ path aggregates (compass
+ * v3.0.0 § Catalog selection rule): active `workflows[]` first (multiple
+ * active → first + a structured warning), else the latest terminal
+ * snapshot by mtime (history view), else a clear error. Never reads the
+ * root v1 `plans[]` / root `agent-flow.jsonl` as primary or as a quiet
+ * fallback.
+ * @param harnessDir - the resolved `{HARNESS_DIR}`.
+ */
+export declare function resolveReadWorkflow(harnessDir: string): WorkflowSelectionView;

package/dist/index.d.ts

@@ -16,7 +16,7 @@ import { DshHostAdapter } from './gates/adapter.ts';
 import type { DispatchGateAdvisory } from './gates/dispatch.ts';
 export { DshMstar } from './service.ts';
 export type { DshMstarOptions } from './service.ts';
-export type { MstarEngineStatusSource, MstarHarnessState, MstarIterationGateView, AgentFlowEventView, AgentFlowSummaryRow, AgentFlowView, } from './types.ts';
+export type { MstarEngineStatusSource, MstarHarnessState, MstarIterationGateView, AgentFlowEventView, AgentFlowSummaryRow, AgentFlowView, WorkflowSelectionView, } from './types.ts';
 export { AGENT_FLOW_FILE, AGENT_FLOW_MAX_EVENTS, SETTLE_SEAM, readAgentFlow, recordDispatch, recordSettle, recordWorkflowVerdict, } from './gates/agent-flow.ts';
 export type { AgentFlowEvent, DispatchVerdict, SettleOutcome, WorkflowGateMode, WorkflowVerdict, WorkflowVerdictInput, } from './gates/agent-flow.ts';
 export { Config, HarnessResolver, skillLocalConfig } from './gates/_shared.ts';