dsh-llm-fallbacks 0.5.0 → 0.5.2

package/dist/role-notice.d.ts

@@ -0,0 +1,156 @@
+/**
+ * In-session role notice row (plan role-based-subagent-adoption Task 3).
+ *
+ * The child of a role-carrying dispatch gets ONE durable transcript row naming
+ * the role it was dispatched as, so the role is visible where the work is read
+ * — inside the child's own session — without reaching for live plugin state.
+ *
+ * Channel: an `agent/pre-step` listener that appends EXACTLY ONE message to the
+ * decision the loop is about to enter (`decision.messages`), which the loop
+ * then commits durably on the step's first attempt
+ * (`agent-loop/src/agent.ts:373-378` — `if (firstAttempt) for (const message of
+ * decision.messages)` the loop commits each message to the session log as a
+ * `'user/message'`). The listener is registered with `{ prepend: true }` (the
+ * `modelSwitchNotice` precedent in
+ * `core/agent/src/model-selection.ts:108-125`), so it is the OUTERMOST layer:
+ * `await next()` yields the FINAL decision every other listener shaped. The
+ * contract is EXACTLY ONE row, not its position: a plugin that registers its
+ * own `{ prepend: true }` `agent/pre-step` listener AFTER this one sits outside
+ * it and may append after the notice, and the loop commits the decision's
+ * messages in order — so the row is appended to whatever the inner listeners
+ * shaped, not guaranteed to be the last one.
+ *
+ * NOT `agent.inject()`: that queue is documented as lossy — "It may miss a
+ * request whose pre-step already claimed its batch. Cancellation or disposal
+ * may discard pending context." (`core/agent/src/runtime-types.ts:231-241`), and
+ * with `wakeup: false` an idle child is never woken to receive it. The pre-step
+ * decision has neither failure mode.
+ *
+ * Session-write contract (plan Global Constraints, hard): the row is a
+ * `user/message` built with `createUserMessage` and the sanctioned plugin source
+ * `{ kind: 'plugin', plugin: 'dsh-llm-fallbacks', form: 'notice', summary: … }`.
+ * `plugin` is a member of the FROZEN released source-kind set the V2→V3 edge
+ * classifies (`dsh-session-format-v2-to-v3/lib/index.js:14-30`: 15 kinds,
+ * includes `plugin`); a bespoke kind would write fine and then refuse at the
+ * next frozen edge with `cannot safely transform unclassified message source`
+ * (`:125`). NO custom session event type, NO `ignorable` marker — a mount-only
+ * plugin cannot publish either (`.mstar/projects/_default/references/
+ * subagent-role-badge-visible/explore-role-seam-report.md` §Q3). The guard test
+ * in `tests/role-notice.spec.ts` pins that membership against a checked-in
+ * mirror of the set.
+ *
+ * Once per child SESSION: the emitter consumes the seam's per-child record
+ * marker (`firstNoticePending`) AND a per-agent `emitted` set (mirroring the
+ * existing `dispatchInjected` pattern), both written only AFTER the row is built
+ * — so a throwing producer degrades without consuming the child's one notice.
+ * Never for a root agent, never for `inherit`/unresolved (those never get a
+ * record), never twice across steps or within-step retries.
+ *
+ * CF-6 — the emitted marker is SESSION-stable and bounded. `Agent.id` IS the
+ * child session id, and a continuable child's durable session outlives its
+ * activation, so the caller (`src/index.ts`) keeps this marker across
+ * `agent/disposed` and clears it only when the plugin itself is disposed; that
+ * is what makes the documented "exactly one notice row per child session" hold
+ * across a dispose + re-activate resume. Because it is never per-activation
+ * cleared it must be bounded: {@link markNoticeEmitted} evicts the oldest entry
+ * once {@link NOTICE_EMITTED_LIMIT} sessions are remembered (a child evicted
+ * that way can at worst be announced a second time, and the projection fold is
+ * last-wins, so no wrong role is ever produced).
+ *
+ * Degrade-never-crash: any throw in the path is contained with ONE debug line
+ * and the decision is returned UNCHANGED — a step is never broken, and no
+ * partial row is ever published.
+ *
+ * @module dsh-llm-fallbacks/role-notice
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { type UserMessage } from '@deepseek-ai/dsh-llm';
+import type { SubagentSeamRecord } from './subagents-seam.ts';
+/**
+ * The `plugin` field of every notice this plugin writes. Stable: the durable
+ * source's provenance label is read from it (`ui-conversation`
+ * `context-provenance.ts` — "the plugin id, or the bare source kind").
+ */
+export declare const ROLE_NOTICE_PLUGIN = "dsh-llm-fallbacks";
+/**
+ * The message source KIND the notice rides. `plugin` is the sanctioned kind for
+ * a plugin-authored notice and a member of the frozen released set (see the
+ * module header); the value is exported so the guard test asserts on the exact
+ * literal the emitter uses.
+ */
+export declare const ROLE_NOTICE_SOURCE_KIND = "plugin";
+/** Suffix appended when the role declares a persona that was NOT delivered. */
+export declare const ROLE_NOTICE_PERSONA_SKIPPED_SUFFIX = " (persona not applied)";
+/**
+ * How many child sessions whose notice was already emitted stay remembered
+ * (CF-6). The marker is session-stable — kept across `agent/disposed` so a
+ * re-activated continuable child is not announced twice — so it needs a bound:
+ * past this many sessions the oldest entry is evicted (worst case: a later
+ * re-activation of that evicted child writes a second identical row; the
+ * projection fold is last-wins, so the pill never names a wrong role).
+ */
+export declare const NOTICE_EMITTED_LIMIT = 256;
+/**
+ * Mark one child session as announced, evicting the oldest remembered session
+ * once {@link NOTICE_EMITTED_LIMIT} is reached (insertion-ordered `Set`
+ * semantics: the oldest entry is the first value). A session already marked
+ * keeps its position — its marker is only ever written once.
+ */
+export declare function markNoticeEmitted(emitted: Set<string>, childSessionId: string): void;
+/** One notice-message producer: role id + whether the declared persona was skipped. */
+export type RoleNoticeBuilder = (role: string, personaNotApplied: boolean) => UserMessage;
+/**
+ * Build the ONE role notice row (pure): `[role: <id>]`, with
+ * ` (persona not applied)` appended when the role declares a persona that Task
+ * 2's capability gate declined to deliver. The summary keeps `role: <id>` either
+ * way — it is the collapsed row's one-line account, and the durable role string
+ * must live there as well as in the content.
+ *
+ * @param role - the DECLARED RAW role id resolved at the dispatch seam.
+ * @param personaNotApplied - `true` only when a declared persona was skipped.
+ */
+export declare function buildRoleNotice(role: string, personaNotApplied: boolean): UserMessage;
+/** Options for {@link installRoleNotice}. */
+export interface RoleNoticeOptions {
+    /**
+     * The dispatch seam's per-child records, keyed by child SESSION id (which IS
+     * `Agent.id`). Read at each pre-step — never captured — so a record written by
+     * a dispatch that races the child's first step is still seen.
+     */
+    records: Map<string, SubagentSeamRecord>;
+    /**
+     * Per-agent marker of children whose notice was already emitted (mirrors the
+     * runtime's `dispatchInjected`): the in-memory half of the once-per-child
+     * guarantee, independent of the record's `firstNoticePending` (which a record
+     * rewrite preserves deliberately) and of the loop's retry bookkeeping.
+     *
+     * SESSION-stable and bounded (CF-6): the caller keeps it across
+     * `agent/disposed` so a re-activated child is never announced twice, and
+     * {@link markNoticeEmitted} bounds it. ROOT-shared across the fibers applied
+     * over one root (CF-5), so a second fiber's emitter cannot announce a child
+     * the first already announced.
+     */
+    emitted: Set<string>;
+    /**
+     * Message producer. Defaults to {@link buildRoleNotice}; the only reason to
+     * replace it is to pin the contained-degrade path (a throwing producer must
+     * publish no row and must NOT consume the child's one notice).
+     */
+    buildNotice?: RoleNoticeBuilder;
+    /** Contained debug sink (at most ONE line per contained degrade). */
+    debug?: (message: string) => void;
+}
+/**
+ * Register the `agent/pre-step` notice emitter on `ctx`; returns its disposer
+ * (the owning fiber's teardown registers it, exactly like the seam's other
+ * listeners).
+ *
+ * Emission order per pre-step (cheapest first, all read-only until the emit):
+ * `next()` → reject/abort → empty decision → `origin === 'subagent'` → already
+ * emitted → pending record. The empty-decision guard is NOT cosmetic: the loop
+ * skips a step whose admitted messages are empty (`phase.step === 0 &&
+ * decision.messages.length === 0` → turn completed, no model call), so a notice
+ * pushed into an empty decision would turn a no-op step into a model call whose
+ * only input is our row.
+ */
+export declare function installRoleNotice(ctx: Context, options: RoleNoticeOptions): () => void;

package/dist/role-projection-key.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The session-projection contract of the subagent role pill (plan
+ * role-based-subagent-adoption Task 3b): the ONE key the host fold
+ * (`./role-projection.ts`) publishes and the session-header badge reads.
+ *
+ * PURE module — no `@deepseek-ai/*` import, no host-only dependency — because
+ * BOTH halves import it: the host through the seam's install point, the client
+ * through `SubagentRoleBadge`. Splitting the key (and the value guard) out of
+ * the host module is what keeps the client half free of the fold's host
+ * imports, and a single shared literal is what keeps the two halves from
+ * drifting into a silent "no pill".
+ *
+ * @module dsh-llm-fallbacks/role-projection-key
+ */
+/**
+ * The projection key the role pill reads (`useProjection(ROLE_PROJECTION_KEY)`).
+ * Lower-camel like the host's own session-scoped keys (`modelSelection`,
+ * `sessionListMetadata`); the `fallbacks` prefix keeps a third-party key
+ * unambiguous inside the shared `SessionProjectionMap`.
+ */
+export declare const ROLE_PROJECTION_KEY = "fallbacksSubagentRole";
+/**
+ * The client-visible value of the role projection: the DECLARED RAW role id the
+ * child was dispatched as (padding included — it is the id the settings
+ * document declares), or `null` while the child's log carries no role notice
+ * row (`./role-notice.ts`).
+ *
+ * A role id, NOT a record: the route is a SEPARATE host projection
+ * (`modelSelection`), because the notice row is written once at the child's
+ * first step while the route it ends up on can change afterwards.
+ */
+export type RoleProjectionValue = string | null;
+/**
+ * Read a projection value defensively (degrade-never-crash): only a non-blank
+ * string is a role. `undefined` — the key is not registered on this host, or no
+ * baseline/frame has carried it yet — and every foreign value read as "no
+ * role", so the pill collapses to nothing instead of naming something wrong.
+ *
+ * @param value - the raw `useProjection('<key>')` value.
+ */
+export declare function readRoleProjectionValue(value: unknown): string | undefined;

package/dist/role-projection.d.ts

@@ -0,0 +1,151 @@
+/**
+ * Durable role visibility for the session-header badge (plan
+ * role-based-subagent-adoption Task 3b) — ONE host-side session projection unit
+ * folding the role out of the child's OWN durable log.
+ *
+ * Data source = Task 3's notice row, the plugin's single write primitive: the
+ * fold reads the child's committed `user/message` events, keeps the one whose
+ * provenance is ours (`source.kind === 'plugin'` + `source.plugin ===
+ * ROLE_NOTICE_PLUGIN`), and parses the role out of its **content text**
+ * (`[role: <id>]`). No second write path, no new event type, no plugin-owned
+ * store: the projection is a pure READ of the log, and the host's projection
+ * cache checkpoints every registered unit at session creation, `turn/end` and
+ * disposal — so a settled child (served as an unpublished observation whose
+ * `projections` ride the follow opening snapshot) and a post-restart view both
+ * work with nothing of ours on disk.
+ *
+ * NEVER `source.summary`: summaries are truncated at
+ * `CONTEXT_SUMMARY_MAX_CHARS = 120` (`@deepseek-ai/dsh-llm` `message.ts`,
+ * applied by `boundContextSummary`) while a role id has no length bound in the
+ * settings schema — a long id would be CUT there and the pill would name a role
+ * that does not exist. The content blocks are unbounded, so the content text is
+ * the only correct source; the row's provenance is what makes the pre-filter
+ * cheap.
+ *
+ * Mount-only + STRUCTURAL: the registry and the unit contract are consumed as
+ * the local structural views below and this module value-imports no host seam,
+ * so the host calls INTO us. The declared
+ * `@deepseek-ai/dsh-session-projection` peerDependency (Task 3b L2 review M-2)
+ * serves the in-process Step-0 spec, which builds the REAL registry — being the
+ * real registry is the whole point of that proof — not a runtime import here
+ * (the badge reads its seat structurally for the same reason).
+ * The runtime shape relied on — `register({ key, stateSchema, init, apply,
+ * wire: { viewSchema, view }, stateVersion })` → unregister disposer — is the
+ * documented `ProjectionDefinition` contract of
+ * `@deepseek-ai/dsh-session-projection@0.1.5-rc.1`
+ * (`lib/types/index.d.ts:38-80,150-152`); only `.parse` is ever called on the
+ * schemas (`lib/index.js:255,305,433`).
+ *
+ * @module dsh-llm-fallbacks/role-projection
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { SessionEvent } from '@deepseek-ai/dsh-session';
+import { type RoleProjectionValue } from './role-projection-key.ts';
+/**
+ * The `.parse` face the registry uses on a definition's `stateSchema` /
+ * `wire.viewSchema` (a structural stand-in for the peer's `ZodType`, so this
+ * module needs no zod import and no new peer).
+ */
+interface ProjectionValueSchema<T> {
+    parse(value: unknown): T;
+}
+/**
+ * One registered projection unit, as this plugin declares it (the consumed
+ * subset of the host's `ProjectionDefinition`): `init` and `apply` are PURE and
+ * SYNCHRONOUS, `state` is plain JSON (the persisted-checkpoint precondition),
+ * and `wire` publishes the client-visible value.
+ */
+export interface RoleProjectionUnit {
+    readonly key: string;
+    readonly stateSchema: ProjectionValueSchema<RoleProjectionState | null>;
+    init(header: unknown, inheritedEventCount: number): RoleProjectionState | null;
+    apply(state: RoleProjectionState | null, event: SessionEvent): RoleProjectionState | null;
+    readonly stateVersion: number;
+    readonly wire: {
+        readonly viewSchema: ProjectionValueSchema<RoleProjectionValue>;
+        view(state: RoleProjectionState | null): RoleProjectionValue;
+    };
+}
+/**
+ * The host fold state: the fork boundary the fold was initialized with, plus the
+ * resolved role once an OWN notice row has landed (`role` absent until then).
+ * An OBJECT, not a bare string, because the registry's publication rule is
+ * reference identity (`Object.is`) — the fold must be able to prove it left the
+ * state untouched, and that proof is only meaningful for a value the fold could
+ * otherwise re-allocate.
+ *
+ * `inheritedEventCount` is part of the state, not a closure constant: the
+ * registry hands `init` the exact fork-inherited prefix length and then folds
+ * the WHOLE log into `apply`, so the boundary has to survive into every `apply`
+ * call (and into a persisted checkpoint row) for the fold to skip an ancestor's
+ * events.
+ */
+export interface RoleProjectionState {
+    /**
+     * The exact fork-inherited prefix length `init` was handed: events with
+     * `seq < inheritedEventCount` belong to the ANCESTOR the child was seeded
+     * from, never to the child.
+     */
+    readonly inheritedEventCount: number;
+    /** The DECLARED RAW role id, verbatim (padding included); absent until then. */
+    readonly role?: string;
+}
+/**
+ * The registry face this plugin uses (`ctx.sessionProjections`): the
+ * client-visible `register` overload plus the read faces the in-process proof
+ * reads. Structural on purpose — see the module header.
+ */
+export interface RoleProjectionRegistryView {
+    register(unit: RoleProjectionUnit): () => void;
+}
+/**
+ * The projection state/version. Bump `stateVersion` whenever the fold changes —
+ * v2 added the fork boundary (`inheritedEventCount`), so a v1 checkpoint row is
+ * NOT re-usable and must be refolded from the log.
+ */
+export declare const ROLE_PROJECTION_STATE_VERSION = 2;
+/**
+ * The ONE role projection unit (plan Task 3b).
+ *
+ * `init` records the fork boundary and nothing else (a child's own log carries
+ * no role yet), `apply` skips every event BELOW that boundary — the seeded
+ * prefix is the ANCESTOR's log, and the plan pins "child whose notice never
+ * landed: no pill, never a wrong pill" — and otherwise folds last-wins over our
+ * own notice rows, returning the SAME state reference for every event it does
+ * not use (the registry's `Object.is` rule: an unchanged reference produces zero
+ * downstream work and no client publication) — including a repeated notice with
+ * the same role, which is what makes the fold idempotent under a replay.
+ *
+ * The boundary carries into the state because the registry calls `apply` with
+ * the WHOLE log (including the fork prefix) on every rung: `buildCell`,
+ * `drive`'s late-registration fold and `restore` all fold from `init` forward.
+ * The host's own sibling unit in the same tree does exactly this
+ * (`@deepseek-ai/dsh-subagent` `subagentCatalogProjectionDefinition`:
+ * `init: (_header, inheritedEventCount) => ({ inheritedEventCount })` and
+ * `apply: … || event.seq < state.inheritedEventCount → return state`).
+ */
+export declare const roleProjectionUnit: RoleProjectionUnit;
+/** Options for {@link installRoleProjection}. */
+export interface RoleProjectionOptions {
+    /** Contained debug sink (at most ONE line per contained degrade). */
+    debug?: (message: string) => void;
+}
+/**
+ * Register {@link roleProjectionUnit} on `ctx.sessionProjections` through the
+ * same conditional-inject idiom the plugin already uses for `settings` / `llm` /
+ * `typert`: the child activates only when the registry is composed, so a
+ * composition without it keeps the key absent and the badge renders nothing
+ * (capability absence — never a dispatch failure, never a crash).
+ *
+ * Registration is an effect on the child fiber: a second apply over the same
+ * root registers the SAME key at the SAME `stateVersion`, which the registry
+ * counts (one unit, the key survives until the last holder unloads) — so this
+ * needs no dedupe of its own, and a reshaped registry that refuses the
+ * registration degrades with one contained debug line.
+ *
+ * @param ctx - the plugin fiber's context.
+ * @param options - contained debug sink.
+ * @returns the disposer that withdraws the child (and with it the key).
+ */
+export declare function installRoleProjection(ctx: Context, options?: RoleProjectionOptions): () => void;
+export {};

package/dist/subagents-seam.d.ts

@@ -0,0 +1,292 @@
+/**
+ * Dispatch-seam role resolution + per-child record (plan
+ * role-based-subagent-adoption Task 1).
+ *
+ * The seam is the documented cordis service-read waterfall
+ * (`Events['internal/get']`, `@deepseek-ai/cordis` 4.0.2
+ * `lib/types/events.d.ts`): a listener wraps the `subagents` service VALUE on
+ * read and returns a prototype-delegating wrapper whose `start` /
+ * `startContinuable` resolve the dispatch role from the incoming request
+ * BEFORE delegating. The real service object is never mutated; readers of the
+ * `subagents` service transparently receive the wrapper.
+ *
+ * Role source (plan Global Constraints): the child request's prompt carries
+ * the Assignment header field `**Execute as**: <id>` — dsh role binding is
+ * prompt-only. {@link resolveDeclaredRoleFromAssignment} is the ONE pure
+ * resolution point; it canonicalizes exactly like the existing trimmed-id
+ * map (trim, drop ONE leading `@`, case-insensitive match against the
+ * declared trimmed ids) and returns the DECLARED RAW id. Undeclared, absent,
+ * `inherit`, or ambiguous declarations resolve to `undefined` = no role.
+ *
+ * The resolution reads the Assignment HEADER region only, never the whole
+ * prompt (Task 1 CF-2): the region ends at the first Assignment body marker,
+ * and when the prompt carries NO marker it is bounded to the LEADING HEADER
+ * BLOCK — the first paragraph plus every following paragraph that opens with
+ * header material, ending at the prompt's first prose paragraph. So a
+ * `**Execute as**: <id>` line quoted inside a body paragraph can never shape a
+ * resolution (it is outside the region) even though mstar's canonical dispatch
+ * text carries no body marker at all. Inside the region the engine's pinned
+ * ambiguity rule stands unchanged: the DISTINCT DECLARED ids must collapse to
+ * exactly one, else the dispatch is a no-op — never a first-occurrence pick.
+ *
+ * Per-child record: the wrapped start's RESULT carries the child session id —
+ * `start` resolves to a `SubagentRun` (`id` IS the published child session id
+ * for a local run) and `startContinuable` to a `ContinuableStart` (`childId`).
+ * The record `{ role, at, firstNoticePending }` is keyed by that id (Task 3
+ * reads it to emit the one role notice row). A result carrying only a
+ * `jobId` — a registry job id, NOT a session id — is never keyed: the child is
+ * correlated instead through the parent-owned `subagent/catalog` session event
+ * `{ childId, label }` joined on the delegating parent + request label.
+ *
+ * Persona delivery (plan Task 2): the SAME single resolution point merges the
+ * declared role's `roles.list[].persona` (trimmed, non-empty) into the
+ * request's NATIVE `persona` slot — the slot the runtime composes as the
+ * scoped `deployment:persona-prefix` system-prompt section on the child. The
+ * source is the RESOLVED ROLE only, so delivery is chain-independent: a
+ * `chain: []` role gets its persona exactly like a chained one (no routing
+ * state is read). Both native start surfaces are covered, with the gate each
+ * one's fail-loud contract needs (measured on the installed
+ * `@deepseek-ai/dsh-subagent` `0.1.5-rc.1`): the one-shot `start` REJECTS a
+ * request carrying `persona` for a provider whose
+ * `getProvider(name).capabilities.persona` is not `true` (`lib/index.js:3202-3227`,
+ * `assertCapabilities`), so the merge pre-checks that flag; the continuable
+ * surface is composed by the continuation manager, which applies
+ * `request.persona` unconditionally (`lib/index.js:1703-1705`) and is gated by
+ * the provider's `prepareContinuable` presence instead (`lib/index.js:3179-3183`).
+ * A gate miss skips the persona with ONE contained debug log — never a failed
+ * start. An explicit caller `persona` WINS (the slot is filled only when it is
+ * absent), and every skip path returns the caller's OWN request object, so the
+ * native call stays byte-identical.
+ *
+ * In-session notice row (plan Task 3): the SAME install point registers the
+ * `agent/pre-step` emitter (`./role-notice.ts`) over the record map it owns, so
+ * the role is announced once in the child's own session. Its per-agent
+ * `noticeEmitted` marker is exposed here for the caller's cleanup sites: the
+ * plugin dispose effect clears it, while `agent/disposed` deliberately KEEPS it
+ * (CF-6 — the marker is SESSION-stable and bounded, because a continuable
+ * child's durable session survives its activation).
+ *
+ * Durable role visibility (plan Task 3b): the SAME install point registers the
+ * host-side session projection unit (`./role-projection.ts`) that folds that
+ * notice row out of the child's own log, so the session-header badge can show
+ * the role for a settled child and after a host restart — a read of the SAME
+ * single write primitive, never a second one.
+ *
+ * Multi-fiber composition (CF-5): the record map and the notice marker are
+ * ROOT-shared, while only the `internal/get` wrapper (+ the catalog listener it
+ * feeds) is single-owner. Every applied fiber registers its OWN notice emitter
+ * and projection unit and reports its ownership structurally
+ * (`SubagentSeam.ownsWrapper`), so a disposing fiber cannot silently take the
+ * role surfaces down with it.
+ *
+ * Degrade-never-crash: an absent/reshaped service, an unexpected result
+ * shape, or any throwing bookkeeping degrades to the native path with at most
+ * ONE contained debug log — a dispatch is never affected.
+ *
+ * @module dsh-llm-fallbacks/subagents-seam
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { type FallbacksRole } from './config.ts';
+/**
+ * The cordis service-read waterfall event the seam registers on. Referenced
+ * ONCE (registration) so a future cordis rename is a one-line change here.
+ */
+export declare const SUBAGENT_SEAM_EVENT = "internal/get";
+/** The service name the seam wraps (`ctx.subagents`). */
+export declare const SUBAGENT_SEAM_SERVICE = "subagents";
+/**
+ * One dispatch-resolved per-child record (Task 3 reads it to emit exactly one
+ * role notice row per child session).
+ */
+export interface SubagentSeamRecord {
+    /**
+     * The DECLARED RAW role id resolved at the dispatch seam.
+     *
+     * Authoritative-role precedence (CF-10, documented rather than resolved by
+     * re-branding): a `startContinuable` resume re-keys the child and may resolve
+     * a DIFFERENT declared role, and this field is then rewritten while the
+     * durable notice row the child's session already carries keeps the FIRST role.
+     * The projection deliberately reads the notice row, so the durable role is the
+     * child's announced identity and this record is only the LIVE dispatch hint
+     * (what the next start / the resume fallback would use). The two can therefore
+     * disagree after a re-dispatch until the child is disposed; no consumer may
+     * treat the record as the durable role.
+     */
+    role: string;
+    /** When the record was written (epoch ms). */
+    at: number;
+    /**
+     * `true` until the child's role notice row has been emitted (Task 3). A
+     * later write for the SAME child session preserves an already-cleared
+     * marker, so a repeat dispatch/resume cannot produce a second notice row.
+     * The root-shared `noticeEmitted` set is the SESSION-stable half of that
+     * guarantee (it survives `agent/disposed`); this field is the per-record half
+     * that a resume rewrite preserves.
+     */
+    firstNoticePending: boolean;
+    /**
+     * `true` when the role DECLARES a persona and that persona was NOT delivered
+     * (Task 2's capability gate declined it, or no provider was registered to
+     * carry it). Absent when there was nothing to report: the persona was
+     * delivered, the caller set one (explicit intent wins), the role declares
+     * none, or no persona source is wired. Task 3 appends
+     * ` (persona not applied)` on `true` only.
+     *
+     * STICKY (Task 3 review Minor 4): a record rewrite (a `startContinuable`
+     * resume re-keys the child) can only ADD this verdict, never clear it. A
+     * resume recomputes the merge outcome on its own surface — and that surface
+     * legitimately returns `false` when it delivers the CALLER's persona or when
+     * its own merge degrades — but neither retroactively installs the role's
+     * DECLARED persona on the dispatch that already reported it missing. The
+     * child's one notice row is a claim about that dispatch, so the first `true`
+     * survives; a later `false` is simply not recorded.
+     */
+    personaNotApplied?: boolean;
+}
+/** One consumed prompt content block (`@deepseek-ai/dsh-llm` `ContentBlock` text members). */
+export interface SubagentPromptBlockView {
+    readonly type: string;
+    readonly text?: string;
+}
+/**
+ * Structural view of the one-shot start request (consumed fields only): the
+ * `prompt` is the role-extraction source, `label` + `parent` are the
+ * catalog-correlation join key, and `persona` is the NATIVE per-child persona
+ * slot the role persona is merged into (plan Global Constraints: an explicit
+ * caller value wins). The wrapper forwards the request object itself, so every
+ * other field reaches the service unchanged.
+ */
+export interface SubagentStartRequestView {
+    readonly prompt?: readonly SubagentPromptBlockView[];
+    readonly label?: string;
+    readonly parent?: {
+        readonly session?: {
+            readonly id?: string;
+        };
+    };
+    readonly persona?: string;
+}
+/**
+ * Structural view of the continuable start spec (consumed fields only):
+ * `childId` is the caller-reserved identity a resume already carries, used as
+ * the record fallback when the resume request has no Assignment header.
+ */
+export interface ContinuableStartSpecView {
+    readonly provider: string;
+    readonly label?: string;
+    readonly childId?: string;
+    readonly request: SubagentStartRequestView;
+}
+/** Options for {@link installSubagentSeam}. */
+export interface SubagentSeamOptions {
+    /**
+     * Live declared-role id map (trimmed id → DECLARED RAW id), read per start
+     * so a settings change is observed without a re-install.
+     */
+    roleIds: () => ReadonlyMap<string, string>;
+    /**
+     * Live declared roles (`roles.list`) — the persona source, read per start so
+     * a settings/persona edit is observed without a re-install. Absent ⇒ the
+     * seam only records roles (no persona delivery).
+     */
+    roles?: () => readonly FallbacksRole[];
+    /** Contained debug sink (at most one line per contained degrade). */
+    debug?: (message: string) => void;
+}
+/** The installed seam (Task 3 surface + explicit teardown). */
+export interface SubagentSeam {
+    /**
+     * Per-child records keyed by the child SESSION id (the wrapped start's
+     * result id). ROOT-shared (CF-5): every fiber applied over the same root reads
+     * the same map. Mutable by design: Task 3 clears `firstNoticePending` after
+     * emitting the notice.
+     */
+    readonly records: Map<string, SubagentSeamRecord>;
+    /**
+     * Per-agent marker of children whose role notice row was already emitted
+     * (mirrors the runtime's `dispatchInjected`): the in-memory half of Task 3's
+     * once-per-child guarantee, also ROOT-shared. SESSION-stable (CF-6): it is
+     * deliberately NOT cleared on `agent/disposed` — a continuable child's durable
+     * session survives the activation, so clearing the marker would let a
+     * re-activation resume append a second notice row to the same log. It is
+     * bounded (`NOTICE_EMITTED_LIMIT`) and cleared only in the plugin dispose
+     * effect.
+     */
+    readonly noticeEmitted: Set<string>;
+    /**
+     * `true` when THIS install owns the root-scoped `internal/get` wrapper (plus
+     * the catalog-correlation listener it feeds) — the only part that must have a
+     * single owner. `false` on a later fiber over the same root, which still
+     * registers its OWN notice emitter and projection unit. The callers' dedupe
+     * branch reads THIS field (CF-5): a structured marker, never a thrown
+     * message.
+     */
+    readonly ownsWrapper: boolean;
+    /** Stop intercepting service reads (the owning fiber's teardown also does). */
+    dispose(): void;
+}
+/**
+ * Cap on un-correlated claims (a `jobId`-only result whose catalog event never
+ * arrives). Bounded insertion-order eviction — recency-ordered, because a
+ * re-claimed hot key is re-inserted (`beginCorrelation` deletes before it sets),
+ * so the busiest claim can never be the one evicted.
+ *
+ * @internal Exported for the bound test (mirrors `subagentSeamOf`): the value is
+ * not part of the plugin's public surface, but a test that hardcoded 64 could
+ * not tell the real bound from a stale copy.
+ */
+export declare const PENDING_CORRELATION_LIMIT = 64;
+/**
+ * PURE dispatch-role resolution (plan Global Constraints): read the Assignment
+ * header field `**Execute as**: <id>` from `prompt` and return the DECLARED
+ * RAW role id, or `undefined` when nothing resolves. Never throws.
+ *
+ * - absent / empty / body-quoted-only → `undefined`
+ * - `inherit` (the reserved "no specific role" id) → `undefined`
+ * - undeclared id → `undefined` (never invent a role)
+ * - several DISTINCT declared ids in the header region → `undefined`
+ *   (ambiguous); repeats of the same declared id (e.g. `coder` and `@CODER`)
+ *   still resolve
+ *
+ * @param prompt - the Assignment text carried by the child request's prompt.
+ * @param roleIds - the declared trimmed-id map (`trimmed id → declared raw id`).
+ */
+export declare function resolveDeclaredRoleFromAssignment(prompt: string, roleIds: ReadonlyMap<string, string>): string | undefined;
+/**
+ * PURE, chain-independent persona lookup (plan Task 2 / Global Constraints):
+ * the DECLARED `persona` of `roleId`, trimmed, and only when it is still
+ * non-empty after the trim — a blank persona is NO persona. `roleId` is the
+ * DECLARED RAW id the seam already resolved, so this is an exact id match, not
+ * a second canonicalization pass.
+ *
+ * Only `id` and `persona` are read: no `chain`, no `rootChain`, no routing
+ * state — a `chain: []` role's persona resolves exactly like a chained one's.
+ *
+ * @param roles - the live declared roles (`roles.list`).
+ * @param roleId - the DECLARED RAW role id resolved at the seam.
+ */
+export declare function personaForRole(roles: readonly FallbacksRole[], roleId: string): string | undefined;
+/**
+ * @internal Test seam (mirrors `chainHeads`): the seam installed on
+ * `ctx`, if any. Not part of the plugin's public surface — lets tests read and
+ * seed the per-child record map without reaching into the installation
+ * closure. `undefined` when no seam is installed.
+ */
+export declare function subagentSeamOf(ctx: Context): SubagentSeam | undefined;
+/**
+ * Install the dispatch seam on `ctx`: wrap every `subagents` service read and
+ * resolve + record the dispatch role per start, and register this fiber's role
+ * surfaces (the notice emitter + the projection unit).
+ *
+ * Never throws for a multi-fiber apply (CF-5): a fiber whose root already owns
+ * the `internal/get` wrapper gets a seam with `ownsWrapper: false` — it shares
+ * the root's record map / notice marker (so exactly one notice row is written
+ * per child) and still installs its OWN notice emitter and projection unit, so
+ * neither surface dies when another fiber of the same root disposes.
+ *
+ * Returns the seam (the shared record map Task 3 reads, the ownership marker,
+ * plus an idempotent `dispose` that withdraws THIS fiber's registrations). The
+ * `internal/get` listener is owned by this module; callers that rely on the
+ * fiber teardown alone may ignore `dispose`.
+ */
+export declare function installSubagentSeam(ctx: Context, options: SubagentSeamOptions): SubagentSeam;