@mstar-harness/dsh 3.6.3 → 3.7.1

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

@@ -1,7 +1,5 @@
 /**
- * Workflow-ledger session-event consumer (plan `20260815-dsh-workflow-ledger`
- * Task 3 — the W-B2 producer half).
- *
+ * Workflow-ledger session-event consumer. *
  * Source of record: the durable `tool-workflow/*` session events appended
  * into the CALLING PARENT session's log (top-level runs only — nested
  * transport calls record nothing upstream; Task 1 seam notes §4). The
@@ -19,9 +17,8 @@
  *     forked conversation — `session/created` fires after the seed enters
  *     the log, upstream `session/src/index.ts:961-995`) gets its snapshot
  *     cold-scanned ONCE on the creation announcement, closing the
- *     late-seeded-session gap (qc3 S-304 / qc2 W-1a).
- *
- * DEDUPE (qc2 W-1 / qc3 F-301 fix-wave): ONE DURABLE per-session watermark —
+ *     late-seeded-session gap. *
+ * DEDUPE : ONE DURABLE per-session watermark —
  * the next expected envelope `seq` (session-log position) — persisted to
  * `{HARNESS_DIR}/workflows/<id>/workflow-ledger-cursors.json` (a small
  * bounded sidecar next to the workflow-dir `agent-flow.jsonl`, written
@@ -31,17 +28,16 @@
  * 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
+ * watermark advances only AFTER the ledger row appended successfully (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
+ * advanced (in-process dedupe —) 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
+ * INTER-PROCESS SERIALIZATION : 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
@@ -52,16 +48,15 @@
  * 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`
+ * Mapping: `tool-workflow/run-start` → `workflow-run`
  * (`agent` = the carrying parent session id), `tool-workflow/agent-start` →
  * `workflow-agent` (`childId` preserved), `tool-workflow/run-end` →
  * `workflow-run-end`. `tool-workflow/agent-end` is upstream MEMBER
- * bookkeeping with no ledger kind (Task 2 handoff + plan Interfaces — the
+ * bookkeeping with no ledger kind (the
  * member `outcome` is intentionally not persisted) and is filtered out.
  * `ts` takes the envelope's `time`.
  *
- * P-c answer observation (plan `20260815-dsh-workflow-gate` Task 4 fold-in —
- * the Task-2 Important handoff): the workflow GATE cannot observe the ask
+ * P-c answer observation : the workflow GATE cannot observe the ask
  * outcome — the tool registry's `serviceAsk` consumes the approval result
  * internally, and the gate invents no answerer. The run-start observation
  * IS the answer seam: when the approval waterfall ALLOWS a workflow call,
@@ -69,7 +64,7 @@
  * (name carried) lands in the parent session log — the consumer maps it to
  * the `workflow-run` row AND records `allow` for the run name into the
  * apply-scoped {@link WorkflowAskCache} (`registerWorkflowLedger`'s third
- * parameter — the host adapter's instance). W-1 (qc2 fix-wave): the record
+ * parameter — the host adapter's instance). the record
  * fires ONLY for names the policy marked asked in this apply
  * (`WorkflowAskCache.markAsked` on every ask verdict; the observation
  * promotes via `wasAsked`) — a run observed without a prior ask (P-b
@@ -107,8 +102,8 @@ 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 the WORKFLOW dir (qc2 W-1 / qc3
- * F-301 fix-wave): `{ "v": 1, "cursors": { "<sessionId>": <nextSeq> } }` —
+ * The durable watermark file name under the WORKFLOW dir (/ qc3
+ * F-301 : `{ "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
  * workflow dir (module-level cache). v3 layout: the sidecar lives in the
@@ -126,8 +121,7 @@ export declare const WORKFLOW_LEDGER_WATERMARK_FILE = "workflow-ledger-cursors.j
  */
 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
+ * Workflow-dir count cap for the module-level watermark cache: 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
@@ -144,12 +138,11 @@ 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;
+/** The number of workflow dirs currently mirrored in the module-level watermark cache */ 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
+ * (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
@@ -161,7 +154,7 @@ export declare function workflowLedgerWatermarkCacheSize(): number;
  * 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
+ * DEGRADED PATH : 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`;
@@ -189,7 +182,7 @@ export declare function advanceWatermark(workflowDir: string, sid: string, nextS
 }): void;
 /**
  * Register the workflow-ledger consumer: (1) a `session/created` backfill
- * listener (registered FIRST — qc3 S-305 — so no apply-time window exists
+ * listener (registered FIRST — — so no apply-time window exists
  * between the snapshot and the attach); (2) a bounded cold scan over
  * `ctx.sessions.list()` reading each session's `events` snapshot for
  * `tool-workflow/*` rows (covers pre-restart runs — constructor-seeded
@@ -199,10 +192,10 @@ export declare function advanceWatermark(workflowDir: string, sid: string, nextS
  * 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
+ * successful ledger append (a failing append leaves the cursor
  * behind so the row is re-attempted at the next scan, never lost). Every
  * read/append is try/catch-contained — including `sessions.list()` itself
- * (qc2 S-7: one warn, the cold scan skipped, the consumer stays live); the
+ * (one warn, the cold scan skipped, the consumer stays live); the
  * `sessions` service absent → one debug log + consumer disabled (composition
  * without dsh-session). All appends go through `recordWorkflowEvent` (itself
  * fully contained — a failing ledger write never crashes or alters a
@@ -212,7 +205,7 @@ export declare function advanceWatermark(workflowDir: string, sid: string, nextS
  * @param resolver - the shared per-workspace `{HARNESS_DIR}` resolver
  *   (harnessDir attribution from the carrying session's `header.cwd`).
  * @param workflowAskCache - the apply-scoped P-c ask cache (plan
- *   `20260815-dsh-workflow-gate` Task 4 fold-in — the host adapter's
+ *     Task 4 fold-in — the host adapter's
  *   instance; see the module doc "P-c answer observation"). Absent → the
  *   observation hook is disabled (W-B2 tests / compositions without the
  *   workflow gate).

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

@@ -1,10 +1,9 @@
 /**
  * Workflow/ralph gate policy — the P-a name allowlist + P-b lease
- * attribution + P-c first-seen ask (plan `20260815-dsh-workflow-gate`
- * Tasks 2–3, W-B3). The policy is the SINGLE
+ * attribution + P-c first-seen ask . The policy is the SINGLE
  * decision point for the four-tier `workflowGate` mode semantics
  * (`off | warn | ask | hard`, default `warn`): it turns one composed
- * {@link WorkflowGateInput} (Task 1) into `allow | warn | ask | deny` + a
+ * {@link WorkflowGateInput}  into `allow | warn | ask | deny` + a
  * reason. The dispatch-gate listener maps the verdict to the
  * `tools/pre-execute` refusal vocabulary (`PreToolDecision`) — this module
  * NEVER throws and NEVER builds an approval path: an `ask` verdict flows
@@ -21,7 +20,7 @@
  * | ralph (no `meta.name`), covered/read-only | any | allow — P-a/P-c NEVER apply to ralph (no allowlist identity); P-b applies |
  * | workflow, name ∈ `workflowNames` (non-empty list), covered | any | allow — the allowlist passes under every mode |
  * | workflow, unknown (empty/absent list ⇒ EVERY name unknown), covered | `off` | allow — the gate short-circuits `off` before the policy; kept here for a total policy |
- * | workflow, unknown, covered | `warn` | warn — advisory + one warn (Task 1 behavior, now centralized) |
+ * | workflow, unknown, covered | `warn` | warn — advisory + one warn (centralized) |
  * | workflow, unknown, covered | `hard` | deny — reason names the workflow name, veto before any child starts |
  * | workflow, unknown, covered, first-seen (no cached decision) | `ask` | ask — `{kind:'ask'}` through the approval waterfall + the name is marked asked (W-1 — the run-start observation promotes only asked names to allow) |
  * | workflow, unknown, covered, cached allow | `ask` | allow — cached decision, NO re-ask |
@@ -34,8 +33,7 @@
  * and a fresh apply starts with an empty cache. The cache records only
  * RESOLVED decisions (`allow` | `deny`) keyed by workflow name.
  *
- * Cache-key normalization (Task 5 fold-in — the Task-4 Important congruence
- * fix): every key — the gate's `metaName` (composed through
+ * Cache-key normalization (the congruence fix): every key — the gate's `metaName` (composed through
  * {@link normalizeWorkflowName} in dispatch.ts `workflowGateInputOf`), the
  * run-start observation's `runName` (workflow-ledger.ts), and the explicit
  * `record()` / `markAsked()` APIs (which normalize internally, F-302) — is
@@ -50,15 +48,14 @@
  * `serviceAsk` consumes the approval result internally (`deepseek-harness
  * packages/core/tools/src/index.ts`, `prepareExecution`/`serviceAsk`) — so
  * the ANSWER reaches the cache through the workflow-ledger consumer's
- * run-start observation (plan `20260815-dsh-workflow-gate` Task 4 fold-in —
- * the Task-2 Important handoff): an ALLOWED ask executes the call, the
+ * run-start observation : an ALLOWED ask executes the call, the
  * durable `tool-workflow/run-start` session event carries the run name, and
  * the consumer records `allow` for it (`workflow-ledger.ts`). The policy
  * marks every name that received an `ask` verdict in this apply
  * (`markAsked`, at the single ask point), and the observation promotes ONLY
  * marked names to `allow` — a run observed WITHOUT a prior ask (a P-b
  * advisory under `ask` mode, a `warn`/`off`-mode run) is NOT an approval
- * resolution and never pre-authorizes the name (qc2 W-1). A DENIED answer
+ * resolution and never pre-authorizes the name . A DENIED answer
  * produces no run → no observation → the next same-name call re-asks
  * (fail-closed — no grant evidence, never an invented allow). The explicit
  * `record()` API stays the general seam — an answerer integration or the
@@ -69,7 +66,7 @@
  * (`WorkflowGateInput` — erased at runtime, no cycle); dispatch.ts imports
  * the policy/cache values from here. The P-a vocabulary
  * (`workflowNameUnknown`, `WORKFLOW_NAME_UNKNOWN_CODE`) centralized HERE from
- * Task 1's dispatch.ts.
+ * 's dispatch.ts.
  */
 import type { Config } from './_shared.ts';
 import type { WorkflowGateInput } from './dispatch.ts';
@@ -81,16 +78,15 @@ import type { WorkflowGateInput } from './dispatch.ts';
 export declare const WORKFLOW_NAME_UNKNOWN_CODE = "workflow.name.unknown";
 /**
  * The workflow-gate advisory/deny violation code for P-b lease attribution
- * (Task 3): the calling workspace has an `InProgress` plan without
+ * : the calling workspace has an `InProgress` plan without
  * `execution_lease` coverage (warn-mode advisory / hard-mode veto reason —
  * the reason cites the uncovered plan id).
  */
 export declare const WORKFLOW_LEASE_UNCOVERED_CODE = "workflow.lease.uncovered";
 /**
  * Strip ASCII control characters (newlines / tabs / CR — the log-forging
- * surface, qc2 S-1) from one workflow name. THE shared P-c cache-key
- * normalization (plan `20260815-dsh-workflow-gate` Task 5 fold-in — the
- * Task-4 Important congruence fix): the gate's `metaName` (composed in
+ * surface( from one workflow name. THE shared P-c cache-key
+ * normalization : the gate's `metaName` (composed in
  * dispatch.ts `workflowGateInputOf`) and the run-start observation's
  * `runName` (workflow-ledger.ts) MUST key the ask cache through the SAME
  * function — a raw-vs-stripped mismatch (e.g. `au\u0000dit` gating under
@@ -108,7 +104,7 @@ export declare function normalizeWorkflowName(value: string): string;
  * `meta.name` — P-a never applies to them (callers guard on
  * `input.metaName !== undefined` first).
  *
- * Comparison boundary (qc1-S2): entries are normalized through
+ * Comparison boundary: entries are normalized through
  * {@link normalizeWorkflowName} BEFORE the comparison — the gate's
  * `metaName` is already stripped, so an operator-pasted control-char
  * variant (trailing newline, copied config value) matches the same
@@ -124,7 +120,7 @@ export type WorkflowAskCacheDecision = 'allow' | 'deny';
  * see the module doc for the lifecycle). Records ONLY resolved decisions; a
  * miss means first-seen (or an unanswered ask) → the policy asks again.
  *
- * W-1 (qc2 fix-wave): the cache ALSO tracks which names received an `ask`
+ * The cache ALSO tracks which names received an `ask`
  * verdict in this apply ({@link markAsked} — the gate marks EVERY ask
  * decision at the policy's single ask point). The run-start observation
  * (workflow-ledger.ts) records `allow` ONLY for names marked-asked — a run
@@ -132,7 +128,7 @@ export type WorkflowAskCacheDecision = 'allow' | 'deny';
  * `warn`/`off`-mode run) is NOT an approval resolution and must not
  * pre-authorize the name.
  *
- * F-302 (qc3 fix-wave): the WRITE seams ({@link record} / {@link markAsked})
+ * The WRITE seams ({@link record} / {@link markAsked})
  * normalize their keys internally — the "ONE shared normalization" contract
  * holds even for a caller that passes a raw spelling (today's production
  * callers already normalize before calling; this is defense-in-depth for the
@@ -163,7 +159,7 @@ export declare class WorkflowAskCache {
     /** Whether `name` received an `ask` verdict in this apply (the observation's promote gate). Normalizes internally. */
     wasAsked(name: string): boolean;
 }
-/** The four-tier policy decision vocabulary (plan W-B3, Task 2). */
+/** The four-tier policy decision vocabulary (plan W-B3). */
 export type WorkflowPolicyDecision = 'allow' | 'warn' | 'ask' | 'deny';
 /**
  * One policy verdict: the decision + a human-readable reason + the violation
@@ -181,7 +177,7 @@ export type WorkflowPolicyVerdict = {
 };
 /**
  * The workflow/ralph gate policy — P-a name allowlist + P-c first-seen ask
- * (plan `20260815-dsh-workflow-gate` Task 2). `config` + cache + composed
+ * . `config` + cache + composed
  * input → verdict; the caller (dispatch gate) maps the verdict to the
  * `PreToolDecision` refusal vocabulary and owns the advisory emit/log
  * infrastructure. The ONE cache write is contained: an `ask` verdict marks

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

@@ -2,7 +2,7 @@ import type { WorkflowSelectionView } from '../types.ts';
 /** The active-set resolver result: the first active lifecycle or a clear error. */
 export type ActiveWorkflowSelection = WorkflowSelectionView;
 /**
- * Test-only observability hook (plan 20260822-gate-fixes Task 3 / f12):
+ * Test-only observability hook :
  * whether a snapshot path is still cached. Production code never calls
  * this — the eviction contract (delete → key gone) is asserted by the
  * workflow-selection spec.
@@ -15,8 +15,8 @@ export declare function _terminalStatusCacheHas(snapshotPath: string): boolean;
  * 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
+ * Active-set definition (explicit decision,
+ * 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

package/dist/index.d.ts

@@ -29,7 +29,7 @@ export type { DispatchGateAdvisory } from './gates/dispatch.ts';
 export { ROLE_PERSONA_LOGGER, registerRolePersonaChannel, setRolePersonaAgentsDir, setRolePersonaLogger, } from './gates/role-persona.ts';
 export type { RolePersonaLogLevel, RolePersonaLogSink, SubagentStartRequestView, SubagentsServiceView } from './gates/role-persona.ts';
 export { ADVISORY_LOGGER, runFallbacksAdvisory, setAdvisoryLogger } from './gates/fallbacks-advisory.ts';
-export type { AdvisoryLogLevel, AdvisoryLogSink } from './gates/fallbacks-advisory.ts';
+export type { AdvisoryLogLevel, AdvisoryLogSink, AdvisoryPassReport } from './gates/fallbacks-advisory.ts';
 export { DshHostAdapter } from './gates/adapter.ts';
 export type { DshHostAdapterOptions } from './gates/adapter.ts';
 /** Cordis function-plugin name registered by the Loader. */