@mstar-harness/dsh 2.2.0 → 2.4.0

package/dist/gates/fallbacks-seeds.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Zero-config seed declaration for the OPTIONAL `dsh-llm-fallbacks` plugin
+ * (plan `20260816-dsh-b4-seeds` Task 2): when the `llm-fallbacks` service is
+ * applied, this module declares the 13 `mode: subagent` mstar roles into the
+ * fallbacks seed registry — persona = mirror `description` (verbatim, the
+ * SSOT stays `mstar-roles`) + one mandatory-load guide line.
+ *
+ * Batch assembly (per-apply, re-runnable):
+ *
+ * 1. `getEffectiveRoles()` readback → the currently-seeded NON-mstar ids are
+ *    merge-preserved (`{ id: row.id.trim(), persona: row.seedPersona }` —
+ *    seedPersona, NOT the row persona, so an operator override stays flagged
+ *    `personaOverridden` upstream). Upstream `declare` REPLACES the whole
+ *    registry, so without preservation a mstar-only batch would strip
+ *    preset/companion ids of their seeded annotations (rows remain — R2).
+ * 2. `subagentRoleIds()` × `personaFor()` resolve the mstar personas from
+ *    the `harness-agents/` mirror (the decoration's existing lookup surface;
+ *    `mode: primary` shells like `project-manager` are excluded).
+ * 3. Interpolation gate (HARD): any persona carrying the dsh system-prompt
+ *    STRICT `{{...}}` hazard is skipped + warned BEFORE `declareSeeds` —
+ *    never declared, never throws (aligned with `agent-personas.ts`
+ *    extraction semantics; a mirror default is already rejected at
+ *    extraction, so the gate's live path is the UNFILTERED readback data
+ *    of a preserved row).
+ *
+ * The upstream `SeedDeclareOutcome` is passed through verbatim; the
+ * structured `SeedOutcomeView` is this module's own view (the service is a
+ * structural parameter — fake-testable, no runtime value import; the type
+ * imports are type-only, mirroring `fallbacks-probe.ts` — the bundle keeps
+ * ZERO runtime references to `dsh-llm-fallbacks`).
+ *
+ * Failure semantics: a throwing readback is contained (skip + one warn —
+ * probe semantics); a rejecting `declareSeeds` PROPAGATES to the caller —
+ * the entry wiring attaches a terminal `.catch` (the upstream preset
+ * self-declare pattern), so declare never throws out of `apply`.
+ *
+ * Module boundary: no barrel — the entry imports this module by explicit
+ * relative path; the entry does not re-export it.
+ */
+import type { EffectiveRolesReadback, SeedDeclaration, SeedDeclareOutcome } from 'dsh-llm-fallbacks';
+/** Logger label for the mstar seeds declaration (dsh logger naming: `<scope>/<subject>`). */
+export declare const SEEDS_LOGGER = "mstar/fallbacks-seeds";
+/** Seed-declaration log levels the module sink understands. */
+export type SeedsLogLevel = 'debug' | 'warn' | 'error';
+/** Per-call log sink — the entry binds it to `ctx.logger(SEEDS_LOGGER)`; tests pass a capture sink. */
+export type SeedsLogSink = (level: SeedsLogLevel, message: string) => void;
+/**
+ * The consumed service surface — a structural subset of the upstream
+ * `FallbacksService` (the two seed methods the declaration flow uses).
+ * Fake-testable: tests pass a spy object; the real service is assignable
+ * (structural typing anchors the contract against the installed `.d.ts`).
+ */
+export interface SeedsServiceView {
+    /** (a) Declare the companion's FULL current seed set (replacement semantics). */
+    declareSeeds(seeds: readonly SeedDeclaration[]): Promise<SeedDeclareOutcome>;
+    /** (b) Sync readback — effective taxonomy with seed annotations. */
+    getEffectiveRoles(): EffectiveRolesReadback;
+}
+/** Options for {@link declareMstarSeeds}. */
+export interface DeclareMstarSeedsOptions {
+    /** The `harness-agents/` mirror root; absent → no mstar personas (preserved-only batch). */
+    agentsDir: string | undefined;
+    /** The module log sink (entry binds `ctx.logger(SEEDS_LOGGER)`). */
+    log: SeedsLogSink;
+}
+/** One locally-skipped id with its gate reason (never reached `declareSeeds`). */
+export interface SeedSkipView {
+    id: string;
+    reason: 'interpolation' | 'no-persona';
+}
+/** One merge-preserved seeded non-mstar id (batch persona = upstream `seedPersona`). */
+export interface PreservedSeedView {
+    id: string;
+    persona: string;
+}
+/** Structured result of one {@link declareMstarSeeds} call — this module's own view. */
+export interface SeedOutcomeView {
+    /** The full declaration batch handed to `declareSeeds` (mstar personas + preserved ids). */
+    declared: SeedDeclaration[];
+    /** Locally skipped ids (interpolation gate / no usable default) — never declared. */
+    skipped: SeedSkipView[];
+    /** The seeded non-mstar ids preserved from the readback into the batch. */
+    preserved: PreservedSeedView[];
+    /** The upstream `SeedDeclareOutcome` — passed through verbatim. */
+    outcome: SeedDeclareOutcome;
+}
+/**
+ * Declare the mstar subagent seeds: readback → merge-preserve seeded
+ * non-mstar ids → resolve mirror personas → interpolation gate → declare.
+ * Idempotent by construction (the same inputs produce the same batch; the
+ * upstream manager's no-delta check skips the settings write).
+ *
+ * @param service - the structural seed surface (real service or test fake).
+ * @param options - mirror root + log sink.
+ * @returns the structured outcome view; rejects only when `declareSeeds`
+ *   itself rejects (the wiring attaches the terminal catch).
+ */
+export declare function declareMstarSeeds(service: SeedsServiceView, options: DeclareMstarSeedsOptions): Promise<SeedOutcomeView>;

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

@@ -0,0 +1,151 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { Config, HarnessResolver } from './_shared.ts';
+/** Logger label for the goal bridge (dsh logger naming: `<scope>/<subject>`). */
+export declare const GOAL_BRIDGE_LOGGER = "mstar/goal-bridge";
+/**
+ * Flat `maxGoalRounds` config fallback (architect decision — plan
+ * `20260816-dsh-nb2-goal-bridge`): 256, aligned with the GoalService default
+ * (`goal/src/index.ts:187`) and ralph `maxRounds` (`tool-ralph/src/index.ts:37`).
+ */
+export declare const DEFAULT_MAX_GOAL_ROUNDS = 256;
+/** Consumer log levels the module sink understands. */
+export type GoalBridgeLogLevel = 'debug' | 'warn';
+/** Module-level consumer log sink — bound by `apply` to `ctx.logger(GOAL_BRIDGE_LOGGER)` (agent-flow ledger precedent). */
+export type GoalBridgeLogSink = (level: GoalBridgeLogLevel, message: string) => void;
+/**
+ * Bind the goal-bridge log sink (the entry `apply` binds it to
+ * `ctx.logger(GOAL_BRIDGE_LOGGER)`). Returns the PRIOR sink so a caller can
+ * restore it (test pattern: agent-flow `setAgentFlowLogger`).
+ */
+export declare function setGoalBridgeLogger(sink: GoalBridgeLogSink): GoalBridgeLogSink;
+/**
+ * Root-agent discriminator (T1-verified; shared with the planMode bridge via
+ * explicit no-barrel import): `header.parentSession === undefined` ⇒
+ * root-like. Conversation forks also carry `parentSession` (seed lineage) →
+ * conservatively excluded from the goal mirror (accepted boundary).
+ */
+export declare function isRootLikeAgent(agent: unknown): boolean;
+/** CAS identity for one exact goal revision (upstream `GoalRef`). */
+export interface GoalRefView {
+    readonly id: string;
+    readonly revision: number;
+}
+/** The one goal surface the bridge reads (`GoalSnapshot` fields used by the mirror). */
+export interface GoalView extends GoalRefView {
+    readonly objective: string;
+    readonly phase: string;
+    readonly maxGoalRounds: number;
+}
+/**
+ * Minimal structural view of the goals service the bridge consumes
+ * (`@deepseek-ai/dsh-goal` `GoalService` — every method is agent-scoped;
+ * the runtime read is `ctx.get('goals')` without the inject requirement,
+ * same pattern as the probe's service view). `create` throws
+ * `GOAL_ALREADY_EXISTS` on a live non-complete goal and REPLACES a
+ * completed one ("A completed goal may be replaced" — `goal/src/
+ * index.ts:244-257`); `complete` is a CAS by `{ id, revision }`
+ * (`GOAL_STALE_REVISION` on stale). The drift path uses complete+create
+ * (never `edit`) so each new iteration gets a FRESH goal with a clean
+ * round budget (plan QC fix wave — qc2 W-1 / qc3 F-001/F-008).
+ */
+export interface GoalsServiceView {
+    get(agent: unknown): GoalView | undefined;
+    create(agent: unknown, request: {
+        objective: string;
+        maxGoalRounds?: number;
+    }): unknown;
+    complete(agent: unknown, ref: GoalRefView): unknown;
+}
+/** The `agents` service surface the `subagent/start` root walk reads. */
+interface AgentsView {
+    get(id: string): unknown;
+}
+/**
+ * The mirrored goal objective: the COMPLETE iteration flow with the exit
+ * definition (mstar-host `/goal` rule — advancing an iteration means the
+ * entire flow, never a sub-stage). Session-level text only — `status.json`
+ * stays the harness SSOT.
+ */
+export declare function iterationGoalObjective(iterationId: string): string;
+/**
+ * Locate the steering iteration compass (mirror of the engine's
+ * `resolveCompassEnforcement` scan + the catalog's `steeringCompassPath`):
+ * the FIRST `{ITERATION_DIR}/<id>/delivery-compass.md` whose frontmatter
+ * `status` is `active` or `locked` — the directory name IS the iteration id
+ * (plan-conventions `{ITERATION_DIR}/<id>/`). Completed/status-less/archived
+ * compasses do not steer. Silent on any read failure (advisory degrade).
+ * Shared with the planMode bridge via explicit no-barrel import (Task 4b —
+ * the same "is an active iteration steering" read).
+ * @param harnessDir - the resolved `{HARNESS_DIR}`.
+ */
+export declare function steeringCompass(harnessDir: string): {
+    iterationId: string;
+} | undefined;
+/** Inputs of the mirror: the structural goals view, the per-workspace resolver, and the resolved round cap. */
+export interface MirrorIterationGoalInput {
+    resolver: HarnessResolver;
+    /** The structural goals view (`ctx.get('goals')`); absent → the mirror is inert. */
+    goals?: GoalsServiceView;
+    /** The resolved `maxGoalRounds` (flat config key, absent → {@link DEFAULT_MAX_GOAL_ROUNDS}). */
+    maxGoalRounds: number;
+}
+/**
+ * Mirror the steering iteration objective into the goal of ONE agent.
+ * Root-like agent (`header.parentSession === undefined`) + active iteration
+ * (compass `status: active|locked`): `get` → absent → `create` (get-先行 —
+ * no `GOAL_ALREADY_EXISTS`); present with drifted objective → REPLACE with
+ * a fresh goal for the new iteration (see {@link replaceDriftedGoal} — a
+ * completed goal is `create`d directly, a live goal is `complete`d first;
+ * the new goal starts with a CLEAN round budget); present with the matching
+ * objective → no-op (idempotent decision-point re-evaluation). ONE stale
+ * re-read retry; a second stale failure is warned and abandoned —
+ * goal-service-side concurrency is rare.
+ *
+ * @returns `true` when the mirror is ensured for this agent (created,
+ * replaced, or already in place); `false` when not applicable or a
+ * contained failure occurred. Never throws — the caller's listener stays
+ * contained.
+ */
+export declare function mirrorIterationGoal(agent: unknown, input: MirrorIterationGoalInput): boolean;
+/**
+ * Resolve the ROOT agent of a published child via the `parentSession` walk
+ * (upstream `subagent/src/continuation.ts:819-831` precedent): in-process
+ * subagent children stamp `header.parentSession` = the parent SESSION id,
+ * which IS the parent agent id (a session per agent); the walk stops at the
+ * first root-like ancestor. `undefined` when unresolvable (fork lineage,
+ * non-in-process provider, registry gap, or a cycle) — the decision point
+ * then silently skips. Cycle guard: a `seen` set over visited session ids
+ * (the upstream `liveLineage` guard — plan QC fix wave qc2 W-2 / qc3
+ * F-003) breaks on ANY revisited id — a 1-hop self-loop, a 2+ hop cycle
+ * (A→B→A), or a longer malformed lineage — instead of spinning forever on
+ * the synchronous `subagent/start` decision-point listeners (reachable via
+ * HMR remounts, resumed/forked sessions with stale headers, or a future
+ * host change). Shared with the planMode bridge via explicit no-barrel
+ * import (Task 4b — the same `subagent/start` decision-point root walk).
+ */
+export declare function rootAgentOf(agent: unknown, agents: AgentsView): unknown | undefined;
+/**
+ * Register the goal bridge: an `agent/session-start` listener (root filter
+ * inside the mirror — root and children alike fire, `runtime-types.ts:217`)
+ * plus a decision-point re-evaluation on `subagent/start` (the existing
+ * decision point — index.ts decoration slot), resolving the delegating ROOT
+ * via the `parentSession` walk — the two mirror edges are idempotent (get +
+ * 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
+ * (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
+ * independent of it (it only needs the firehose + resolver). Every listener
+ * body is try/catch-contained.
+ *
+ * @param ctx - the plugin's registrant context (the app composition root).
+ * @param resolver - the shared per-workspace `{HARNESS_DIR}` resolver.
+ * @param config - validated plugin configuration (flat `maxGoalRounds`,
+ *   absent → {@link DEFAULT_MAX_GOAL_ROUNDS}; a non-positive / non-integer
+ *   value warns once and falls back to the default — see
+ *   {@link resolveGoalRounds}).
+ */
+export declare function registerGoalBridge(ctx: Context, resolver: HarnessResolver, config: Config): void;
+export {};

package/dist/gates/plan-mode-bridge.d.ts

@@ -0,0 +1,70 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { HarnessResolver } from './_shared.ts';
+/** Logger label for the planMode bridge (dsh logger naming: `<scope>/<subject>`). */
+export declare const PLAN_MODE_BRIDGE_LOGGER = "mstar/plan-mode-bridge";
+/** Consumer log levels the module sink understands. */
+export type PlanModeBridgeLogLevel = 'debug' | 'warn';
+/** Module-level consumer log sink — bound by `apply` to `ctx.logger(PLAN_MODE_BRIDGE_LOGGER)` (goal-bridge precedent). */
+export type PlanModeBridgeLogSink = (level: PlanModeBridgeLogLevel, message: string) => void;
+/**
+ * Bind the planMode-bridge log sink (the entry `apply` binds it to
+ * `ctx.logger(PLAN_MODE_BRIDGE_LOGGER)`). Returns the PRIOR sink so a caller
+ * can restore it (test pattern: goal-bridge `setGoalBridgeLogger`).
+ */
+export declare function setPlanModeBridgeLogger(sink: PlanModeBridgeLogSink): PlanModeBridgeLogSink;
+/**
+ * Minimal structural view of the planMode service the bridge consumes
+ * (`@deepseek-ai/dsh-plan-mode` `PlanModeController` — every method is
+ * agent-scoped; the runtime read is `ctx.get('planMode')` without the
+ * inject requirement, same pattern as the goal bridge). `set` is idempotent:
+ * `'noop'` when the target already matches (`plan-mode/src/index.ts:425-445`).
+ */
+export interface PlanModeServiceView {
+    get(agent: unknown): {
+        active?: unknown;
+        pending?: unknown;
+    } | undefined;
+    set(agent: unknown, active: boolean): unknown;
+}
+/**
+ * The planMode target for one harness: `true` iff an active iteration steers
+ * (compass `status: active|locked`) AND a Prepare window exists (≥1 plan
+ * row `Todo`). No active iteration / no Prepare window → `false` (plan mode
+ * OFF — the host default).
+ * @param harnessDir - the resolved `{HARNESS_DIR}`.
+ */
+export declare function planModeTarget(harnessDir: string): boolean;
+/** Inputs of the sync: the structural planMode view and the per-workspace resolver. */
+export interface PlanModeSyncInput {
+    resolver: HarnessResolver;
+    /** The structural planMode view (`ctx.get('planMode')`); absent → the sync is inert. */
+    planMode?: PlanModeServiceView;
+}
+/**
+ * Mirror the harness Prepare state into the planMode selection of ONE agent:
+ * root-like agent (`header.parentSession === undefined`) → resolve the
+ * workspace → compute {@link planModeTarget} → `planMode.set(agent, target)`.
+ * The service's `'noop'` return makes repeated evaluation at multiple
+ * decision points churn-free (no new `plan/mode` event when already in
+ * target). Non-root agent / unresolvable harness / missing planMode service
+ * → no set.
+ *
+ * @returns `true` when the sync ran for this agent (set called); `false`
+ * when not applicable or a contained failure occurred. Never throws — the
+ * caller's listener stays contained.
+ */
+export declare function syncPlanMode(agent: unknown, input: PlanModeSyncInput): boolean;
+/**
+ * Register the planMode bridge: an `agent/session-start` listener (root
+ * filter inside — root and children alike fire, `runtime-types.ts:217`) plus
+ * the EXISTING `subagent/start` decision point (the goal-bridge precedent),
+ * resolving the delegating ROOT via the shared `parentSession` walk — the
+ * two edges are idempotent (`'noop'` when already in target — no churn). The
+ * planMode service is an OPTIONAL seam (`ctx.get('planMode')` structural
+ * read): absent → ONE debug log + the bridge stays inert, never a boot
+ * failure. Every listener body is try/catch-contained.
+ *
+ * @param ctx - the plugin's registrant context (the app composition root).
+ * @param resolver - the shared per-workspace `{HARNESS_DIR}` resolver.
+ */
+export declare function registerPlanModeBridge(ctx: Context, resolver: HarnessResolver): void;

package/dist/gates/skill-lint.d.ts

@@ -52,9 +52,10 @@ export declare class SkillLintVetoError extends Error {
 }
 /**
  * Lint one SKILL.md document with the engine skill-authoring lints
- * (`lintFrontmatter` + `lintFiveQuestion` — the CLI `mstar skill lint`
- * combination; violation codes `lint.frontmatter.*` /
- * `skill-authoring.five-question.*`). Pure: no enforcement, no I/O.
+ * (`lintFrontmatter` + `lintFiveQuestion` + `findEphemeralCitations` — the
+ * CLI `mstar skill lint` combination plus the ephemeral-citation gate;
+ * violation codes `lint.frontmatter.*` / `skill-authoring.five-question.*`
+ * / `skill.ephemeral.*`). Pure: no enforcement, no I/O.
  * @param doc - the full SKILL.md text.
  */
 export declare function lintSkillDoc(doc: string): GateResult;

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

@@ -0,0 +1,121 @@
+/**
+ * Harness-rules system-prompt injection (plan `20260816-dsh-nb1-systemprompt`
+ * Task 2): the root session's ONE `mstar:harness-rules` pointer section plus
+ * the `mstar:engine-status` runtime-context summary, both registered on the
+ * GLOBAL prompt layer — visible to the root session AND every dispatched
+ * child — without touching the child-scoped `mstar:role-persona` section
+ * (fallbacks-decoration; distinct name, distinct layer — duplicate-name
+ * throws are per name per layer, verified `scope/src/store.ts`).
+ *
+ * Content discipline:
+ * - The section is a POINTER block (presence / enforcement word / resolved
+ *   `{HARNESS_DIR}` / one read-mstar-harness-core directive) — deliberately
+ *   minimal, never a rules dump (plan pointer-block constraint). The
+ *   OUTPUT is zero-complete-`{{...}}`-groups text: dsh system-prompt
+ *   renders section AND context text with STRICT `{{variable}}`
+ *   interpolation and throws on unknown/malformed/undefined references
+ *   (`interpolate` in `@deepseek-ai/dsh-system-prompt`), so every injected
+ *   string must carry no complete group. The mechanism is LIVE, not static
+ *   (plan QC fix wave W-1): every operator-controlled value embedded below
+ *   (harness dir, plan ids, iteration id, lease fields, direction prose)
+ *   is passed through `stripInterpolationHazard` — complete `{{…}}` groups
+ *   are screened so a hostile value can never break prompt assembly, while
+ *   a lone `{{` stays literal prose.
+ * - The harness dir is resolved PER ASSEMBLY from the assembly context's
+ *   agent (plan QC fix wave W-2 — the catalog pre-step precedent): the
+ *   session cwd of the agent whose prompt is being assembled, via
+ *   `resolver.forAgent`, with the boot value (`forWorkspace(undefined)`,
+ *   the explicit config or null) as the fallback when the assembly carries
+ *   no agent. Zero-config deployments (no explicit `harnessDir`, the
+ *   probe-discovers-`.mstar/` default) therefore resolve the pointer and
+ *   the status context to the session's own workspace instead of rendering
+ *   a permanent `none`/`soft`. The enforcement word is LIVE — the section
+ *   text is a provider (the plan:policy precedent) that re-reads
+ *   `resolveCompassEnforcement` per assembly (the same existing read the
+ *   gates and the catalog use — no new config key), so a mid-session
+ *   compass soft/hard flip lands on the next assembly without
+ *   re-registration, in zero-config and explicit-config deployments alike.
+ * - 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
+ *   (residual detail, agent-flow events, knowledge digest, branch/policy
+ *   anchors) stays out. 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).
+ *
+ * Degradation (boot is never affected — the decoration's contained-degrade
+ * discipline):
+ * - Structural existence check via `ctx.get('systemPrompt')` — the
+ *   `ctx.get('agents')` precedent: a DIRECT `ctx.systemPrompt` property
+ *   read throws "cannot get property without inject" on a started cordis
+ *   fiber when the service is not composed. Absent service → return `false`
+ *   + exactly one debug log.
+ * - Registration is deferred through `ctx.inject(['systemPrompt'], …)`
+ *   (HMR-safe re-apply): the `section()`/`context()` calls run on the
+ *   inject child, and the exact disposers they return are collected on
+ *   that child via `systemPromptCtx.effect` (plan QC fix wave W-HMR) — the
+ *   registrations therefore unwind with THIS plugin's apply by explicit
+ *   ownership, so a re-apply disposes the old registrations before
+ *   registering fresh ones (no duplicate-name throw, no stale closure from
+ *   the previous apply). A direct global registration through the service
+ *   instance without the collected disposers would instead rely on the
+ *   cordis traceable-proxy `this.ctx` rebind for ownership — implicit and
+ *   version-fragile; the explicit collection removes that dependency.
+ * - Registration errors are contained (warn + return `false`); a throwing
+ *   log sink is contained inside the log helper (never-throws invariant);
+ *   the collected disposers run inside a try/catch so an exotic disposal
+ *   throw can never break the fiber teardown.
+ *
+ * Module boundary: no barrel — the entry imports this module by explicit
+ * relative path and does NOT re-export its public names (plan constraint);
+ * tests import from this module directly.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { type HarnessResolver } from './_shared.ts';
+/** Logger label for the harness-prompt injection (dsh logger naming: `<scope>/<subject>`). */
+export declare const HARNESS_PROMPT_LOGGER = "mstar/harness-prompt";
+/** The global harness-rules pointer section name (root AND child assemblies). */
+export declare const HARNESS_RULES_SECTION_NAME = "mstar:harness-rules";
+/** Prompt order of the harness-rules section — after the deployment persona (0) and the child role persona (1), before plan:policy (50). */
+export declare const HARNESS_RULES_SECTION_ORDER = 2;
+/** The engine-status runtime-context contribution name (durable user-role snapshot). */
+export declare const ENGINE_STATUS_CONTEXT_NAME = "mstar:engine-status";
+/** Prompt order of the engine-status context — first in the runtime snapshot, before the policy sentences (110+). */
+export declare const ENGINE_STATUS_CONTEXT_ORDER = 100;
+/** Harness-prompt log levels the module sink understands. */
+export type HarnessPromptLogLevel = 'debug' | 'warn';
+/** Module-level harness-prompt log sink — bound by `apply` to `ctx.logger(HARNESS_PROMPT_LOGGER)` (decoration precedent). */
+export type HarnessPromptLogSink = (level: HarnessPromptLogLevel, message: string) => void;
+/**
+ * Bind the harness-prompt log sink (the entry `apply` binds it to
+ * `ctx.logger(HARNESS_PROMPT_LOGGER)`). Returns the PRIOR sink so a caller
+ * can restore it (test pattern: {@link setDecorationLogger}).
+ */
+export declare function setHarnessPromptLogger(sink: HarnessPromptLogSink): HarnessPromptLogSink;
+/**
+ * Register the harness-rules pointer section + the engine-status context on
+ * the GLOBAL prompt layer.
+ *
+ * @param ctx - the registrant context (the plugin's apply ctx; unscoped →
+ *   the registrations land on the global layer).
+ * @param options.resolver - the per-workspace `{HARNESS_DIR}` resolver.
+ *   The BOOT value (`forWorkspace(undefined)`, the explicit config or null)
+ *   is the fallback; the section and context providers resolve the harness
+ *   dir PER ASSEMBLY from the assembly context's agent (the session
+ *   workspace), and the section's enforcement word is re-read from the
+ *   compass per assembly — so both stay correct in zero-config deployments
+ *   and follow mid-session compass flips.
+ * @returns `true` when the service exists and registration was scheduled;
+ *   `false` when `ctx.systemPrompt` is structurally absent (one debug log,
+ *   boot unaffected) or the synchronous registration path threw (contained
+ *   warn). The actual registration runs in an inject child that settles
+ *   ASYNC — a failure there is contained to a warn and cannot be observed
+ *   through this return value (`true` only guarantees scheduling, not
+ *   landing; `apply` ignores the value, so boot is never affected). Never
+ *   throws.
+ */
+export declare function registerHarnessPrompt(ctx: Context, options: {
+    resolver: HarnessResolver;
+}): boolean;

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

@@ -0,0 +1,149 @@
+/**
+ * Workflow-ledger session-event consumer (plan `20260815-dsh-workflow-ledger`
+ * Task 3 — the W-B2 producer half).
+ *
+ * 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
+ * consumer has THREE halves (the architect-verified seam):
+ *  1. COLD SCAN at apply — iterate `ctx.get('sessions').list()`, read each
+ *     session's `events` snapshot, and record any `tool-workflow/*` rows
+ *     already present. Constructor-seeded events (replay/resume/fork) NEVER
+ *     publish on the `session/event` firehose (`firstLiveSeq`), so without
+ *     the cold scan pre-restart runs would be invisible.
+ *  2. LIVE FIREHOSE — `ctx.events.on('session/event', …)`: the post-commit
+ *     append feed, delivered to ALL sessions for a root-context listener
+ *     (scope-null event, untagged listeners admitted).
+ *  3. SESSION-CREATED BACKFILL — `ctx.events.on('session/created', …)`: a
+ *     session created AFTER apply with a constructor-seeded log (resumed /
+ *     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 —
+ * 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.
+ *
+ * Mapping (Task 2 schema): `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
+ * 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
+ * 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,
+ * the call executes and the durable `tool-workflow/run-start` session event
+ * (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
+ * 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
+ * advisory under `ask` mode, `warn`/`off`-mode runs) is not an approval
+ * resolution and never pre-authorizes the name. A DENIED answer produces no
+ * run → no observation → the next same-name call under `ask` re-asks
+ * (fail-closed — no grant evidence, never an invented allow). The hook is
+ * bounded and contained: it fires only on the FIRST successful recording of
+ * a run-start (the watermark gate above), keyed on the UNCAPPED run name
+ * (`row.runName` — it must match the gate's `meta.name`, which is never
+ * truncated AND is normalized through the SAME `normalizeWorkflowName` the
+ * gate composes with — the Task 5 congruence fold-in), and a throwing cache
+ * record degrades the observation with one warn — the ledger row is already
+ * appended, the run is never affected.
+ *
+ * Observe-only (plan Global Constraints: W3 / N5): ZERO gating — every read
+ * and append is try/catch-contained; a throwing session read logs one warn
+ * and the run is unaffected; all appends go through `recordWorkflowEvent`
+ * (itself fully contained — a failing ledger write never crashes or alters
+ * a workflow run). The `sessions` service is read STRUCTURALLY via
+ * `ctx.get('sessions')` — an absent service (composition without
+ * dsh-session) → one debug log + consumer disabled. No runtime dependency
+ * on `@deepseek-ai/dsh-session` (same pattern as the agents/loader seams).
+ * The `session/created` listener NEVER throws synchronously — upstream
+ * vetoes a session publication on a throwing creation listener.
+ *
+ * Depth advisory (P-e / N5): on `agent-start`, resolve the child session
+ * via `sessions.get(childId)` and warn when its `header.delegationDepth`
+ * is >= 2 — ONCE per run (bounded by a per-runId latch). Observe-time only,
+ * NEVER a refusal path.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { HarnessResolver } from './_shared.ts';
+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
+ * 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.
+ */
+export declare const WORKFLOW_LEDGER_WATERMARK_FILE = "workflow-ledger-cursors.json";
+/**
+ * Session-count cap for ONE watermark file (bounds the sidecar). Eviction
+ * prefers sessions that are no longer live; when every entry is live the
+ * oldest entry is dropped (documented residual — a later restore of an
+ * evicted session re-records its rows; bounded by the cap).
+ */
+export declare const WORKFLOW_LEDGER_WATERMARK_MAX_SESSIONS = 256;
+/** 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). */
+export type WorkflowLedgerLogSink = (level: WorkflowLedgerLogLevel, message: string) => void;
+/**
+ * Bind the consumer log sink (the entry `apply` binds it to
+ * `ctx.logger(WORKFLOW_LEDGER_LOGGER)`). Returns the PRIOR sink so a caller
+ * can restore it (test pattern: agent-flow `setAgentFlowLogger`).
+ */
+export declare function setWorkflowLedgerLogger(sink: WorkflowLedgerLogSink): WorkflowLedgerLogSink;
+/**
+ * Register the workflow-ledger consumer: (1) a `session/created` backfill
+ * listener (registered FIRST — qc3 S-305 — 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
+ * 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
+ * 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
+ * read/append is try/catch-contained — including `sessions.list()` itself
+ * (qc2 S-7: 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
+ * workflow run).
+ *
+ * @param ctx - the plugin's registrant context (the app composition root).
+ * @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
+ *   instance; see the module doc "P-c answer observation"). Absent → the
+ *   observation hook is disabled (W-B2 tests / compositions without the
+ *   workflow gate).
+ */
+export declare function registerWorkflowLedger(ctx: Context, resolver: HarnessResolver, workflowAskCache?: WorkflowAskCache): void;