@try-works/dsh-recursive-mode 0.3.0 → 0.4.0

package/lib/job-log.d.ts

@@ -0,0 +1,34 @@
+import type { JobRunResult } from './jobs-runner.ts';
+/** One recorded run, as the board reads it. */
+export interface JobLogRecord {
+    at: string;
+    /** The producer kind: `lint`, `worktree`, `delegation`. */
+    kind: string;
+    label: string;
+    /** False when there was no registry and the work ran inline. */
+    tracked: boolean;
+    jobId?: string;
+    status: 'completed' | 'killed' | 'failed';
+    detail?: string;
+}
+/** Where a run's job log lives, beside its other run-layer records. */
+export declare function jobsLogPath(root: string, runId: string): string;
+/**
+ * Append one run to the log. Never throws: an unwritable log is not a reason for a completed
+ * lint to be reported as a failure.
+ *
+ * @returns true when the line was written, false when it could not be — so a caller that
+ * cares can say so without this function deciding for it.
+ */
+export declare function recordJobRun(root: string, runId: string, entry: {
+    kind: string;
+    label: string;
+    result: JobRunResult<unknown>;
+}): boolean;
+/** Read a run's job log. A missing or damaged file reads as empty — never an error. */
+export declare function readJobRuns(root: string, runId: string): JobLogRecord[];
+/**
+ * A board-facing rendering: one line per run, newest last, with the untracked and
+ * non-completed cases called out rather than implied.
+ */
+export declare function renderJobLog(root: string, runId: string): string;

package/lib/jobs-runner.d.ts

@@ -0,0 +1,105 @@
+/**
+ * T10 — track a long operation as a NATIVE job.
+ *
+ * WHY. `lintRun`, `createLinkedWorktree` and `delegateReview` run synchronously in-block,
+ * so a hung one is invisible on the board and unstoppable from it. The native registry
+ * already owns identity, lifecycle state, a bounded output ring and a kill switch; the
+ * plugin should not invent any of that, so this adapts the plugin's long operations onto
+ * `ctx.jobs` instead of building a parallel notion of "running".
+ *
+ * ⚠ AN OPTIONAL SERVICE, DEGRADED HONESTLY. `ctx.jobs` is absent in a composition that does
+ * not mount the registry. In that case the work runs DIRECTLY and the result says
+ * `tracked: false` — because failing a lint (or a worktree create) merely because no board
+ * is attached would be a worse failure than losing the progress display. The caller can
+ * always tell which happened, so "untracked" is never silently passed off as "tracked".
+ *
+ * ⚠ A CANCELLED OPERATION SETTLES `killed`, NOT `failed`. The distinction is the whole
+ * point of exposing a kill switch: "the operator stopped this" and "this broke" call for
+ * different responses, and a board that renders a deliberate kill as a failure teaches
+ * people to distrust the kill switch.
+ *
+ * ⚠ THE TIMEOUT IS A KILL, NOT A HANG. A deadline reached means the registry's `cancel` is
+ * invoked and the outcome is reported as killed with the reason — so a hung operation
+ * cannot leave a caller waiting forever on a promise nobody owns.
+ *
+ * Types are structural (the plugin's established seam style), so this module depends on the
+ * SHAPE of the registry rather than on the package, and a test can drive it with a fake
+ * without mounting the real service.
+ */
+/** The producer face the registry hands `run`: identity plus the ring and progress writers. */
+export interface JobHandleLike {
+    readonly id: string;
+    append(text: string, options?: {
+        stream?: string;
+    }): void;
+    updateProgress(line: string): void;
+}
+/** How a job ended. Mirrors the registry's own vocabulary verbatim. */
+export interface JobOutcomeLike {
+    status: 'completed' | 'killed' | 'failed';
+    detail?: string;
+    result?: string;
+}
+export interface JobHooksLike {
+    cancel(reason?: string): void;
+    done: Promise<JobOutcomeLike>;
+}
+export interface JobSpecLike {
+    kind: string;
+    label: string;
+    owner?: unknown;
+    outputLimitBytes?: number;
+    run(job: JobHandleLike): JobHooksLike;
+}
+export interface JobsRegistryLike {
+    start(spec: JobSpecLike): string;
+}
+/** What one tracked run produced. */
+export interface JobRunResult<T> {
+    /** False when no registry was available and the work ran inline. */
+    tracked: boolean;
+    /** The registry-issued id, when there was one. */
+    jobId?: string;
+    status: 'completed' | 'killed' | 'failed';
+    /** The terminal reason, for the board's status line. */
+    detail?: string;
+    /** The operation's own value; absent when it was killed or threw. */
+    value?: T;
+    /** The error message when the operation threw. */
+    error?: string;
+}
+export interface TrackedRunOptions<T> {
+    /** Producer kind, also the id prefix: `lint`, `worktree`, `delegation`. */
+    kind: string;
+    /** One-line, model-facing label. */
+    label: string;
+    owner?: unknown;
+    /** A deadline. Reaching it CANCELS the work rather than abandoning it. */
+    timeoutMs?: number;
+    /** The work. It receives a progress reporter and an abort signal to honour. */
+    run: (context: {
+        report: (line: string) => void;
+        signal: AbortSignal;
+    }) => Promise<T>;
+    /** Render the value into the job's terminal result line. */
+    render?: (value: T) => string;
+}
+/** The reason used when a deadline cancelled the work. */
+export declare const TIMEOUT_REASON = "timed out";
+/**
+ * Run `options.run` as a native job when a registry is available, inline when it is not.
+ *
+ * Never throws for a failure of the WORK: the outcome carries `status: 'failed'` and the
+ * message, because a caller tracking a job wants to read what happened rather than catch it.
+ */
+export declare function runTracked<T>(jobs: JobsRegistryLike | null | undefined, options: TrackedRunOptions<T>): Promise<JobRunResult<T>>;
+/** The abort reason as a string, whatever the caller passed. Exported for a caller that
+ * turns an abort into its own action (T39 interrupts the child on a delegation kill). */
+export declare function abortReason(signal: AbortSignal): string;
+/**
+ * A board-facing one-liner for one run: what happened, and whether it was even tracked.
+ *
+ * Says "untracked" OUT LOUD rather than omitting the field, so a reader never has to infer
+ * from a missing id whether the job ran without a board or the board lost it.
+ */
+export declare function describeJobRun<T>(result: JobRunResult<T>): string;

package/lib/json-safe.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Lossless-JSON projection for tool results (FU-9 defect fix).
+ *
+ * ⚠ THE DEFECT THIS EXISTS FOR, measured live: the host refused a review result with
+ *
+ *     Error: tool "recursive_review" returned invalid output: value is not lossless JSON
+ *     ToolOutputError, code INVALID_TOOL_OUTPUT
+ *
+ * The tool returned its service result through a TYPE CAST — `return outcome as unknown as JsonValue` — and a
+ * cast is a promise the compiler cannot keep. The outcome carries live objects: the delegation's per-round
+ * `result` is whatever the host returned for a child run, which in a real session holds an Agent or a provider
+ * seam, and neither survives `JSON.stringify`.
+ *
+ * ⚠ WHY A GENERAL PROJECTION RATHER THAN STRIPPING THE KNOWN FIELD: I could delete the `result` property and
+ * pass this round's test, but the next field the engine adds would break the tool again — and the failure mode
+ * is a REFUSED RESULT, which tells the caller nothing about the work that was done. A projection that handles
+ * cycles, functions and class instances is correct for every future field rather than for this one.
+ *
+ * ⚠ AND IT IS HONEST ABOUT WHAT IT DROPS: a function becomes nothing, a cycle becomes a marker string, and a
+ * class instance becomes its own enumerable properties. Nothing is invented, and nothing silently vanishes
+ * without a trace in the output — a dropped key simply is not there, which is what "lossless JSON" means.
+ */
+import type { JsonValue } from '@deepseek-ai/dsh-util-values';
+/** What a reference to an already-visited object becomes, so a cycle is visible rather than dropped. */
+export declare const CIRCULAR_MARKER = "[circular]";
+/**
+ * Project any value into something `JSON.stringify` accepts, without throwing.
+ *
+ * Returns `null` for values that have no JSON form at all (a lone function, a symbol, `undefined`), which the
+ * caller decides how to present. Objects are walked by their OWN ENUMERABLE keys, so a class instance projects
+ * to its data and its methods are left behind — which is exactly what an Agent or a seam needs to become.
+ */
+export declare function toLosslessJson(value: unknown, seen?: WeakSet<object>): JsonValue | null;

package/lib/lock.d.ts

@@ -85,6 +85,48 @@ export declare function getAllStaleReceipts(runDir: string): StaleDownstream[];
  * next legal phase, completion, and stale receipts.
  */
 export declare function validateChain(runDir: string, runId: string): LockChainResult;
+/** Why a receipt chain failed verification. */
+export type ReceiptChainBreakKind = 'receipt-hash-mismatch' | 'prerequisite-hash-mismatch' | 'missing-prerequisite-receipt' | 'malformed-previous-hash';
+/** One broken link, naming the phase at fault and both values involved. */
+export interface ReceiptChainBreak {
+    /** The artifact whose receipt is at fault. */
+    phase: string;
+    kind: ReceiptChainBreakKind;
+    /** A sentence naming both values, so the break is diagnosable without a debugger. */
+    detail: string;
+}
+export interface ReceiptChainResult {
+    runId: string;
+    ok: boolean;
+    /** How many receipts were examined (absent phases are skipped, not counted). */
+    checked: number;
+    breaks: ReceiptChainBreak[];
+}
+/**
+ * T32 — verify a run's receipts against each other and against the artifacts they
+ * cite. Closes review finding E: the receipt hash was COMPUTED on every lock and
+ * never re-derived, so `previous_receipt_hash` was written and read by nothing.
+ *
+ * READ-ONLY, deliberately. The chain is evidence, and a verification that rewrites
+ * what it verifies is worthless — so this never repairs, re-hashes or touches a
+ * receipt, and a caller can run it as often as it likes.
+ *
+ * WHAT IT CHECKS, and what it refuses to claim. `previous_receipt_hash` chains to the
+ * SAME artifact's previous receipt, and there is exactly one receipt file per
+ * artifact, so the receipt it names has been overwritten and its LINKAGE cannot be
+ * verified from disk. Rather than assert a linkage it cannot prove, this checks:
+ *   1. receipt integrity — the stored `receipt_hash` must equal the hash recomputed
+ *      from the receipt's own fields (catches an edit after the fact);
+ *   2. prerequisite agreement — each recorded `prerequisite_hashes[p]` must equal
+ *      p's CURRENT artifact hash (catches an upstream changed after locking);
+ *   3. gaps — a receipt citing a prerequisite that has no receipt at all;
+ *   4. a well-formedness check on `previous_receipt_hash`, which the writer could
+ *      only ever produce as a sha256 hex digest or null.
+ *
+ * Never throws: an unreadable receipt is skipped, and a missing run directory is an
+ * empty result rather than an error.
+ */
+export declare function validateReceiptChain(runDir: string, runId: string): ReceiptChainResult;
 /**
  * Python json.dumps(obj, sort_keys=True, separators=(', ', ': '), ensure_ascii=True)
  * compact serialization. Exported for parity testing against the Python oracle.

package/lib/memory-feedback.d.ts

@@ -0,0 +1,52 @@
+/** Where the machine-owned counters live — inside the memory plane, but never a shard a person writes. */
+export declare const FEEDBACK_FILE = "memory/.feedback.json";
+/** Where a run records what it was shown. */
+export declare const INJECTIONS_FILE = "memory-injections.json";
+/** One entry the agent was shown, as the run recorded it. */
+export interface InjectionRecord {
+    /** The entry's source path, which is also its identity in the counters. */
+    source: string;
+    title: string;
+    /** The phase it was injected for. */
+    phase: string;
+    score: number;
+}
+export interface FeedbackCounter {
+    /** Times an entry was injected for a phase that then locked on that round. */
+    applied: number;
+    /** Times an entry was injected for a phase that had to come round again before it locked. */
+    contradicted: number;
+}
+export type FeedbackBook = Record<string, FeedbackCounter>;
+/** Read the counters. A missing or unreadable file is an empty book, never an error. */
+export declare function readFeedback(root: string, readFile?: (path: string) => string | null): FeedbackBook;
+/** Read what a run recorded being shown. */
+export declare function readInjections(runDir: string, readFile?: (path: string) => string | null): InjectionRecord[];
+/**
+ * Record what the run was shown, MERGED by (source, title, phase).
+ *
+ * ⚠ MERGED RATHER THAN APPENDED, because a phase can be re-entered while it is still DRAFT and the same
+ * entries are selected again. Appending would count one decision as four, and the counters exist to be
+ * evidence. The highest score seen wins, since that is what the agent was most recently shown.
+ */
+export declare function recordInjection(runDir: string, entries: readonly {
+    source: string;
+    title: string;
+    score: number;
+}[], phase: string, write?: (path: string, content: string) => void, readFile?: (path: string) => string | null): InjectionRecord[];
+/**
+ * Settle a finished run against its own outcome and return the updated book.
+ *
+ * ⚠ THE OUTCOME SIGNAL, and it is deliberately modest: an entry injected for a phase that **locked** was
+ * APPLIED; an entry injected for a phase that had to come round again before it locked is CONTRADICTED — the
+ * memory did not carry the phase the first time. That is a real signal available from the run's own files,
+ * and it is not dressed up as more than that: no model was trained, and an entry is never deleted for losing.
+ */
+export declare function settleInjections(root: string, runDir: string, lockedPhases: readonly string[], write?: (path: string, content: string) => void, readFile?: (path: string) => string | null): FeedbackBook;
+/**
+ * What the counters are worth in the ranking: `applied - contradicted`, clamped to one step.
+ *
+ * Clamped because a single long-lived entry should not be able to dominate the ranking forever, and because
+ * the counter is evidence about retrieval, not a verdict about the lesson.
+ */
+export declare function feedbackBonus(book: FeedbackBook, source: string): number;

package/lib/memory-select.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Explainable memory selection (FU-13 P1/P2) — the reference loader's good idea, with the reasons attached.
+ *
+ * ⚠ THE REFERENCE, measured: `recursive-training-loader.py` (21.1 KB) *"scores memory docs by relevance to the
+ * current task, reads the most relevant docs, scores individual items, and returns formatted context for the
+ * agent"* — progressive scoring, which is the right idea. Its weakness is that the ranking is OPAQUE: it
+ * returns context, not reasons, so "why did the agent get this?" has no answer and a bad ranking cannot be
+ * debugged or tuned.
+ *
+ * ⚠⚠ AND THE DEFECT THIS MODULE WAS REWRITTEN TO FIX. The first version asserted that one component — the
+ * query score — came from production, and then ranked on THREE OTHER SIGNALS OF ITS OWN: it matched the last
+ * path SEGMENT where production matches the whole path, capped the path weight where production does not,
+ * tested its own retirement pattern instead of `RETIRED_MARKER`, and tie-broke differently. So it described a
+ * ranking that does not ship, and the spec passed because it only checked the one shared component. The fix is
+ * not "be careful": it is that this module now IMPORTS every constant it ranks with from `memory.ts`, and its
+ * spec asserts the only property that cannot be faked — on the same on-disk plane with the same options, this
+ * module's order EQUALS `selectMemory`'s shard order.
+ */
+import { type FeedbackBook } from './memory-feedback.ts';
+import { type MemoryEntry } from './memory.ts';
+/** One contribution to an entry's score, named so a reader can argue with it. */
+export interface ScoreComponent {
+    name: string;
+    weight: number;
+    detail?: string;
+}
+export interface ExplainedEntry {
+    kind: string;
+    title: string;
+    source: string;
+    score: number;
+    /** Sums to `score`. Asserted in the spec, because a breakdown that does not add up is worse than none. */
+    components: ScoreComponent[];
+    warnings: string[];
+}
+export interface ExcludedEntry {
+    title: string;
+    source: string;
+    reason: string;
+}
+export interface MemoryExplanation {
+    /** Included entries, best first, each with its components. */
+    entries: ExplainedEntry[];
+    /** Everything the selector saw and did not inject — never silently dropped. */
+    excluded: ExcludedEntry[];
+    /** The same rendering shape the review path uses, for the included set. */
+    rendered: string;
+}
+export interface ExplainOptions {
+    query: string;
+    /**
+     * The run's changed paths. Already the signal FU-4 wired into `selectMemory`, and the one the reference
+     * script cannot compute because it runs outside the run.
+     */
+    files?: readonly string[];
+    /** The phase in play. Mirrors production's own option so both rank identically. */
+    phase?: string;
+    /** How many entries may be injected. Mirrors `selectMemory`'s own cap, which is docs-and-items bounded. */
+    maxItems?: number;
+    /** Mirrors `selectMemory`'s doc cap; the two caps compose there, so they must compose here. */
+    maxDocs?: number;
+    /**
+     * The counters, PASSED IN. This module takes entries rather than a root, so it has no business reading a
+     * sidecar — and an explainer that read its own evidence could disagree with the ranking it describes,
+     * which is the defect it was rewritten to remove.
+     */
+    feedback?: FeedbackBook;
+}
+/**
+ * Rank entries and explain every decision, using **production's own signals**.
+ *
+ * The score is `scoreMemoryEntry(entry, query) + <whole-path matches> * MEMORY_PATH_MATCH_WEIGHT`, the retired
+ * marker is `RETIRED_MARKER`, and the tie-break is `title.localeCompare` — the four things the first version
+ * got wrong by inventing them.
+ */
+export declare function explainMemorySelection(entries: readonly MemoryEntry[], options: ExplainOptions): MemoryExplanation;
+/** Render the included set, so a caller can print exactly what would be shown. */
+export declare function renderExplained(entries: readonly ExplainedEntry[]): string;

package/lib/memory.d.ts

@@ -0,0 +1,137 @@
+/**
+ * T14 — retrieve prior-run memory into the review bundle, so the recursion COMPOUNDS.
+ *
+ * WHY. A run that rediscovers what the last run learned is not a recursion, it is a repetition:
+ * the workflow already writes memory to `.recursive/memory/` (domains, patterns, episodes, skills),
+ * but nothing read it back into a REVIEWER's context, so every review started from nothing and the
+ * only party who benefited from a lesson was whoever happened to grep the directory.
+ *
+ * ⚠ THERE IS NO NATIVE MEMORY SERVICE — measured, not assumed. The item's `memoryStore` names a
+ * seam the harness does not provide (there is no memory package), so the store is this plugin's own
+ * layer: markdown documents under `.recursive/memory/`. That is why this module PARSES and RANKS
+ * rather than delegating; and it is why the ranking has to be explainable, since nothing else is
+ * going to decide relevance for it.
+ *
+ * ⚠ AND RETRIEVAL IS DETERMINISTIC ON PURPOSE. Two runs over the same memory with the same query
+ * MUST select the same entries: a reviewer whose context shuffles between runs cannot be compared
+ * with itself, and "why did it miss that?" becomes unanswerable. The tie-break is document order,
+ * so the result is reproducible from the inputs alone.
+ */
+import { type FeedbackBook } from './memory-feedback.ts';
+export declare const MEMORY_KINDS: readonly ["domains", "patterns", "episodes", "skills"];
+export type MemoryKind = (typeof MEMORY_KINDS)[number];
+/** One memory note: a titled section of a memory document. */
+export interface MemoryEntry {
+    kind: string;
+    title: string;
+    body: string;
+    /** Where it came from, so a citation in a review can be traced. */
+    source: string;
+}
+/** How many entries a bundle carries by default — enough to inform, not enough to drown a review. */
+export declare const DEFAULT_MEMORY_LIMIT = 8;
+/**
+ * Split a memory document into entries at its headings.
+ *
+ * A document with NO headings yields one entry rather than nothing: a memory file written as a
+ * single paragraph is still memory, and dropping it because it lacks structure would silently lose
+ * exactly the notes a hurried run leaves behind.
+ */
+export declare function parseMemoryEntries(kind: string, text: string, source: string): MemoryEntry[];
+/**
+ * Score one entry against a query: a term in the TITLE counts double.
+ *
+ * Titles are what a note is ABOUT; a term that appears only in the body may be incidental. The
+ * weighting is crude and deliberate — an explainable ranking beats a clever one nobody can audit,
+ * and the caller can always see every entry it did not get.
+ */
+export declare function scoreMemoryEntry(entry: MemoryEntry, query: string): number;
+/**
+ * Rank entries against a query, keeping only those that MATCH.
+ *
+ * A zero score means no overlap, and an unmatched entry is not "less relevant" — it is unrelated,
+ * and padding a reviewer's context with it would cost attention for nothing. Ties break by the
+ * original order (a stable sort), so the same inputs always give the same answer.
+ */
+export declare function retrieveMemory(entries: readonly MemoryEntry[], query: string, limit?: number): MemoryEntry[];
+/**
+ * Read the plugin's memory layer. Best-effort and never throws: an unreadable memory directory is
+ * a missing advantage, not a failed review.
+ *
+ * `readFile` is injected so the caller decides how files are read (and a test can drive it without
+ * a filesystem), which is also how the layout stays in ONE place — `.recursive/memory/<kind>/*.md`.
+ */
+export declare function readMemoryEntries(readFile: (path: string) => string | null, listFiles: (kind: string) => readonly string[], kinds?: readonly string[]): MemoryEntry[];
+/** Render the retrieved memory for a review bundle: sections a reviewer can cite by title. */
+export declare function renderMemorySection(entries: readonly MemoryEntry[]): string;
+/**
+ * T29 — INJECT MEMORY AT RUN START: the loader.
+ *
+ * WHY. The plugin built and linted the memory plane and **never read it**, so every run started from
+ * zero and the whole temporal axis was dead. This is the read half of that axis; {@link selectMemory}
+ * is the progressive-disclosure rule that keeps it from becoming a firehose.
+ *
+ * ⚠ RETIRED ENTRIES ARE NEVER INJECTED. `MemoryEntry` has no status FIELD, so the marker is read from
+ * the entry's own text (`Status: STALE` / `Status: DEPRECATED`) — and an entry that says it is retired
+ * is the one thing a later run must not be taught. Superseding writes a new entry; this is what makes
+ * the old one stop being read.
+ */
+export declare const RETIRED_MARKER: RegExp;
+/**
+ * What one matched changed path is worth. Exported for the same reason as the marker above: the explainer
+ * must add the number production adds, not a number that looks reasonable.
+ */
+export declare const MEMORY_PATH_MATCH_WEIGHT = 3;
+/**
+ * What an entry that declares it applies to THIS phase is worth. Exported for the same reason as the two
+ * constants above: the explainer must add the number production adds.
+ */
+export declare const MEMORY_PHASE_MATCH_WEIGHT = 2;
+/**
+ * The phase-applicability convention: an entry declares Applies to: 03, 03.5 in its body.
+ *
+ * Declaring NOTHING means general guidance, which is why the bonus is only ever added and never subtracted:
+ * an entry that names other phases simply earns no bonus, and the ranking order decides.
+ */
+export declare function entryAppliesTo(entry: MemoryEntry): string[];
+/** The registry the loader starts from: the router, not the plane. */
+export declare const MEMORY_INDEX_FILE = "memory/MEMORY.md";
+/** Progressive disclosure defaults, matching the parent (`--max-docs` 3, `--max-items` 10). */
+export declare const MAX_MEMORY_DOCS = 3;
+export declare const MAX_MEMORY_ITEMS = 10;
+/** Read the whole plane, minus nothing: filtering is the SELECTOR's job, not the reader's. */
+export declare function loadMemoryIndex(root: string, readFile?: (path: string) => string | null, listFiles?: (kind: string) => readonly string[]): MemoryEntry[];
+/** A shard, as the loader returns it: the entry plus why it was selected. */
+export interface MemoryShard {
+    entry: MemoryEntry;
+    score: number;
+    /** The query terms or paths that matched. Empty for an entry kept only because it is pinned. */
+    matched: string[];
+}
+export interface MemorySelection {
+    /** The shards to inject, best first. EMPTY when nothing was relevant. */
+    shards: MemoryShard[];
+    /** False when nothing is injected — the caller must then continue WITHOUT fabricating memory. */
+    injected: boolean;
+    reason: string;
+}
+/**
+ * Select what to inject.
+ *
+ * ⚠ PATHS ARE THE STRONGER SIGNAL, per the parent: a shard whose text mentions a path the run has
+ * actually changed outranks one that merely shares wording with the query. Both matter, and the path
+ * evidence is weighted — not substituted, because a run's requirements text is what says what the run
+ * is FOR.
+ *
+ * ⚠ NOTHING RELEVANT MEANS NOTHING INJECTED, verbatim from the parent: *"If the loader finds nothing
+ * relevant, continue normally rather than fabricating memory."* A zero-score entry is NOT a weak
+ * match, it is no match, and `injected: false` says so.
+ */
+export declare function selectMemory(root: string, options: {
+    query: string;
+    files?: readonly string[];
+    phase?: string;
+    feedback?: FeedbackBook;
+    maxDocs?: number;
+    maxItems?: number;
+}): MemorySelection;

package/lib/model-inventory.d.ts

@@ -0,0 +1,106 @@
+/**
+ * ⚠ FU-19 — THE PROVIDER AND MODEL INVENTORY, RESOLVED FROM DSH ITSELF.
+ *
+ * The requirement, in the user's words: *"provider and model inventory should be resolved from dsh itself, we only
+ * concern ourselves with what is configured inside dsh."* So this module does not keep a list, does not ship a
+ * table of known models, and does not guess. It asks the host what it has.
+ *
+ * ## Where the truth lives (measured, not assumed)
+ *
+ * `packages/llm/llm/src/index.ts` does `super(ctx, 'llm')`, so the service a plugin reaches is `ctx.llm`:
+ *
+ *   - `ctx.llm.listProviders()`                        → the providers DSH has
+ *   - `await ctx.llm.listModels(providerId)`           → that provider's models
+ *   - `await ctx.llm.resolveModelInfo(providerId, id)` → model detail (reasoning efforts, defaults)
+ *
+ * `api/session-controller/src/catalog.ts` builds the BROWSER model catalog from exactly that trio, so a plugin
+ * reading the same calls is reading what the UI shows. The service is resolved as an OPTIONAL seam, like every
+ * other host service this plugin uses.
+ *
+ * ## ⚠ TWO DIFFERENT THINGS ARE CALLED "PROVIDER", AND CONFLATING THEM WAS A REAL DEFECT IN THIS FEATURE
+ *
+ *   - a **SUBAGENT provider** creates the child — `spawn`, `fork` — and comes from `ctx.subagents.list()`;
+ *   - an **LLM provider** serves the model — `deepseek-official` — and comes from `ctx.llm.listProviders()`.
+ *
+ * A policy field called plain `provider` could mean either, and a user setting it would have no way to know which.
+ * So this module deals ONLY in the second kind, and the policy names it `modelProvider` for exactly that reason.
+ *
+ * ## ⚠ THE THREE-STATE VERDICT, WHICH IS THE POINT OF THE WHOLE MODULE
+ *
+ * A checker that answers only yes/no forces a lie in one direction or the other: either an unverifiable choice is
+ * reported as fine (a silent pass, which this project has fixed ten times over) or it is reported as wrong (a
+ * refusal to do something the user asked for, on the strength of a service that merely was not mounted). The
+ * verdict therefore has three states, and `unverified` is not a synonym for either:
+ *
+ *   - `available`  — the model is in the inventory; the choice is real
+ *   - `missing`    — the inventory answered and does NOT have it; the caller should say so, and must NOT swap it
+ *   - `unverified` — there was no inventory to ask; nothing is claimed, and nothing is replaced
+ */
+import type { SubagentProviderLike } from './router.ts';
+/**
+ * The structural view of `ctx.llm` this module needs. Structural rather than imported, like every other seam in
+ * this plugin: the harness packages are peer dependencies, and a plugin that imported their types would not load
+ * on a host that mounts a compatible service under its own class.
+ */
+export interface LlmInventoryLike {
+    listProviders(): ReadonlyArray<{
+        id: string;
+    }>;
+    listModels(providerId: string): Promise<ReadonlyArray<{
+        id: string;
+    }>> | ReadonlyArray<{
+        id: string;
+    }>;
+}
+/** One provider and the models it advertises. */
+export interface InventoryProvider {
+    id: string;
+    models: string[];
+}
+/** The inventory, when there was one to read. */
+export interface InventoryAvailable {
+    available: true;
+    providers: InventoryProvider[];
+    /** One sentence naming what was read, for the record. */
+    note: string;
+}
+/** The inventory was not readable, and why — never an empty inventory pretending to be one. */
+export interface InventoryUnavailable {
+    available: false;
+    reason: string;
+}
+export type ModelInventory = InventoryAvailable | InventoryUnavailable;
+/**
+ * Read the provider/model inventory from the host.
+ *
+ * Never throws: a provider whose model list fails is recorded with a NAME and no models rather than dropping the
+ * whole inventory, because "this provider would not answer" and "there are no providers" are different facts.
+ */
+export declare function describeInventory(llm: LlmInventoryLike | null | undefined): Promise<ModelInventory>;
+/** Which LLM provider advertises a model id — the lookup that makes `modelProvider` optional for the user. */
+export declare function findModelProvider(inventory: ModelInventory, modelId: string): string | null;
+export type ChoiceVerdict = 'available' | 'missing' | 'unverified';
+export interface ChoiceCheck {
+    verdict: ChoiceVerdict;
+    /** One sentence, always present, always saying which of the three states this is and why. */
+    reason: string;
+}
+/**
+ * Check a model choice against the inventory — and say `unverified` rather than guessing when there is none.
+ *
+ * ⚠ IT NEVER CHANGES THE CHOICE. A caller that receives `missing` must report it; it must not quietly substitute
+ * a model the inventory does have, because silently running a child on a different model than the user asked for
+ * is precisely the failure this whole feature exists to prevent.
+ */
+export declare function checkModelChoice(inventory: ModelInventory, modelId: string, modelProvider?: string | null): ChoiceCheck;
+/** The provider ids, for a message that tells the caller what IS available instead of only what is not. */
+export declare function providerIdsText(inventory: ModelInventory): string;
+/**
+ * Which subagent providers the host actually offers — the OTHER kind of provider, kept adjacent on purpose so the
+ * two are never confused in a message.
+ */
+export declare function subagentProviderNames(seam: {
+    list?: () => unknown;
+} | null | undefined): string[];
+/** The declared capabilities of a subagent provider, or null when it is not registered. */
+export declare function capabilitiesOf(providers: Record<string, SubagentProviderLike>, name: string): SubagentProviderLike['capabilities'] | null;