@mstar-harness/dsh 2.2.0 → 2.3.0

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

@@ -17,6 +17,44 @@ export declare const AGENT_FLOW_DEFAULT_LIMIT = 50;
  * small-file append path free of a full read per dispatch).
  */
 export declare const AGENT_FLOW_SIZE_GATE_BYTES: number;
+/**
+ * WORKFLOW field length caps (qc2 W-3 fix-wave) — ONE constant family at
+ * the ledger boundary, enforced on BOTH the consumer (workflow-ledger
+ * `rowOf`) and the read narrow (`eventFromUnknown`): a hostile or
+ * model-controlled multi-MB string must never defeat the
+ * `AGENT_FLOW_MAX_EVENTS` line-count truncation or reach the panel
+ * unbounded. ID-sized fields (`runId`, `childId`) SKIP the row when
+ * oversized — truncating them could forge collisions; display fields
+ * (`name`, `label`, `phase`) are truncated deterministically with a suffix
+ * marker. `2^31` bounds every sequence number (envelope + member) — the
+ * cursor-math safe range (see the consumer's durable watermark).
+ */
+export declare const WORKFLOW_LEDGER_MAX_ID_LENGTH = 512;
+/** Cap for label-sized display fields (`label`, `phase`). */
+export declare const WORKFLOW_LEDGER_MAX_LABEL_LENGTH = 512;
+/** Cap for the run display `name`. */
+export declare const WORKFLOW_LEDGER_MAX_NAME_LENGTH = 1024;
+/** The deterministic suffix marker appended to capped display fields. */
+export declare const WORKFLOW_LEDGER_TRUNCATION_MARKER = "\u2026";
+/** Upper bound (exclusive) for envelope + member sequence numbers. */
+export declare const WORKFLOW_LEDGER_MAX_SEQ: number;
+/**
+ * Deterministically cap one display field: values at or under the cap pass
+ * through unchanged; longer values are truncated to `cap − marker` chars
+ * plus the {@link WORKFLOW_LEDGER_TRUNCATION_MARKER} suffix (the marker
+ * guarantees the truncation is visible in the panel — never a silent cut).
+ * CODE-POINT gated AND sliced (plan QC fix wave — qc2 S-5; PR #97 finding
+ * 2): `String.prototype.slice` operates on UTF-16 code units and can split
+ * a surrogate pair at the cap boundary (a lone surrogate renders as U+FFFD
+ * in the log line), and a UTF-16 `.length` gate would false-positive
+ * truncate astral-dense values (≤ cap code points but > cap UTF-16 units)
+ * then re-inflate the result to cap code points — up to ~2× the cap in the
+ * unit the gate measured. ONE `Array.from` drives both the gate and the
+ * slice, so the bound is measured and enforced in the same unit; a
+ * multi-byte character at the boundary is kept whole, at the cost of at
+ * most one code point of slack. Pure — NEVER throws.
+ */
+export declare function truncateLedgerField(value: string, cap: number): string;
 /** Logger label for the agent-flow ledger (dsh logger naming: `<scope>/<subject>`). */
 export declare const AGENT_FLOW_LOGGER = "mstar/agent-flow";
 /**
@@ -46,10 +84,71 @@ export declare const SETTLE_SEAM_PAIRING_NOTE = "settle seam \"tools/post-execut
 export type DispatchVerdict = 'ok' | 'advisory' | 'denied';
 /** Settle outcome vocabulary (spec §2.1.3). */
 export type SettleOutcome = 'ok' | 'error' | 'denied';
+/** Workflow run terminal reason (`tool-workflow` vocabulary — `workflow/src/types.ts:63`). */
+export type WorkflowStopReason = 'completed' | 'cancelled' | 'error';
 /**
- * One v1 ledger event (spec §2.1.3 schema — the JSONL line). Optional fields
- * are OMITTED from the serialized line when absent (Session.append's lossless
- * JSON discipline starts at the record boundary).
+ * Workflow/ralph gate verdict vocabulary (plan `20260815-dsh-workflow-gate`
+ * Task 4): the RESOLVED outcomes reuse the dispatch verdict vocabulary
+ * (`ok`/`advisory`/`denied` — the plan interface "the workflow verdict
+ * vocabulary"); `ask` is the PENDING-decision member — the first-seen ask
+ * itself is a gated call, so its row carries `ask` until the approval
+ * waterfall resolves it ("one ledger row per gated call").
+ */
+export type WorkflowVerdict = DispatchVerdict | 'ask';
+/**
+ * The workflow/ralph gate mode (Config `workflowGate` — plan
+ * `20260815-dsh-workflow-gate` Task 1), recorded on every verdict row.
+ * `off` rows never exist: the gate short-circuits `off` BEFORE the policy,
+ * so no verdict is produced.
+ */
+export type WorkflowGateMode = 'off' | 'warn' | 'ask' | 'hard';
+/**
+ * One v1 workflow ledger event (plan `20260815-dsh-workflow-ledger` Task 2 —
+ * the W-B2 schema). Produced from the durable `tool-workflow/*` session events
+ * by the Task 3 consumer (`run-start` → `workflow-run`, `agent-start` →
+ * `workflow-agent`, `run-end` → `workflow-run-end`; the upstream `agent-end`
+ * member outcome has no ledger kind). Optional fields (`agent` / `phase`) are
+ * OMITTED from the serialized line when absent (lossless-JSON discipline).
+ */
+export type AgentFlowWorkflowEvent = {
+    v: 1;
+    ts: number;
+    kind: 'workflow-run';
+    /** The workflow run's stable id (upstream `runId`). */
+    runId: string;
+    /** The run's display name (upstream `name`). */
+    name: string;
+    /** The calling session's stable id, when carried. */
+    agent?: string;
+} | {
+    v: 1;
+    ts: number;
+    kind: 'workflow-agent';
+    /** The workflow run's stable id (upstream `runId`). */
+    runId: string;
+    /** 1-based `agent()` call sequence within the run (upstream `seq`). */
+    seq: number;
+    /** The published member's display label (upstream `label`). */
+    label: string;
+    /** The member's phase, when carried (upstream `phase?`). */
+    phase?: string;
+    /** The published child session's stable id (upstream `childId`). */
+    childId: string;
+} | {
+    v: 1;
+    ts: number;
+    kind: 'workflow-run-end';
+    /** The workflow run's stable id (upstream `runId`). */
+    runId: string;
+    /** Terminal run reason (upstream `stopReason`). */
+    stopReason: WorkflowStopReason;
+};
+/**
+ * One v1 ledger event (spec §2.1.3 + plan `20260815-dsh-workflow-ledger`
+ * Task 2 — the JSONL line). Optional fields are OMITTED from the serialized
+ * line when absent (Session.append's lossless JSON discipline starts at the
+ * record boundary). The three `workflow-*` kinds are the W-B2 addition —
+ * see {@link AgentFlowWorkflowEvent}.
  */
 export type AgentFlowEvent = {
     v: 1;
@@ -90,7 +189,25 @@ export type AgentFlowEvent = {
     role?: string;
     planId?: string;
     taskId?: string;
-};
+} | {
+    v: 1;
+    ts: number;
+    kind: 'workflow-verdict';
+    /** The calling session's stable id, when carried. */
+    agent?: string;
+    /** The matched tool name (`'workflow'` | `'ralph'`). */
+    tool: 'workflow' | 'ralph';
+    /** `meta.name` for workflow calls — the P-a/P-c allowlist identity. */
+    workflow?: string;
+    /** `objective` for ralph calls — the ralph identity. */
+    objective?: string;
+    /** The effective `workflowGate` mode at decision time (never `off` — off records nothing). */
+    mode: WorkflowGateMode;
+    /** The gate verdict (ok/advisory/denied/ask). */
+    verdict: WorkflowVerdict;
+    /** The policy violation code (advisory/ask/denied rows only). */
+    code?: string;
+} | AgentFlowWorkflowEvent;
 /**
  * The identity of one recorded dispatch, carried by the pairing store so a
  * later completion (post-execute settle / onJobDone terminal) can record a
@@ -225,6 +342,71 @@ export declare function recordSettle(input: {
     planId?: string;
     taskId?: string;
 }): void;
+/**
+ * Record one workflow ledger event (plan `20260815-dsh-workflow-ledger` Task 2
+ * — the W-B2 schema). Fully try/catch-contained — NEVER throws into the
+ * session-event consumer (Task 3 wires it); a failing record logs only
+ * (`mstar/agent-flow`), so a ledger write never crashes or alters a workflow
+ * run (Global Constraint: observe-only events are never refusal channels).
+ * The event is serialized lossless — optional fields (`agent` / `phase`) are
+ * omitted when absent at the record boundary; the caller shapes the event
+ * 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.
+ * @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).
+ */
+export declare function recordWorkflowEvent(input: {
+    harnessDir: string;
+    event: AgentFlowWorkflowEvent;
+}): boolean;
+/**
+ * Input for {@link recordWorkflowVerdict} — one gated workflow/ralph call's
+ * decision identity (plan `20260815-dsh-workflow-gate` Task 4: verdict +
+ * metaName/objective + mode).
+ */
+export interface WorkflowVerdictInput {
+    /** The resolved `{HARNESS_DIR}` the row records into. */
+    harnessDir: string;
+    /** The in-flight tool call (structural read for the carrying session id). */
+    exec?: unknown;
+    /** The matched tool name (`'workflow'` | `'ralph'`). */
+    tool: 'workflow' | 'ralph';
+    /** `meta.name` for workflow calls (the P-a/P-c allowlist identity). */
+    workflow?: string;
+    /** `objective` for ralph calls (the ralph identity). */
+    objective?: string;
+    /** The effective `workflowGate` mode at decision time. */
+    mode: WorkflowGateMode;
+    /** The gate verdict. */
+    verdict: WorkflowVerdict;
+    /** The policy violation code (advisory/ask/denied rows only). */
+    code?: string;
+}
+/**
+ * Record one workflow/ralph gate verdict row (plan `20260815-dsh-workflow-gate`
+ * Task 4 — "one ledger row per gated workflow/ralph call" via the ledger
+ * plan's record path, the `workflow-verdict` kind). Fully
+ * try/catch-contained — NEVER throws into the gate (`gateWorkflow` calls
+ * this on EVERY policy decision); a failing record logs only
+ * (`mstar/agent-flow`), so a ledger write never crashes or alters a
+ * workflow call. The event is serialized lossless — optional fields
+ * (`agent` / `workflow` / `objective` / `code`) omit when absent; the
+ * display identity fields (`workflow` / `objective`) are capped at the
+ * ledger boundary (same discipline as the W-B2 name cap) and the ralph
+ * `objective` is routed through the SHARED `normalizeWorkflowName` strip at
+ * this write boundary (qc2 W-2 — control-char discipline parity with the
+ * name/label/phase fields; the gate already normalizes `workflow`). The
+ * JSONL line is line-safe either way (`JSON.stringify` escapes), but the
+ * panel view passes the objective through raw — a hostile objective
+ * (ESC/ANSI/NEL) must never reach it. Malformed input is a caller bug —
+ * the strict narrowing applies on READ (`eventFromUnknown`), never here.
+ * @param input - the gate's decision identity (see {@link WorkflowVerdictInput}).
+ */
+export declare function recordWorkflowVerdict(input: WorkflowVerdictInput): void;
 /**
  * Read the agent-flow ledger as the catalog view (spec §2.1.3 — fix-wave
  * qc1 F-001 / qc2 F-6): the latest events first (bounded by `limit`) plus

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

@@ -0,0 +1,44 @@
+/**
+ * The role-id shape the mirror lookup accepts — upstream `ROLE_ID_PATTERN`
+ * semantics (`/^[a-z0-9-]{1,32}$/`, dsh-llm-fallbacks `src/config.ts`),
+ * implemented locally (no import-shape assumptions). The role id flows from
+ * the child's Assignment header (`Execute as`) into a filesystem path, so
+ * it is constrained to this shape BEFORE any path join: no `..`, no path
+ * separators, no absolute roots, bounded length. All 14 mirror stems comply.
+ */
+export declare const ROLE_ID_PATTERN: RegExp;
+/** One resolved persona: the text and its source. */
+export interface PersonaResult {
+    text: string;
+    source: 'config' | 'default';
+}
+/** The lookup surface {@link personaFor} consumes. */
+export interface PersonaLookup {
+    /** Config-sourced persona map (`rolePersonas`) — wins over the mirror default. */
+    rolePersonas?: Record<string, string> | null;
+    /** The mirror root (`harness-agents/`); absent → mirror defaults are skipped. */
+    agentsDir?: string;
+}
+/** Warn sink for extraction-time hazards (bound by the decoration to its warn channel). */
+export type PersonaWarnSink = (message: string) => void;
+/**
+ * The decoration's single persona lookup: `rolePersonas[roleId]` → mirror
+ * default → undefined. Pure — the mirror root is passed explicitly (the
+ * decoration supplies the apply-bound packaged root; tests supply fixtures).
+ *
+ * @param roleId - the mstar role id (Assignment `Execute as`).
+ * @param lookup - the config override map and the mirror root.
+ * @param warn - optional extraction-time warn sink (hazard defaults).
+ */
+export declare function personaFor(roleId: string, lookup: PersonaLookup, warn?: PersonaWarnSink): PersonaResult | undefined;
+/**
+ * The mstar role-id set for one mirror: the file stems of the shells
+ * eligible as subagent role defaults (`mode` absent-or-`subagent` — a
+ * `primary` shell like `project-manager` is excluded), sorted for
+ * deterministic warn listings. The adoption advisory (plan
+ * `20260815-dsh-fallbacks-personas` Task 4) derives its taxonomy reference
+ * from here — never hardcoded. Reads the mirror directory + each shell's
+ * frontmatter once per call (the advisory invokes it once per apply — no
+ * cache needed). Returns `[]` for an unreadable/absent mirror directory.
+ */
+export declare function subagentRoleIds(agentsDir: string): string[];

package/dist/gates/dispatch.d.ts

@@ -8,12 +8,26 @@ import type { DshHostAdapter } from './adapter.ts';
 export declare const DISPATCH_LOGGER = "mstar/dispatch-gate";
 /**
  * Default delegation tool names the dispatch gate matches (tool-subagent
- * default id). Exported SHARED with the agent-flow settle pairing
+ * default id + its fork sibling — roadmap §9 W-B1: fork dispatches carry the
+ * same Assignment-shaped `{ description, prompt }` args and must be gated
+ * like `subagent`). Exported SHARED with the agent-flow settle pairing
  * (`registerSettleListener` matches the same tool set — plan
  * `20260811-panel-f4-timeliness` Task 1) so the default cannot drift between
  * the gate and the settle seam.
  */
-export declare const DEFAULT_DISPATCH_TOOLS: readonly ["subagent"];
+export declare const DEFAULT_DISPATCH_TOOLS: readonly ["subagent", "subagent_fork"];
+/**
+ * The fixed workflow/ralph tool names the workflow gate matches (plan
+ * `20260815-dsh-workflow-gate` — architect-verified): the workflow tool
+ * registers under Config-default name `'workflow'` and is RENAMEABLE per
+ * instance (`toolName`, `tool-workflow/src/index.ts:41`); `ralph` is a
+ * fixed name (`tool-ralph/src/index.ts:413`). A renamed instance is out
+ * of reach until its name is configured — the same documented caveat as
+ * `DEFAULT_DISPATCH_TOOLS`. The workflow tools are gated by THEIR OWN
+ * branch, never by addition to `DEFAULT_DISPATCH_TOOLS` (plan Global
+ * Constraint — that list stays `['subagent', 'subagent_fork']`).
+ */
+export declare const DEFAULT_WORKFLOW_TOOLS: readonly ["workflow", "ralph"];
 /**
  * Advisory emitted on warn-mode dispatch-gate passes (the * `mstar/status-gate` decision reused for the dispatch gate — dsh's
  * `agent/status` lifecycle event stays untouched). Consumers (later tasks,
@@ -128,6 +142,54 @@ export declare function dispatchGateCore(config: Config, harnessDir: string | nu
     violations: ValidationResult[];
     writable: boolean | undefined;
 };
+/**
+ * The workflow-gate input composed from one `workflow`/`ralph` tool call
+ * (plan `20260815-dsh-workflow-gate` Task 1 — consumed by the Task 2 P-a /
+ * P-c and Task 3 P-b policies): the tool name + the structural reads of
+ * `meta` (workflow) / `objective` (ralph) + the in-flight call.
+ */
+export interface WorkflowGateInput {
+    /** The matched tool name (`'workflow'` | `'ralph'` — the gate name-guards on {@link DEFAULT_WORKFLOW_TOOLS} first). */
+    tool: 'workflow' | 'ralph';
+    /** `meta.name` for workflow calls — the P-a allowlist input; absent for ralph (no meta). */
+    metaName?: string;
+    /** `objective` for ralph calls (objective-based ledger logging, P-b); absent for workflow. */
+    objective?: string;
+    /** The in-flight tool call — Task 3 P-b lease attribution reads the calling agent/session off it. */
+    exec: ToolExecution;
+    /**
+     * P-b lease attribution (plan Task 3): the calling workspace's first
+     * `InProgress` plan lacking `execution_lease` coverage (computed by
+     * {@link writableFanOutUncovered} from the status.json read through the
+     * contained resolver path — `preExecuteListener` already resolved the
+     * harness dir from the calling agent's session workspace). Undefined → no
+     * uncovered plan (allow axis). Applies to workflow AND ralph (P-b needs no
+     * `meta.name`).
+     */
+    uncoveredPlanId?: string;
+}
+/**
+ * Compose the {@link WorkflowGateInput} from one workflow/ralph tool call's
+ * arguments — structural reads, NEVER throws (plan
+ * `20260815-dsh-workflow-gate` Task 1; args shapes architect-verified:
+ * workflow `{ script, meta: { name, description, whenToUse?, phases? },
+ * args? }` (`tool-workflow/src/index.ts:152-161`); ralph
+ * `{ objective, maxRounds?, maxHandoffChars? }`
+ * (`tool-ralph/src/index.ts:76,416-419`)). Returns undefined for malformed
+ * args — workflow without a non-empty string `meta.name`, ralph without a
+ * string `objective` — the fail-open + one-warn path.
+ *
+ * `meta.name` is NORMALIZED through {@link normalizeWorkflowName} (control
+ * chars stripped) BEFORE the empty check — the P-c cache-key congruence
+ * fold-in (plan Task 5): the run-start observation (workflow-ledger.ts)
+ * keys the ask cache with the SAME normalized name, so a control-char name
+ * (`au\u0000dit`) asks once and observes under one key instead of re-asking
+ * forever. The length is NEVER capped here (the gate's identity axis is
+ * uncapped — the ledger ROW display field is capped separately). A name
+ * that is ONLY control characters normalizes to '' → malformed (fail-open),
+ * matching the ledger's read boundary.
+ */
+export declare function workflowGateInputOf(exec: ToolExecution): WorkflowGateInput | undefined;
 /**
  * `tools/pre-execute` listener. The waterfall refusal channel is the returned
  * decision: a deny is returned WITHOUT calling `next()` (short-circuits the

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

@@ -0,0 +1,77 @@
+/**
+ * Warn-only adoption advisory for the OPTIONAL `dsh-llm-fallbacks` plugin
+ * (plan `20260815-dsh-fallbacks-personas` Task 4 + `20260816-dsh-b4-seeds`
+ * Task 3): when the capability is mounted, ONE advisory pass per apply
+ * reports the deployment's fallbacks taxonomy state (bounded: ≤1 warn per
+ * category, logger `mstar/fallbacks-advisory`):
+ *
+ * - Service present (seeds-aware path): the decision point FIRST awaits the
+ *   idempotent re-declare (`declareMstarSeeds`) — converging the boot
+ *   dual-inject-child race window — then reads the EFFECTIVE state
+ *   (`getEffectiveRoles`, sync) and reports per mstar role id:
+ *   (i) missing row → missing warn; (ii) `seeded && !personaOverridden` →
+ *   seeded (silent, one debug); (iii) `personaOverridden` → persona-
+ *   overridden warn (ids + the revert entry: the `fallbacks/revert-seed`
+ *   gateway / settings-card rollback button). Empty-persona warns fire only
+ *   for non-seeded rows or overridden-empty rows. The declare outcome's
+ *   skips/conflicts (upstream conflict code `'persona-source'`) merge into
+ *   one warn. The legacy-keys check runs through the service's own
+ *   `detectLegacyKeys` on the row config.
+ * - Loader-fallback path (no service): the structural read is preserved
+ *   (`readRowConfig`/`readRolesList` — (b) missing ids / (c) empty personas
+ *   over the raw `roles.list`); the legacy check is SKIPPED (never
+ *   reimplemented) and no revert entry appears (no seeds surface).
+ *
+ * The mstar role-id set is derived from the `harness-agents/` mirror
+ * (`subagentRoleIds` — shell file stems filtered to `mode: subagent`),
+ * never hardcoded.
+ *
+ * Unreadable row config (absent field / non-object, or an unreadable
+ * `roles.list`) → skip + one debug log. Unmounted → the pass is not invoked
+ * (returns `false`, no logs). The advisory NEVER writes the fallbacks config
+ * — the read is read-only over the deployment's config layer (never the
+ * fallbacks plugin's module internals); the only write path is the
+ * idempotent seeds re-declare through the released seeds surface (no-delta
+ * → no settings write upstream). The advisory never throws (the caller's
+ * dispatch/apply flow is never affected).
+ *
+ * Module boundary: no barrel — the entry imports this module by explicit
+ * relative path (the decoration-module pattern).
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Logger label for the adoption advisory (dsh logger naming: `<scope>/<subject>`). */
+export declare const ADVISORY_LOGGER = "mstar/fallbacks-advisory";
+/** Advisory log levels the module sink understands. */
+export type AdvisoryLogLevel = 'debug' | 'warn';
+/** Module-level advisory log sink — bound by `apply` to `ctx.logger(ADVISORY_LOGGER)` (decoration-module pattern). */
+export type AdvisoryLogSink = (level: AdvisoryLogLevel, message: string) => void;
+/**
+ * Bind the advisory log sink (the entry `apply` binds it to
+ * `ctx.logger(ADVISORY_LOGGER)`). Returns the PRIOR sink so a caller can
+ * restore it (test pattern: {@link setDecorationLogger}).
+ */
+export declare function setAdvisoryLogger(sink: AdvisoryLogSink): AdvisoryLogSink;
+/**
+ * Warn id-list cap: an id-list warn line lists at most this many ids before
+ * the `… and K more` suffix — a huge registry (thousands of rows) must not
+ * produce a multi-KB log line (plan QC fix wave S-cap). Exported for the
+ * suite's cap assertions; module surface only — the entry's frozen 47-name
+ * export surface deliberately does not re-export it.
+ */
+export declare const ADVISORY_ID_LIST_CAP = 20;
+/**
+ * One advisory pass: unmounted → not invoked (`false`, no logs); mounted →
+ * report the taxonomy adoption state (bounded: ≤1 warn per category). With
+ * the service present the pass is ASYNC: it awaits the idempotent re-declare
+ * before the effective-state readback (report determinism — the boot
+ * dual-inject-child race window is closed). Never throws — every failure
+ * mode degrades to skip + one debug/warn. Never writes the fallbacks config.
+ *
+ * @param ctx - the plugin's registrant context (the app composition root).
+ * @param agentsDir - the `harness-agents/` mirror root the mstar role-id set
+ *   is derived from; absent → the taxonomy checks are skipped (one debug
+ *   log; the legacy-keys check is mirror-independent and still runs).
+ * @returns `true` when the pass ran (mounted), `false` when unmounted — the
+ *   caller (entry `apply`) uses the boolean for the one-pass-per-apply latch.
+ */
+export declare function runFallbacksAdvisory(ctx: Context, agentsDir: string | undefined): Promise<boolean>;

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

@@ -0,0 +1,108 @@
+/**
+ * Role-based subagent decoration at the `subagent/start` seam (plan
+ * `20260814-dsh-fallbacks-integration` Task 2).
+ *
+ * Decoration rides the `subagent/start` EMIT — NOT `tools/pre-execute`:
+ * tool args are deep-frozen snapshots and persona/`agentOptions` come from
+ * the tool-subagent's own Config, never call args. The listener is
+ * SYNCHRONOUS (the section must register before the child's first LLM call)
+ * and resolves the published child via `ctx.get('agents')?.get(info.id)` —
+ * documented in the `@deepseek-ai/dsh-subagent` event contract ("For
+ * in-process providers, `ctx.agents.get(info.id)` resolves during this
+ * notification"). The registered section is agent-scoped on `Agent.ctx`
+ * (contributions are agent-local and unwind on disposal — the
+ * hooks-claude-code precedent).
+ *
+ * Role identity uses the engine Assignment header grammar — the SAME
+ * parsers the dispatch gate uses (`assignmentHeaderRegion` +
+ * `parseAssignmentFields`) — over the child's seeded task prompt (the
+ * child session's first `user/message`). Persona lookup (plan
+ * `20260815-dsh-fallbacks-personas` Task 3) is the single
+ * {@link personaFor} surface — `Config.rolePersonas[executeAs]` →
+ * `harness-agents/` mirror default → skip (never gated on `roleMap` or on
+ * the fallbacks mounted state: unmounted fallbacks degrades to the same
+ * injection with exactly one debug log; probe at the decision point, no
+ * cache). `roleMap` is a taxonomy bridge for logging + future rule-driven
+ * interop only. The mirror root is bound at apply (`setDecorationAgentsDir`
+ * ← `packagedAgentsDir()`), package-relative so the shipped bundle works
+ * from any launch cwd.
+ *
+ * Degradation (the listener never throws — contained like the dispatch
+ * gate's degrade path): `agents` service absent → skip + one debug log
+ * (documented Known Limitation for compositions without dsh-agent);
+ * child unresolved / non-Assignment / role-unmatched → silent no-op
+ * (role-unmatched with the mirror present and no eligible shell stays
+ * silent; with NO mirror the config-miss path logs ONE debug per apply —
+ * case (e) semantics). A throwing log sink is contained inside the log
+ * helper itself (plan QC F-002) — the sink must not escape the listener
+ * either.
+ *
+ * Persona text is rendered by dsh system-prompt's STRICT `{{...}}`
+ * interpolation, so persona values MUST NOT contain `{{` paired with a
+ * later `}}` — the Config schema rejects such values at plugin mount (see
+ * `_shared.ts` `rolePersonas` / `PERSONA_INTERPOLATION_HAZARD`); a mirror
+ * default carrying the hazard is warned + skipped at extraction (never a
+ * boot throw).
+ *
+ * Module boundary: no barrel — the entry imports this module by explicit
+ * relative path and re-exports the public names verbatim.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { Config } from './_shared.ts';
+/** Logger label for the subagent decoration (dsh logger naming: `<scope>/<subject>`). */
+export declare const DECORATION_LOGGER = "mstar/subagent-decoration";
+/** The decoration's system-prompt section name (agent-scoped on `Agent.ctx`). */
+export declare const PERSONA_SECTION_NAME = "mstar:role-persona";
+/** Prompt order of the persona section — renders right after the deployment persona slot (order 0). */
+export declare const PERSONA_SECTION_ORDER = 1;
+/**
+ * Structural view of the `subagent/start` emit payload the decoration
+ * consumes (`@deepseek-ai/dsh-subagent` `SubagentRunInfo` — the plugin
+ * carries no dsh-subagent dependency; same pattern as the probe's
+ * `LoaderEntryView` and agent-flow's `TaskDoneSnapshot`). Only `id` is
+ * consumed; the rest keeps the view faithful to the published contract.
+ */
+export interface SubagentRunInfoView {
+    /** Unique identity shared with the paired terminal event. */
+    readonly runId: unknown;
+    /** Provider name recorded when the child was first created. */
+    readonly provider: string;
+    /** The child agent's id. */
+    readonly id: string;
+    /** Snapshot of whether the run's local agent was present when start fulfilled. */
+    readonly local: boolean;
+}
+/** Decoration log levels the module sink understands. */
+export type DecorationLogLevel = 'debug' | 'info' | 'warn';
+/** Module-level decoration log sink — bound by `apply` to `ctx.logger(DECORATION_LOGGER)` (agent-flow ledger precedent). */
+export type DecorationLogSink = (level: DecorationLogLevel, message: string) => void;
+/**
+ * Bind the decoration log sink (the entry `apply` binds it to
+ * `ctx.logger(DECORATION_LOGGER)`). Returns the PRIOR sink so a caller can
+ * restore it (test pattern: agent-flow `setAgentFlowLogger`).
+ */
+export declare function setDecorationLogger(sink: DecorationLogSink): DecorationLogSink;
+/**
+ * Bind the persona-defaults mirror root. Returns the PRIOR binding so a
+ * caller can restore it (test pattern: {@link setDecorationLogger}).
+ * @param dir - the mirror root, or `undefined` to disable mirror defaults.
+ */
+export declare function setDecorationAgentsDir(dir: string | undefined): string | undefined;
+/**
+ * Decorate one `subagent/start` emit: resolve the child, extract its seeded
+ * task prompt, and — when the prompt is Assignment-shaped and
+ * `rolePersonas[executeAs]` is configured — register the persona as the
+ * child's `mstar:role-persona` system-prompt section (agent-scoped on
+ * `Agent.ctx`, unwinds on child disposal). Synchronous by design: the
+ * section must register before the child's first LLM call.
+ *
+ * Never throws — every failure mode degrades (skip + one log line at most),
+ * matching the dispatch gate's contained degrade path; the dispatch itself
+ * is never affected.
+ *
+ * @param ctx - the plugin's registrant context (the app composition root).
+ * @param config - validated plugin configuration (`rolePersonas` is the only
+ *   payload source; `roleMap` is never consulted for injection).
+ * @param info - the `subagent/start` emit payload.
+ */
+export declare function decorateSubagentStart(ctx: Context, config: Config, info: SubagentRunInfoView): void;

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

@@ -0,0 +1,63 @@
+/**
+ * Capability probes for the OPTIONAL `dsh-llm-fallbacks` plugin (plan
+ * `20260814-dsh-fallbacks-integration` Task 1 — probe foundation).
+ *
+ * The fallbacks plugin is registry-declared (`dependencies`) and external in
+ * the build, and every import here is TYPE-ONLY: `dist/index.js` must carry
+ * ZERO runtime references to `dsh-llm-fallbacks`. The package's
+ * `declare module '@deepseek-ai/cordis'` augmentation types
+ * `ctx.get('llm-fallbacks')` for importers.
+ *
+ * Two views:
+ * - {@link fallbacksService} — the named cordis service while the plugin is
+ *   applied. Registration is per-apply, so the service is `undefined` during
+ *   HMR/fiber-swap windows even when the loader entry lives (the entry is
+ *   declarative and outlives a fiber swap).
+ * - {@link fallbacksMounted} — capability view, service-first with a
+ *   loader-entries fallback: the loader entry is present, enabled, and has a
+ *   live fiber. Point-in-time read (no cache) — loader mounts entries
+ *   concurrently (plugin-inventory philosophy).
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { FallbacksService } from 'dsh-llm-fallbacks';
+/** Loader entry name of the `dsh-llm-fallbacks` plugin row. */
+export declare const FALLBACKS_ENTRY_NAME = "dsh-llm-fallbacks";
+/**
+ * Minimal structural view of one cordis loader `Entry` the probe reads
+ * (`@deepseek-ai/cordis-plugin-loader` `Entry`/`EntryOptions` contract — the
+ * plugin carries no loader dependency; this is the consumed surface, same
+ * pattern as the optional `jobs` seam in agent-flow.ts).
+ */
+export interface LoaderEntryView {
+    options: {
+        name: string;
+        group?: boolean | null;
+        /**
+         * Deployment row config (`EntryOptions.config` — "Config passed to the
+         * plugin", the same value the plugin's `apply()` receives; architect-
+         * verified field 2026-08-15). ABSENT when the user never configured the
+         * row — the adoption advisory treats that as an unreadable config.
+         */
+        config?: unknown;
+    };
+    disabled: boolean;
+    fiber: unknown;
+}
+/** Service view: the named `llm-fallbacks` cordis service while applied. */
+export declare function fallbacksService(ctx: Context): FallbacksService | undefined;
+/**
+ * The fallbacks loader row when present and enabled (group rows skipped).
+ * Unlike {@link fallbacksMounted}, NO live-fiber requirement: the entry is
+ * declarative and `options.config` is set at entry creation, so the adoption
+ * advisory (plan `20260815-dsh-fallbacks-personas` Task 4) can read the
+ * deployment's row config even during HMR/fiber-swap windows — the advisory
+ * caller gates on `fallbacksMounted` first.
+ */
+export declare function fallbacksEntry(ctx: Context): LoaderEntryView | undefined;
+/**
+ * Capability view: `true` when the fallbacks capability is mounted — the
+ * service is applied, or (service absent: HMR/fiber-swap window, older
+ * version, not yet applied) the loader entry is present, enabled, and its
+ * fiber is live.
+ */
+export declare function fallbacksMounted(ctx: Context): boolean;