@mstar-harness/dsh 2.1.1

package/dist/gates/_shared.d.ts

@@ -0,0 +1,198 @@
+import z from 'schemastery';
+import type { GateResult, ValidationResult } from '@mstar-harness/engine';
+import type { Config as SkillLocalConfig } from '@deepseek-ai/dsh-skill-filesystem';
+import type { IterationGateListView, IterationGateViolationView } from '../types.ts';
+/** Canonical harness status file name (mstar-plan-artifacts status.json). */
+export declare const STATUS_FILE = "status.json";
+/** Plugin configuration. */
+export interface Config {
+    /**
+     * Explicit harness root. When set, wins over engine probing (plan-conventions
+     * `{HARNESS_DIR}` resolution order); when absent the plugin probes from
+     * the SESSION workspace root (`agent.session.header.cwd`) — never the
+     * process cwd — walking `.mstar/` → `.agents/` → `.plans/`/`plans/`.
+     * Required for repos whose harness root is not a probed name (e.g. a
+     * `.harness/` maintenance root).
+     */
+    harnessDir?: string;
+    /**
+     * Per-deployment enforcement override. `hard` forces
+     * hard gates, `soft` forces warn-only even when an active iteration compass
+     * declares `enforcement: hard` (local rollback); absent → the compass
+     * frontmatter decides, warn-only when no compass hardens (never a global default).
+     */
+    enforcement?: 'hard' | 'soft';
+    /**
+     * Model-facing delegation tool name(s) the dispatch gate matches. The dsh
+     * subagent tool registers as `subagent` by default, but its `toolName`
+     * config may rename instances (tool-subagent README: each instance needs a
+     * distinct name), so the match list is deployment-settable. Defaults to
+     * `['subagent']`.
+     */
+    dispatchTools?: string[];
+    /**
+     * The dispatching agent's own harness role/type (e.g. `fullstack-dev`), used
+     * as the anti-recursion binding: an Assignment whose `Execute as` equals this
+     * role is a self-dispatch (critical violation — leaf executors must not
+     * re-invoke their own role). dsh exposes no agent role on the tool-execution
+     * context, so the deployment declares it. Absent → the anti-recursion
+     * precheck is skipped (an empty binding is not self-recursion).
+     */
+    dispatchBinding?: string;
+    /**
+     * Additional skill roots registered with the dsh skill-filesystem provider
+     * (skill-filesystem `Config.customSkillDirs` semantics — scanned after project
+     * roots and before user roots — single canonical mount).
+     * Dev-time: the mirror `<repo-root>/skills` absolute path. Each root's
+     * children are skill dirs (`<name>/SKILL.md`) or flat skill files
+     * (`<name>.md`). Absent → no custom-root registration.
+     */
+    skillRoots?: string[];
+    /**
+     * Bundled skill root registered with the dsh skill-filesystem provider
+     * (skill-filesystem `Config.bundledSkillDir` semantics — scanned last, trusted).
+     * Production: a `skills/` dir shipped inside the plugin package (the
+     * canonical published form — dsh defaults `$DSH_BUNDLED_SKILL_DIR` when
+     * default roots are included; this plugin mounts an isolated provider, so
+     * the bundled root is registered explicitly). Absent → no bundled-root
+     * registration.
+     */
+    bundledSkillDir?: string;
+    /**
+     * Catalog refresh interval in milliseconds — how often the per-workspace
+     * pre-step catalog cache (engine-status watermark, iteration-gate row,
+     * harness-state row) re-reads status.json / the compass / the knowledge
+     * index. Default 60000: a mid-session plan/compass/residual change lands
+     * within one TTL (the hot path stays a timestamp compare + cache hit
+     * between refreshes; a bounded sync re-read per workspace at most once
+     * per interval). Absent → 60000.
+     */
+    catalogTtlMs?: number;
+}
+/** Schemastery configuration schema for the plugin consumer. Object keys are optional by default (`.optional()` is a vendored-fork addition not present in npm schemastery); omitted ARRAY keys would materialize as `[]` (schemastery empty-value default — the tool-subagent `toolFilter` pitfall), so both dispatch keys preserve omission via `.default(undefined)`. */
+export declare const Config: z<Config>;
+/** One violation line for logs and the typed veto message. */
+export declare function formatViolation(violation: ValidationResult): string;
+/** Narrow an unknown value to a record. */
+export declare function asRecord(value: unknown): Record<string, unknown> | undefined;
+/**
+ * Resolve the hard-enforcement flag for the artifact gates: explicit
+ * Config override wins, else the iteration compass frontmatter (when a
+ * harness dir resolves), else warn-only. {@link resolveHard} parity with a
+ * null-tolerant harness dir — the skill roots and the artifact
+ * seams (design-md / audit / compound / roles) do not require
+ * `{HARNESS_DIR}` (compound scoping is the only seam that does, and only
+ * for its knowledge-path matcher).
+ */
+export declare function resolveSeamHard(harnessDir: string | null, config: Config): boolean;
+/**
+ * Resolve the plugin package's own `harness-skills/` mirror (synced from the
+ * repo root by `bundle-assets` at build/postinstall; gitignored), anchored at
+ * the file URL of one module in the package. Pure — the caller passes its own
+ * module URL string, so the dual-depth resolution is directly unit-testable
+ * at either layout depth without touching `import.meta`. Resolved
+ * package-relative — NOT cwd-anchored — so the shipped bundled mount works
+ * from any launch cwd (this resolves the cwd-anchoring limitation for the
+ * default; an explicit `bundledSkillDir` still wins). Returns undefined when
+ * the mirror is absent (e.g. a checkout where `bundle-assets` has not run —
+ * the default mount is then inert).
+ *
+ * Dual-depth probe semantics: the module moved from `src/index.ts` (one level
+ * below the package root) into `src/gates/_shared.ts` (two levels below in
+ * the source layout, but still inlined one level below in the bundled
+ * `dist/index.js`). Probe both depths — same dual-depth pattern as
+ * `pluginVersion()` — so the mirror resolves identically from source and from
+ * the bundle (behavior-preserving move; the dist path is the original one):
+ * - `'../harness-skills'` — dist 布局候选（`dist/index.js` 深度）：shipped
+ *   form（`package.json` `main: ./dist/index.js`），第一候选直接命中；
+ * - `'../../harness-skills'` — 源码布局候选（`src/gates/` 深度）：dev-time
+ *   form；该深度下第一候选解析到 `src/harness-skills`——非规范路径——落空后
+ *   命中本候选（规范 `packages/dsh/harness-skills`）。
+ * `src/harness-skills` 非规范（镜像仅由 `bundle-assets` 生成到规范位置）；
+ * 若同名目录意外出现（陈旧镜像），shallow-first 既定——dist 布局命中优先于
+ * 源码布局，与 `pluginVersion()` 探测顺序一致（源/dist 不分叉）。
+ *
+ * @param fileUrl - the module's `import.meta.url` string (or any file URL at
+ * the depth whose layout should be probed).
+ */
+export declare function resolvePackagedSkillsDir(fileUrl: string): string | undefined;
+export declare function packagedSkillsDir(): string | undefined;
+/**
+ * Per-workspace `{HARNESS_DIR}` resolution for the plugin.
+ *
+ * The probe NEVER starts from the process cwd — it starts from the WORKSPACE
+ * root of the session whose agent drives the event (the session cwd,
+ * `agent.session.header.cwd` — the dsh workspace the user opened) AND stops
+ * there: `workspaceRoot = 探测起点` (roadmap §7c), so the walk-up never
+ * leaves the session workspace (the `~/.mstar` global-collision defect is
+ * the special case) and the dsh boundary deliberately diverges from the
+ * CLI's git-top-level boundary. An
+ * explicit `harnessDir` config still wins outright (resolved once at boot;
+ * a relative value is launch-cwd anchored — config path anchoring, not
+ * probing — matching the `bundledSkillDir` precedent and the engine's
+ * `resolve(startDir, explicit)` semantics). Probing results are memoized
+ * per workspace root, so the agent-loop hot path does one Map lookup after
+ * the first event of each workspace.
+ *
+ * An event without a session workspace (no agent / no header cwd) resolves
+ * to the explicit config or `null` — never a process-cwd probe: without a
+ * workspace there is nothing to probe FROM.
+ */
+export declare class HarnessResolver {
+    private readonly explicit;
+    private readonly cache;
+    constructor(explicit: string | undefined);
+    /**
+     * Resolve for one workspace root (the session cwd).
+     * @param cwd - the workspace root; `undefined` when the event carries no session.
+     * @returns the resolved `{HARNESS_DIR}` (explicit override, else the probe
+     * from the workspace root), or `null` when none resolves.
+     *
+     * Boundary (roadmap §7c): the probe stops AT the workspace root —
+     * `workspaceRoot = 探测起点` (the session cwd itself), so it never walks up
+     * beyond the session workspace (the `~/.mstar` global-collision special
+     * case), and it does NOT inherit the engine's default git-top-level
+     * boundary (the CLI surface). An empty/missing `cwd` keeps the current
+     * contract: `null`, never a process-cwd probe.
+     */
+    forWorkspace(cwd: string | undefined): string | null;
+    /**
+     * Resolve for one agent: the workspace root is the agent's session cwd.
+     * @param agent - the agent handle an event carries (structural read).
+     */
+    forAgent(agent: unknown): string | null;
+}
+/** The workspace root of one agent — the session cwd (structural read; never trusts the runtime shape). */
+export declare function sessionCwdOf(agent: unknown): string | undefined;
+/** The tool-execution actor of one fs-intent event, when it carries an agent. */
+export declare function actorAgentOf(actor: object | undefined): unknown;
+/**
+ * Map one engine `ValidationResult` to its lossless JSON view (`fix` omitted
+ * when absent so `additionalProperties: false` never sees an undefined key).
+ * The view interfaces live in `types.ts` (shared with the pre-step
+ * iteration-gate catalog row).
+ */
+export declare function iterationViolationView(v: ValidationResult): IterationGateViolationView;
+/** Map one engine gate (`GateResult`) to its JSON view. */
+export declare function iterationGateView(gate: GateResult): IterationGateListView;
+/**
+ * Build the dsh skill-filesystem registration payload from the plugin Config
+ * (single canonical mount). Semantics mirror the skill-filesystem
+ * `Config` contract: `skillRoots` → `customSkillDirs` (custom roots),
+ * `bundledSkillDir` → `bundledSkillDir` (bundled root). The provider is
+ * named `mstar` and default roots are excluded (`includeDefaultRoots: false`
+ * — the repository-plugin convention: an isolated provider must see only its
+ * explicit roots, so the mstar mount never claims the host app's own skills;
+ * without this the app's user/project skills would be re-discovered under
+ * the mstar provider). Returns `undefined` when nothing is configured — no
+ * registration happens.
+ *
+ * The bundled default is the package's OWN `harness-skills/` mirror (synced
+ * from the repo root by `bundle-assets` at build/postinstall; gitignored),
+ * resolved package-relative — NOT cwd-anchored — so a deployment launching
+ * from any cwd gets the bundled mount (this resolves the
+ * cwd-anchoring limitation for the shipped default; an explicit
+ * `bundledSkillDir` still wins).
+ * @param config - validated plugin configuration.
+ */
+export declare function skillLocalConfig(config: Config): SkillLocalConfig | undefined;

package/dist/gates/adapter.d.ts

@@ -0,0 +1,131 @@
+import { Service, type Context } from '@deepseek-ai/cordis';
+import type { AssignmentFields, GateResult, HostAdapter, IntegrationMergeLease, ValidationResult } from '@mstar-harness/engine';
+import type { ToolExecution } from '@deepseek-ai/dsh-tools';
+import type { HarnessResolver, Config } from './_shared.ts';
+import type { AgentFlowPairing } from './agent-flow.ts';
+/** Options for {@link DshHostAdapter}. */
+export interface DshHostAdapterOptions {
+    /**
+     * The per-workspace `{HARNESS_DIR}` resolver (explicit config wins; the
+     * probe never starts from the process cwd). The exec-bound gate paths
+     * resolve per the calling session's workspace.
+     */
+    readonly resolver: HarnessResolver;
+    /** The plugin Config the gates resolve enforcement + anti-recursion binding from. */
+    readonly config: Config;
+    /**
+     * The apply-scoped agent-flow pairing store (plan
+     * `20260811-panel-f4-timeliness` Task 1 — created by the entry `apply`,
+     * shared with the settle listener): passed to `recordDispatch` so an
+     * exec-bound dispatch registers `callId → dispatchRef` for the later
+     * post-execute settle pairing. Absent (host-adapter tests / direct
+     * construction) → no pairing registration (record-only).
+     */
+    readonly pairing?: AgentFlowPairing;
+    /**
+     * Log sink for `HostAdapter.log`. Defaults to the dsh ctx logger scoped
+     * `mstar/host-adapter` (dsh logger naming: `<scope>/<subject>`).
+     */
+    readonly log?: (level: 'info' | 'warn' | 'error', msg: string) => void;
+}
+/**
+ * The plugin's `HostAdapter` implementation (engine `host.ts` type-only
+ * contract) — the HOST-FACING facade over the gate
+ * internals: `host: 'dsh'`, `log` → dsh ctx logger, and the optional hooks
+ * wired to the SAME code paths the in-plugin gates use, so host hooks and
+ * gates share ONE validation path:
+ *
+ * - `beforeStatusWrite(path, doc)` — validates the incoming document when
+ *   the host provides it (the write's content — the opencode consumer
+ *   convention for this engine hook), else the current on-disk document at
+ *   `path` via the gate's single-read `validateStatusDoc` semantics (missing
+ *   file = first create = pass). Both inputs flow through
+ *   `validateStatusValue` — the same pipeline the fs-intent gate runs, so
+ *   codes match by construction. Returns the FIRST violation: the engine
+ *   hook shape is one `ValidationResult`; the gate's full violation list
+ *   stays available on the fs-intent slot.
+ * - `beforeDispatch(assignment)` — the dispatch gate validation path
+ *   (engine `composeDispatchGate` — fields + branch gate + anti-recursion —
+ *   plus worktree L1/L2 checks; read-only roles skip the branch gate). The lease gate
+ *   stays listener-side: it binds the ToolExecution context (session id)
+ *   this hook's contract does not carry. The parsed `AssignmentFields` form
+ *   is normalized to the engine's own header grammar (lossless — the
+ *   parsers read exactly these labels) and gated through the same text path.
+ *   Enforcement is applied like the listener (opencode parity): the
+ *   returned GateResult carries `hardBlocked` so a refusal-capable host can
+ *   refuse the dispatch.
+ * - `beforeMerge(lease)` — thin wrapper over the engine
+ *   `validateIntegrationMergeLease` (reserve/validate the integration merge
+ *   lease; the reservation WRITE into status.json is a P3 seam).
+ */
+export declare class DshHostAdapter extends Service implements HostAdapter {
+    /** Engine host identity (`HostId` union). */
+    readonly host: "dsh";
+    private readonly resolver;
+    private readonly config;
+    private readonly pairing;
+    private readonly logSink;
+    constructor(ctx: Context, options: DshHostAdapterOptions);
+    /**
+     * `HostAdapter.log` — the adapter's own reporting channel (the gates keep
+     * their scoped loggers; this is the host-facing sink).
+     * @param level - log level.
+     * @param msg - message.
+     */
+    log(level: 'info' | 'warn' | 'error', msg: string): void;
+    /**
+     * Shared status-gate core (plugin-internal): the fs-intent listeners and
+     * the `beforeStatusWrite` on-disk fallback route through this method —
+     * ONE validation code path. Missing file = first create = pass (the
+     * intent waterfall carries no incoming content, so the vetoable signal is
+     * the pre-write on-disk state).
+     * @param statusPath - the canonical `{HARNESS_DIR}/status.json` path.
+     */
+    statusGate(statusPath: string): GateResult;
+    /**
+     * Shared dispatch-gate core (plugin-internal): the `tools/pre-execute`
+     * listener and `beforeDispatch` route through this method — ONE
+     * validation code path (field gate + anti-recursion + branch gate +
+     * worktree L1/L2 checks; read-only roles skip the branch gate). The
+     * listener passes `exec` so the lease gate (ToolExecution-bound: session
+     * id, in-flight call) joins the same verdict; the host hook has no exec
+     * context and covers the field/branch/anti-recursion/worktree path.
+     * @param prompt - the Assignment text (engine header grammar).
+     * @param exec - the in-flight delegation tool call (listener path only).
+     * @param hard - the caller's ONE `resolveDispatchHard` resolution (qc1
+     * F-002 / qc2 F-3 / qc3 F-002 fix-wave): passed in so the record block and
+     * the caller's enforcement decision share a single compass resolution;
+     * when omitted (external callers) the adapter resolves it itself.
+     */
+    dispatchGate(prompt: string, exec?: ToolExecution, hard?: boolean): GateResult;
+    /**
+     * `HostAdapter.beforeStatusWrite` — see the class doc for the doc-first /
+     * on-disk-fallback semantics. Never throws; a failing gate maps to its
+     * FIRST violation (severity/code/message/fix/aliases preserved — failing
+     * gates always carry ≥1 violation), a passing gate to
+     * `host.beforeStatusWrite.ok` (the engine test convention for this hook).
+     * @param path - the status.json target path.
+     * @param doc - the document about to be written (undefined → validate the
+     * on-disk document at `path`).
+     */
+    beforeStatusWrite(path: string, doc: unknown): Promise<ValidationResult>;
+    /**
+     * `HostAdapter.beforeDispatch` — the dispatch gate validation path (see
+     * the class doc). Accepts the raw Assignment text (full fidelity: the
+     * `Enforcement` header flag participates in enforcement resolution) or the
+     * parsed `AssignmentFields` (engine-typed hook input; normalized to the
+     * engine's header grammar before gating). Returns the enforced GateResult
+     * — `hardBlocked` mirrors the `tools/pre-execute` deny decision under the
+     * same enforcement resolution.
+     * @param assignment - raw Assignment text or parsed header fields.
+     */
+    beforeDispatch(assignment: AssignmentFields | string): Promise<GateResult>;
+    /**
+     * `HostAdapter.beforeMerge` — reserve/validate the integration merge
+     * lease. Thin wrapper over the engine `validateIntegrationMergeLease`
+     * (the engine owns the lease shape; the reservation write into
+     * `{HARNESS_DIR}/status.json` is a P3 seam).
+     * @param lease - the `metadata.integration_merge_lease` object.
+     */
+    beforeMerge(lease: IntegrationMergeLease): Promise<GateResult>;
+}

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

@@ -0,0 +1,320 @@
+import { type Context } from '@deepseek-ai/cordis';
+import type { AgentFlowView } from '../types.ts';
+import type { Config } from './_shared.ts';
+/** The agent-flow ledger file name under `{HARNESS_DIR}`. */
+export declare const AGENT_FLOW_FILE = "agent-flow.jsonl";
+/** Truncation bound: the ledger keeps only the most recent events. */
+export declare const AGENT_FLOW_MAX_EVENTS = 500;
+/** Default read limit (the catalog passes 50 per spec §2.2). */
+export declare const AGENT_FLOW_DEFAULT_LIMIT = 50;
+/**
+ * The append size gate (qc2 F-1 / qc3 F-001/003 — fix-wave): the truncation
+ * read-modify-write runs only when the file exceeds ~500 lines' typical
+ * size (conservative ≈ 500 × 128 B average line); smaller files stay
+ * append-only. The bound is therefore approximate ("~500 events") — a file
+ * of unusually tiny events can grow past 500 lines under the gate until its
+ * BYTES cross the threshold (documented tradeoff; the gate keeps the common
+ * small-file append path free of a full read per dispatch).
+ */
+export declare const AGENT_FLOW_SIZE_GATE_BYTES: number;
+/** Logger label for the agent-flow ledger (dsh logger naming: `<scope>/<subject>`). */
+export declare const AGENT_FLOW_LOGGER = "mstar/agent-flow";
+/**
+ * The settle seam name — the dsh-tools registry's `tools/post-execute`
+ * waterfall. VERIFIED to be dispatched by the real registry for every tool
+ * call (`runPostExecute` → `postExecute`, upstream source; pinned by the
+ * real-call probe in `tests/agent-flow.spec.ts`), so settles are no longer
+ * host-emission-dependent (plan `20260811-panel-f4-timeliness` Task 1 — the
+ * old "not part of the verified surface" assumption is obsolete).
+ */
+export declare const SETTLE_SEAM = "tools/post-execute";
+/**
+ * The once-per-apply settle-pairing trace (plan `20260811-panel-f4-timeliness`
+ * Task 1). Historical name `SETTLE_SEAM_UNAVAILABLE_NOTE` (qc1 F-105 / qc2
+ * N-002 fix-wave): the old name claimed the seam was UNAVAILABLE, which the
+ * message itself refutes — the seam IS a verified part of the registry
+ * surface, so the constant was renamed to the accurate `PAIRING` name. The
+ * message states the VERIFIED pairing facts: the seam is emitted by the
+ * registry; foreground dispatch calls settle via it, background subagents
+ * settle via `ctx.jobs.onJobDone` pairing; only unpaired payloads stay
+ * dispatch-only (never fabricated settlement). Logged ONCE per logger binding
+ * (≈ once per apply — the same module-level flag, qc1 F-006) when the pairing
+ * listener is registered.
+ */
+export declare const SETTLE_SEAM_PAIRING_NOTE = "settle seam \"tools/post-execute\" IS part of the verified dsh-tools registry surface (runPostExecute dispatches it for every tool call) \u2014 foreground dispatch calls settle here, background subagents settle via ctx.jobs.onJobDone pairing; only UNPAIRED payloads (non-dispatch tools, calls outside the apply-scoped pairing window) stay dispatch-only \u2014 never a fabricated settle";
+/** Dispatch verdict vocabulary (spec §2.1.3). */
+export type DispatchVerdict = 'ok' | 'advisory' | 'denied';
+/** Settle outcome vocabulary (spec §2.1.3). */
+export type SettleOutcome = 'ok' | 'error' | 'denied';
+/**
+ * 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).
+ */
+export type AgentFlowEvent = {
+    v: 1;
+    ts: number;
+    kind: 'dispatch';
+    /** The dispatching session's stable id (exec.agent.id; host-hook path has no exec → absent). */
+    agent?: string;
+    /** Assignment `Execute as` ('' when missing). */
+    role: string;
+    /** planIdOf(header): `Plan Path` / `SDD dir` / `plan_id` basename. */
+    planId?: string;
+    /** Body `Task N` best-effort extraction (taskIdOf). */
+    taskId?: string;
+    /** Assignment `Task category`. */
+    taskCategory?: string;
+    /** Gate verdict derivation: no violations → ok; hard + violations → denied; else advisory. */
+    verdict: DispatchVerdict;
+    /** resolveDispatchHard result (recorded unconditionally, incl. hard denies). */
+    hard: boolean;
+} | {
+    v: 1;
+    ts: number;
+    kind: 'settle';
+    /** The settled session's stable id (the paired dispatch's agent). */
+    agent?: string;
+    outcome: SettleOutcome;
+    durationMs?: number;
+    /**
+     * The PAIRED dispatch's identity (plan `20260811-panel-f4-timeliness`
+     * Task 1) — same field names + semantics as the dispatch event:
+     * `role` is the Assignment `Execute as` ('' when missing), `planId` /
+     * `taskId` the plan + `Task N` tags. Written for every paired settle;
+     * ABSENT on unpaired (legacy) settles — the client pairs on identity
+     * presence. The registry background-task id is deliberately NOT
+     * written here (`taskRef` is reserved as the distinct field name if a
+     * future audit needs it — it never collides with `taskId`).
+     */
+    role?: string;
+    planId?: string;
+    taskId?: string;
+};
+/**
+ * The identity of one recorded dispatch, carried by the pairing store so a
+ * later completion (post-execute settle / onJobDone terminal) can record a
+ * settle carrying the SAME identity fields as its dispatch event.
+ */
+export interface AgentFlowDispatchRef {
+    /** The resolved `{HARNESS_DIR}` the dispatch recorded into (settles record into the same ledger). */
+    harnessDir: string;
+    /** The dispatching session's stable id ('' when the exec carried none). */
+    agent?: string;
+    /** Assignment `Execute as` ('' when missing — the dispatch event's grammar). */
+    role: string;
+    /** `planIdOf(header)` — the dispatch event's grammar. */
+    planId?: string;
+    /** `taskIdOf(prompt)` — the Assignment `Task N` tag, NOT a registry task id. */
+    taskId?: string;
+}
+/**
+ * The apply-scoped pairing store (plan `20260811-panel-f4-timeliness` Task 1,
+ * decision D1 — created in the entry `apply`, same lifetime as the catalog
+ * cache; an HMR restart resets it, and completions outside the window stay
+ * unpaired → no settle, the documented honest degrade). Maps are keyed by
+ * the TWO verified pairing keys: the tool-call `callId` (pre → post-execute)
+ * and the registry background-task id (post-execute background shape →
+ * `onJobDone` terminal).
+ */
+export interface AgentFlowPairing {
+    /**
+     * The agent-namespaced call key → the dispatch it recorded (populated by
+     * `recordDispatch` when an exec is present). Key = `${sessionId}\u0000${callId}`
+     * (qc1 F-101 fix-wave): a raw `ToolExecution.callId` is NOT globally unique
+     * in one process — dsh runs many sessions concurrently and upstream mints
+     * per-message ids (`call-${index}`), so the dispatching session id must
+     * namespace the key or session B's same-id call could overwrite session A's
+     * pairing and mis-pair A's settle into B's dispatchRef. Consumed (deleted)
+     * by the post-execute branch — the map holds only in-flight calls.
+     */
+    dispatchByCallId: Map<string, AgentFlowDispatchRef>;
+    /** Registry background-job id (`JobSnapshot.id`) → the dispatch that started it (populated by the post-execute background branch; consumed by `recordTaskSettle`). */
+    dispatchByTaskId: Map<string, AgentFlowDispatchRef>;
+}
+/** Module-scoped log sink (bound to `mstar/agent-flow` by the entry at apply). */
+type AgentFlowLogSink = (level: 'info' | 'warn' | 'error', message: string) => void;
+/**
+ * Module-scoped catalog-invalidation hook (plan `20260811-panel-f4-timeliness`
+ * Task 1 — the `invalidateCatalog` 挂钩 that Task 2 consumes): called with
+ * the affected `{HARNESS_DIR}` after every SUCCESSFUL ledger record
+ * (`recordDispatch` / `recordSettle`). The entry binds the real invalidation
+ * closure at apply (Task 2 shipped the apply-scoped harnessDir → cache-key
+ * reverse-map closure in `index.ts` — see `createCatalogInvalidation`);
+ * unbound → no-op. Never throws into the record path.
+ */
+type AgentFlowInvalidator = (harnessDir: string) => void;
+/**
+ * Bind the module's catalog-invalidation hook (plan
+ * `20260811-panel-f4-timeliness` Task 1 — same pattern as
+ * {@link setAgentFlowLogger}; the entry binds at apply; Task 2 shipped the
+ * real binding — the apply-scoped harnessDir → cache-key reverse-map
+ * closure in `index.ts`).
+ * @param invalidate - the hook (`undefined` clears the binding).
+ * @returns the PREVIOUS hook (tests restore it in a `finally`).
+ */
+export declare function setAgentFlowInvalidator(invalidate: AgentFlowInvalidator | undefined): AgentFlowInvalidator | undefined;
+/**
+ * Bind the module's log sink (called once at apply; tests may rebind to
+ * capture ledger logs). Rebinding RESETS the once-per-apply settle trace
+ * flag — each binding is a fresh "apply" (production binds once; tests bind
+ * per case for deterministic capture).
+ * @param sink - the sink (entry binds `ctx.logger('mstar/agent-flow')`);
+ * `undefined` clears the binding (restores the pre-bind no-op state).
+ * @returns the PREVIOUS sink (tests restore it in a `finally`).
+ */
+export declare function setAgentFlowLogger(sink: AgentFlowLogSink | undefined): AgentFlowLogSink | undefined;
+/**
+ * Best-effort extraction of the targeted `Task N` from the Assignment BODY
+ * (spec §2.1.1 — `taskIdOf`). The engine `assignmentHeaderRegion` boundary is
+ * reused: only text AFTER the header region is scanned, so a `## Task N`
+ * example quoted in the header never resolves a task id. Only a LEVEL-2
+ * heading (`^## Task N`) matches (qc2 F-8: an example or sub-heading at
+ * another depth before the real task must not resolve — lower false-hit
+ * surface); normalized to `T<n>` (matches the panel render `planId#taskId`,
+ * e.g. `20260810-x#T2`).
+ * @param prompt - the full Assignment text.
+ */
+export declare function taskIdOf(prompt: string): string | undefined;
+/**
+ * Record one dispatch event (spec §2.1.3). Fully try/catch-contained — NEVER
+ * throws into the gate; a failing record logs only (`mstar/agent-flow`).
+ * Verdict derivation (ok/advisory/denied, incl. hard denies) and the header
+ * identity derivation (role / planId / taskId / taskCategory) reuse the gate's
+ * own parsers — one grammar.
+ *
+ * Pairing (plan `20260811-panel-f4-timeliness` Task 1): when the input
+ * carries an `exec` AND the apply-scoped `pairing` store, the successful
+ * record registers the agent-namespaced key `${sessionId}\u0000${callId}` →
+ * dispatchRef (the full dispatch identity), so a later
+ * `tools/post-execute` for the same call can settle with the SAME identity
+ * (qc1 F-101 fix-wave: the session id namespaces the key — a raw callId is
+ * not globally unique across sessions in one process). The pairing registers
+ * only after the ledger append SUCCEEDED — a failed record never pairs to a
+ * phantom dispatch. An exec-less record (host-hook path) has no callId → no
+ * pairing. The pairing sub-path has its OWN catch scope (qc1 F-106 / qc2
+ * N-001 / qc3 F-006 fix-wave): a `Map.set` throw must not log "record
+ * failed" after the dispatch was already appended.
+ * @param input - harness dir + exec (agent id) + Assignment text + the gate's
+ * violations + the hard-enforcement resolution + the apply-scoped pairing
+ * store (the adapter passes its own; direct callers may omit it).
+ */
+export declare function recordDispatch(input: {
+    harnessDir: string;
+    exec?: unknown;
+    prompt: string;
+    violations: readonly unknown[];
+    hard: boolean;
+    pairing?: AgentFlowPairing;
+}): void;
+/**
+ * Record one settle event (spec §2.1.3). Fully try/catch-contained; a failing
+ * record logs only. Callers resolve the harness dir from the PAIRED dispatch
+ * (the pairing store's dispatchRef — never a payload probe).
+ * @param input - harness dir + agent id + outcome + optional duration + the
+ * PAIRED dispatch's identity (`role`/`planId`/`taskId` — same field names +
+ * semantics as the dispatch event; written for every paired settle, so the
+ * client can exactly pair the settle back to its dispatch).
+ */
+export declare function recordSettle(input: {
+    harnessDir: string;
+    agent?: string;
+    outcome: SettleOutcome;
+    durationMs?: number;
+    role?: string;
+    planId?: string;
+    taskId?: string;
+}): 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
+ * the role × outcome summary over the SAME window (so `by role` counts sum
+ * to the event count). A MISSING ledger file returns the EMPTY view
+ * `{ events: [], summary: [] }` — recording hasn't started (it begins at
+ * plan merge), and the panel renders its "no actual dispatches yet" empty
+ * state instead of an evidence-missing degrade; only an UNREADABLE file
+ * returns null (advisory degrade — the catalog renders no agent-flow line).
+ * Malformed lines are skipped, never fatal.
+ * @param harnessDir - the resolved `{HARNESS_DIR}`.
+ * @param limit - explicit window bound: `undefined` → `AGENT_FLOW_DEFAULT_LIMIT`;
+ * otherwise `Math.max(0, Math.floor(limit))` — `0` requests the EMPTY window.
+ */
+export declare function readAgentFlow(harnessDir: string, limit?: number): AgentFlowView | null;
+/**
+ * The `tools/post-execute` settle pairing (plan `20260811-panel-f4-timeliness`
+ * Task 1 — replaces the old defensive payload probing): the VERIFIED
+ * dsh-tools registry dispatches this seam for every tool call
+ * (`runPostExecute` → `postExecute`, upstream source), so the listener only
+ * decides whether a completion signal exists for the PAIRED dispatch:
+ *
+ * - non-dispatch tool (`exec.name` ∉ Config `dispatchTools`) → nothing;
+ * - dispatch tool whose agent-namespaced call key
+ *   (`${sessionId}\u0000${callId}`, qc1 F-101 fix-wave) is not in the pairing
+ *   store (HMR reset, host-hook dispatch, non-gate path) → nothing (warned
+ *   once per registration — honest degrade, never fabricated settlement);
+ * - `result.isError === true` OR an `error` payload present → settle `error`
+ *   immediately (fabrication guard, qc2 F-001 / qc3 F-003a — the dispatch
+ *   call failed; a result carrying `error` without `isError` never settles ok);
+ * - successful `result.value` shape `{ kind: 'background', taskId }` with a
+ *   valid taskId → store `taskId → dispatchRef` (the real settle arrives via
+ *   `ctx.jobs.onJobDone`); `{ kind: 'background' }` WITHOUT a valid taskId
+ *   → nothing mappable (no settle, qc3 F-003b);
+ * - `{ kind: 'continuable', subagentId }` → no terminal signal this round →
+ *   no settle (documented limit — the child owns its turns);
+ * - any other successful value (foreground `{ kind: 'foreground', … }`
+ *   included) → settle `ok` (the call completed synchronously).
+ * The consumed `dispatchByCallId` entry is DELETED after the branch resolves
+ * the call (map pruning, qc1 F-102 / qc2 F-002 / qc3 F-002 — each callId
+ * pairs exactly once; the map holds only in-flight calls).
+ *
+ * The waterfall MUST be delegated via `next()` on every path — returning
+ * without calling `next` bails the chain and breaks every tool call. A
+ * throwing record never propagates.
+ *
+ * Cordis typing note: `ctx.on` only accepts declared event keys and
+ * `tools/post-execute` is undeclared — the registration casts through the
+ * runtime-accepted event-name string (the event bus dispatches any name).
+ * @param ctx - registrant context (fiber disposal unwinds the listener).
+ * @param config - the plugin Config (dispatch-tool matching).
+ * @param pairing - the apply-scoped pairing store (dispatchByCallId read,
+ * dispatchByTaskId written by the background branch).
+ */
+export declare function registerSettleListener(ctx: Context, config: Config, pairing: AgentFlowPairing): void;
+/**
+ * The structural read of the dsh-jobs terminal snapshot the pairing consumes
+ * (plan `20260811-panel-f4-timeliness` Task 1). The `ctx.jobs.onJobDone`
+ * contract was verified against the upstream `@deepseek-ai/dsh-jobs`
+ * `types.ts`: `JobDoneListener = (snapshot, owner) => …`, terminal
+ * `snapshot.status` ∈ `completed | killed | failed`, `startedAt`/`finishedAt`
+ * are epoch ms (`finishedAt` absent while running). Structural (no runtime or
+ * type import of the optional dsh-jobs seam — the plugin treats it as an
+ * optional service, wired via `ctx.inject(['jobs'])`).
+ */
+export interface TaskDoneSnapshot {
+    /** The registry-issued task id (`<kind>-N`, e.g. `subagent-1`). */
+    id: string;
+    /** Terminal lifecycle status: `completed | killed | failed`. */
+    status: string;
+    /** Epoch ms when the task was registered. */
+    startedAt?: number;
+    /** Epoch ms when the task settled. */
+    finishedAt?: number;
+}
+/**
+ * Record the settle for one background-task terminal (plan
+ * `20260811-panel-f4-timeliness` Task 1 — the `ctx.jobs.onJobDone` path):
+ * the snapshot's task id must hit the pairing store's `dispatchByTaskId`
+ * (populated by the post-execute background branch) — a miss records NOTHING
+ * (honest degrade, never fabricated). Outcome mapping: `completed → ok` /
+ * `killed → denied` / `failed → error`; `durationMs = finishedAt − startedAt`
+ * when both are present. After a SUCCESSFUL settle the consumed
+ * `dispatchByTaskId` entry is deleted (map pruning, qc1 F-102 / qc2 F-002 /
+ * qc3 F-002 — the map holds only in-flight tasks; a contract-violating
+ * non-terminal snapshot records nothing and KEEPS the entry so a later real
+ * terminal can still settle). Fully contained — never throws into the task
+ * registry's listener notification.
+ * @param snapshot - the terminal task snapshot (structural read).
+ * @param pairing - the apply-scoped pairing store.
+ */
+export declare function recordTaskSettle(snapshot: TaskDoneSnapshot, pairing: AgentFlowPairing): void;
+export {};