@inixiative/foundry-core 0.5.2 → 0.5.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inixiative/foundry-core",
-  "version": "0.5.2",
+  "version": "0.5.3",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",

package/src/feedback/correction.ts

@@ -31,6 +31,8 @@ export interface CorrectionEvent {
   readonly timestamp: string;
   /** What the agent said right before the correction ('' at the start of a session). */
   readonly before: string;
+  /** The person's previous message: what the agent was answering when it earned the correction. */
+  readonly ask?: string;
   /** The person's message. */
   readonly correction: string;
   /** The strongest signal, and every signal that fired. */
@@ -167,6 +169,7 @@ export function extractCorrections(
   const minScore = options.minScore ?? 0;
   const corrections: CorrectionEvent[] = [];
   let before = '';
+  let ask = '';
   let pendingInterruption = false;
   let secretsScrubbed = 0;
   // An identical message resent within ten minutes is one correction, not a repeat.
@@ -181,6 +184,8 @@ export function extractCorrections(
     if (!text.trim()) continue;
     const detection = detectCorrection(text, before, { interrupted: pendingInterruption });
     pendingInterruption = false;
+    const previousAsk = ask;
+    ask = text.trim();
     const key = text.toLowerCase().replace(/\s+/g, ' ').trim();
     const at = Date.parse(turn.timestamp);
     const sent = recent.get(key);
@@ -190,12 +195,14 @@ export function extractCorrections(
     // Scrub before truncating, so a cut can't leave part of a secret unmatched.
     const scrubbedBefore = scrubSecrets(before);
     const scrubbedText = scrubSecrets(text.trim());
-    secretsScrubbed += scrubbedBefore.hits + scrubbedText.hits;
+    const scrubbedAsk = scrubSecrets(previousAsk);
+    secretsScrubbed += scrubbedBefore.hits + scrubbedText.hits + scrubbedAsk.hits;
     const event = {
       ...(turn.id ? { messageId: turn.id } : {}),
       ...(turn.sourceRef ? { sourceRef: turn.sourceRef } : {}),
       timestamp: turn.timestamp,
       before: scrubbedBefore.text.slice(-2000),
+      ...(scrubbedAsk.text ? { ask: scrubbedAsk.text.slice(0, 4000) } : {}),
       correction: scrubbedText.text.slice(0, 4000),
       signal: detection.signal,
       signals: detection.signals,

package/src/feedback/experiment-gate.ts

@@ -0,0 +1,89 @@
+/**
+ * The experiment gate (`.claude/skills/experiment/SKILL.md`), shared by Foundry's eval scripts and
+ * Oracle's replay runner: a wide run (more than TINY_MOMENTS moments, or whatever else the caller
+ * counts as wide) needs `--experiment <design.md>` whose pre-registration sections are filled and
+ * whose `<design>.review.md` says `verdict: go` for this exact design (`design-sha256:` of its
+ * bytes). A tiny test runs without one.
+ */
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+export const TINY_MOMENTS = 3;
+
+/** The `## ` headings of `.claude/skills/experiment/design.md`, every one required. */
+export const DESIGN_SECTIONS = [
+  'Question',
+  'Variable',
+  'Arms',
+  'Fixtures and power',
+  'Baseline',
+  'Gates',
+  'Cost ceiling and stop rules',
+  'Provenance',
+  'What would make the result wrong',
+] as const;
+
+export type ExperimentRecord = { design: string; designSha256: string; review: string };
+
+export const reviewPathOf = (design: string) => design.replace(/\.md$/, '.review.md');
+
+const sha256 = (path: string) => createHash('sha256').update(readFileSync(path)).digest('hex');
+
+/** Why the design may not run wide; empty when it may. */
+export const experimentProblems = (designPath: string): string[] => {
+  const design = resolve(designPath);
+  if (!design.endsWith('.md')) return [`${design}: the design is a .md file`];
+  if (!existsSync(design)) return [`${design}: no such design`];
+  const problems: string[] = [];
+  const text = readFileSync(design, 'utf8');
+  const sections = new Map<string, string>();
+  let current: string | undefined;
+  for (const line of text.split('\n')) {
+    const heading = /^##\s+(.+?)\s*$/.exec(line);
+    if (heading) {
+      current = heading[1]?.toLowerCase();
+      if (current) sections.set(current, sections.get(current) ?? '');
+    } else if (/^#\s/.test(line)) current = undefined;
+    else if (current) sections.set(current, `${sections.get(current) ?? ''}${line}\n`);
+  }
+  for (const name of DESIGN_SECTIONS) {
+    const body = sections.get(name.toLowerCase());
+    if (body === undefined) problems.push(`missing section "## ${name}"`);
+    else if (!body.replace(/<!--[\s\S]*?-->/g, '').trim())
+      problems.push(`section "## ${name}" is empty`);
+  }
+  if (text.includes('<fill')) problems.push('unfilled <fill: …> placeholders remain');
+  const review = reviewPathOf(design);
+  if (!existsSync(review)) return [...problems, `no adversarial review at ${review}`];
+  const reviewText = readFileSync(review, 'utf8');
+  if (!/^verdict:\s*go\s*$/im.test(reviewText))
+    problems.push(`${review} has no "verdict: go" line`);
+  const reviewed = /^design-sha256:\s*([0-9a-f]{64})\s*$/im.exec(reviewText)?.[1];
+  if (!reviewed) problems.push(`${review} has no "design-sha256: <hex>" line`);
+  else if (reviewed !== sha256(design))
+    problems.push('the design changed after its review (design-sha256 differs): review it again');
+  return problems;
+};
+
+/** Throws unless the run may go ahead; returns the provenance to record when a design was named. */
+export const requireExperiment = (
+  experiment: string | undefined,
+  wide: boolean,
+): ExperimentRecord | undefined => {
+  if (!experiment) {
+    if (!wide) return undefined;
+    throw Error(
+      `a wide run (more than ${TINY_MOMENTS} moments) needs --experiment <design.md> ` +
+        'with a reviewed pre-registration: see .claude/skills/experiment/SKILL.md',
+    );
+  }
+  const problems = experimentProblems(experiment);
+  if (problems.length)
+    throw Error(
+      `--experiment ${experiment} may not run:\n  - ${problems.join('\n  - ')}\n` +
+        'see .claude/skills/experiment/SKILL.md',
+    );
+  const design = resolve(experiment);
+  return { design, designSha256: sha256(design), review: reviewPathOf(design) };
+};

package/src/feedback/review-findings.ts

@@ -0,0 +1,237 @@
+import {
+  type Authorship,
+  CONCEPT_CLUSTERS,
+  type CorrectionTarget,
+  MISS_KINDS,
+  type MissKind,
+} from './warden-probes';
+
+// The Prospector's reading of written review: PR reviews and ticket comments where the person said the
+// work should have used, extended or ported something that already existed. Data and pure functions
+// only: callers fetch the text and make the model call.
+
+/** One piece of written review, with what it was about. */
+export interface ReviewMoment {
+  readonly id: string;
+  /** Where it was written, e.g. `PR #2116 (CHANGES_REQUESTED review, inline)` or `ZLT-4321 comment`. */
+  readonly where: string;
+  /** What the work was: PR title and description, or the issue's title and description. */
+  readonly work: string;
+  /** The code it was written on, when inline (path, line, diff hunk). */
+  readonly code?: string;
+  /** The message it replies to, when it is a reply. */
+  readonly replyTo?: string;
+  readonly text: string;
+  /** `directive`: a description the person wrote of work still to do (a ticket, a project), not a review of done work. */
+  readonly mode?: 'review' | 'directive';
+}
+
+export type FindingScope = 'architectural' | 'code';
+
+/** How much a finding counts in scoring: generic code-correctness findings are lightly down-weighted (Aron, 2026-10-15). */
+export const SCOPE_WEIGHT: Readonly<Record<FindingScope, number>> = {
+  architectural: 1,
+  code: 0.75,
+};
+
+/** One place the reviewer pushed toward something that already existed. */
+export interface ReviewFinding {
+  readonly target: CorrectionTarget;
+  /** The reviewer's own words that say it, verbatim, at most 300 characters. */
+  readonly excerpt: string;
+  /** `architectural`: about which system, primitive or boundary to build on; `code`: a generic code-correctness fix. */
+  readonly scope?: FindingScope;
+}
+
+export interface ReviewReading {
+  readonly findings: readonly ReviewFinding[];
+  /** The model's read of the voice: typed by a person, or written by an AI agent. A weak signal. */
+  readonly voice?: 'human' | 'agent';
+}
+
+/**
+ * Words a reuse finding almost always carries. A change-request review is read whole; everything else
+ * is read only when it matches (the method of Zealot's core-primitives findings, ZLT-5638).
+ */
+export const REUSE_HINT =
+  /\b(?:already (?:exists?|have|has|does|handles?|in|imported|installed|there)|existing|exists|re-?use|reimplement\w*|re-implement\w*|hand-?roll\w*|hand-?written|duplicat\w*|copy|copies|copied|parallel|second (?:copy|version|implementation)|third (?:copy|type system)|instead of|port(?:ed|ing)? (?:from|it|this|the)|from (?:the )?template|template'?s|primitive|extend(?:ing)? (?:the|it)|use (?:the |our )?[`\w]|we have|there'?s (?:a|an|already)|same (?:shape|thing|as)|like \w+ does|convention|pattern|wrapper|shared|generic|lodash|helper|util|registry|consolidate|fold (?:into|it)|one place|single source)\b/i;
+
+export const REVIEW_FINDINGS_PROMPT = `You read code review written by one reviewer, Aron, on pull requests and tickets. For each item, find every place where he says the work should have USED, EXTENDED or PORTED something that ALREADY EXISTS instead of what was built: a primitive (helper, wrapper, hook, component, class, module, package export, library already installed), a system (an existing subsystem or flow), a pattern (an established way the codebase does a thing, e.g. a route template or a module convention), or a rule (a standing convention or ruling, e.g. "no select on internal reads").
+
+A finding needs both: the existing thing, and what was done instead. Not findings: bug reports, missing tests, style nits, new requirements, questions, praise, status updates, an author's replies about what they fixed, and anything that points at something not yet built.
+
+For each finding:
+- name: the existing thing as the codebase names it, at most 80 characters (e.g. "paginate() + filterLens", "Skeleton component", "lodash omit", "PolymorphismRegistry"). Name the thing, not the advice.
+- kind: "primitive" | "system" | "pattern" | "rule"
+- concept: its concept cluster; use one of the given clusters when one fits, else a new short kebab-case cluster.
+- where: the file, package or doc it lives in, only when the item says so.
+- builtInstead: what the work did instead, one line, at most 160 characters. For a directive item, what the work would otherwise have built, or "" when the item doesn't say.
+- miss: why it was missed, judged from the item: "unaware" (didn't know it existed), "misfit" (knew it, worked around a gap instead of extending it), "wrapper" (wrapped it under a new name), "unclear".
+- excerpt: Aron's words that say it, verbatim, at most 300 characters.
+- scope: "architectural" when it is about which system, primitive, module boundary or pattern to build on; "code" when it is a generic code-correctness fix (a library call, a small helper, an idiom).
+
+Items marked "Mode: directive" are descriptions Aron wrote of work still to be done (a ticket, a project). There a finding is a place where he directs the work to use, extend or port something that already exists, by name.
+
+Also judge the voice of each item: "human" when it reads as typed by a person (terse, informal, lowercase, typos, first-person asides), "agent" when it reads as written by an AI coding agent (headed sections, bold labels, numbered findings, dense backticked citations, "Fixed in <sha>" replies, polished em-dash prose).
+
+Respond with JSON only: { "results": { "<id>": { "voice": "human" | "agent", "findings": [ { "name": string, "kind": string, "concept": string, "where"?: string, "builtInstead": string, "miss": string, "excerpt": string, "scope": "architectural" | "code" } ] } } } with "findings": [] when there are none.`;
+
+/** The reader's input for a batch of review moments. */
+export function reviewFindingMessages(
+  moments: readonly ReviewMoment[],
+): { role: 'system' | 'user'; content: string }[] {
+  const body = moments
+    .map((m) =>
+      [
+        `## ${m.id}`,
+        `Where: ${m.where}`,
+        ...(m.mode === 'directive' ? ['Mode: directive'] : []),
+        `### The work\n${m.work.slice(0, 1200)}`,
+        ...(m.code ? [`### Code it was written on\n${m.code.slice(-1500)}`] : []),
+        ...(m.replyTo ? [`### Replying to\n${m.replyTo.slice(0, 800)}`] : []),
+        `### Aron wrote\n${m.text.slice(0, 4000)}`,
+      ].join('\n'),
+    )
+    .join('\n\n');
+  return [
+    { role: 'system', content: REVIEW_FINDINGS_PROMPT },
+    {
+      role: 'user',
+      content: `Concept clusters: ${CONCEPT_CLUSTERS.join(', ')}\n\nRead each item below.\n\n${body}`,
+    },
+  ];
+}
+
+const KINDS = new Set(['primitive', 'system', 'pattern', 'rule']);
+const kebab = (text: string) =>
+  text
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-|-$/g, '');
+
+/** One reading per id; undefined when missing or malformed (the caller retries it alone). */
+export function parseReviewFindings(
+  content: string,
+  ids: readonly string[],
+): (ReviewReading | undefined)[] {
+  let results: Record<string, { voice?: unknown; findings?: unknown }> = {};
+  try {
+    results =
+      (
+        JSON.parse(content.slice(content.indexOf('{'), content.lastIndexOf('}') + 1)) as {
+          results?: typeof results;
+        }
+      ).results ?? {};
+  } catch {
+    return ids.map(() => undefined);
+  }
+  return ids.map((id) => {
+    const item = results[id];
+    if (!item || !Array.isArray(item.findings)) return undefined;
+    const findings: ReviewFinding[] = [];
+    for (const raw of item.findings as Record<string, unknown>[]) {
+      if (!raw || typeof raw.name !== 'string' || !raw.name.trim()) continue;
+      if (typeof raw.concept !== 'string' || !kebab(raw.concept)) continue;
+      const miss = MISS_KINDS.includes(raw.miss as MissKind) ? (raw.miss as MissKind) : 'unclear';
+      findings.push({
+        target: {
+          name: raw.name.trim().slice(0, 120),
+          kind: (KINDS.has(String(raw.kind)) ? raw.kind : 'pattern') as CorrectionTarget['kind'],
+          concept: kebab(raw.concept),
+          ...(typeof raw.where === 'string' && raw.where.trim()
+            ? { where: raw.where.trim().slice(0, 160) }
+            : {}),
+          ...(typeof raw.builtInstead === 'string' && raw.builtInstead.trim()
+            ? { builtInstead: raw.builtInstead.trim().slice(0, 240) }
+            : {}),
+          miss,
+        },
+        excerpt: typeof raw.excerpt === 'string' ? raw.excerpt.trim().slice(0, 300) : '',
+        ...(raw.scope === 'architectural' || raw.scope === 'code' ? { scope: raw.scope } : {}),
+      });
+    }
+    return {
+      findings,
+      ...(item.voice === 'human' || item.voice === 'agent' ? { voice: item.voice } : {}),
+    };
+  });
+}
+
+/** Markers an agent leaves in what it posts, and the trace of text typed into a web form. */
+export const AUTHORSHIP_MARKERS = {
+  /** An agent's signature line. */
+  footer:
+    /(?:generated (?:by|with) \[?claude|🤖 generated|co-authored-by: claude|^_?generated by .{0,40}_?$)/im,
+  /** Claude Code's terminal glyphs: an agent's output pasted in by hand. */
+  pasted: /(?:^|\n)\s*[⏺⎿]/,
+  /** CRLF line endings: typed (or edited) in the GitHub web UI; gh and the API post LF. */
+  webForm: /\r\n/,
+} as const;
+
+/** What the person's own sessions say about a comment: an agent posted it, or the person typed it. */
+export interface SessionEvidence {
+  readonly posted?: boolean;
+  /** The text appears in another tool call: a body file an agent drafted, or a quote. Weak. */
+  readonly drafted?: boolean;
+  readonly typed?: boolean;
+}
+
+/**
+ * Who wrote a comment posted under the person's account. Strong evidence decides; a model's read of
+ * the voice is the weak fallback, then plain style. A typed prompt outranks an agent posting it: the
+ * person dictated the words.
+ */
+export function authorshipOf(
+  text: string,
+  evidence: SessionEvidence = {},
+  voice?: 'human' | 'agent',
+): Authorship {
+  const signals: string[] = [];
+  if (evidence.typed) signals.push('session:typed');
+  if (evidence.posted) signals.push('session:posted');
+  if (evidence.drafted) signals.push('session:drafted');
+  if (AUTHORSHIP_MARKERS.footer.test(text)) signals.push('marker:footer');
+  if (AUTHORSHIP_MARKERS.pasted.test(text)) signals.push('marker:pasted');
+  if (AUTHORSHIP_MARKERS.webForm.test(text)) signals.push('marker:web-form');
+  const style = styleOf(text);
+  signals.push(`style:${style}`);
+  if (voice) signals.push(`voice:${voice}`);
+  if (evidence.typed) return { by: 'human', confidence: 'strong', signals };
+  if (evidence.posted || signals.includes('marker:footer') || signals.includes('marker:pasted'))
+    return { by: 'agent', confidence: 'strong', signals };
+  if (signals.includes('marker:web-form')) return { by: 'human', confidence: 'strong', signals };
+  // A draft can also be an agent quoting the person's comment back, so it only outweighs style.
+  return { by: evidence.drafted ? 'agent' : (voice ?? style), confidence: 'weak', signals };
+}
+
+/** Plain style: an agent's headings, bold labels, numbered findings and dense citations. */
+export function styleOf(text: string): 'human' | 'agent' {
+  let agent = 0;
+  if (/^#{1,4} /m.test(text)) agent += 2;
+  if (/\*\*[^*\n]{2,60}\*\*/.test(text)) agent++;
+  if (/^\s*\d+\. \*\*/m.test(text)) agent += 2;
+  if ((text.match(/`[^`\n]+`/g) ?? []).length >= 4) agent++;
+  if ((text.match(/—/g) ?? []).length >= 2) agent++;
+  if (/^(?:Fixed in|Addressed in|Done in) [0-9a-f]{7}/im.test(text)) agent += 2;
+  if (text.length > 900) agent++;
+  let human = 0;
+  if (/^[a-z]/.test(text.trim())) human += 2;
+  if (!/[.!?:`)]\s*$/.test(text.trim())) human++;
+  if (/\b(?:im|dont|cant|doesnt|isnt|wont|u|ur|pls|thx|lol|imo|tbh)\b/.test(text)) human += 2;
+  if (text.length < 200) human++;
+  return agent > human ? 'agent' : 'human';
+}
+
+/**
+ * A distinctive run of a comment that survives JSON and shell quoting unchanged, to find the session
+ * that posted it. Undefined when the text has no such run.
+ */
+export function evidenceSnippet(text: string, length = 48): string | undefined {
+  let best = '';
+  for (const run of text.split(/[^A-Za-z0-9 ,.;:()/_=+-]+/))
+    if (run.trim().length > best.length) best = run.trim();
+  if (best.length < Math.min(length, 32)) return undefined;
+  const start = Math.max(0, Math.floor((best.length - length) / 2));
+  return best.slice(start, start + length).trim();
+}

package/src/feedback/warden-labels.ts

@@ -14,7 +14,7 @@ export interface WardenLabel {
   readonly shouldKnow?: string;
 }
 
-export type WardenTriggerKind = 'user-message' | 'agent-action' | 'agent-plan';
+export type WardenTriggerKind = 'user-message' | 'agent-action' | 'agent-plan' | 'subagent-spawn';
 
 /**
  * A labelled moment for the Warden prefilter: which Warden domains the trigger touches. Never commit
@@ -215,7 +215,10 @@ export function fixtureProbe(
     kind: relevant.length ? 'positive' : 'negative',
     ctx: fixture.ctx,
     ...(fixture.project ? { project: fixture.project } : {}),
-    moment: fixture.trigger.text,
+    // A user-message fixture is asked at the user-message trigger; the others are the agent's turn.
+    ...(fixture.trigger.kind === 'user-message'
+      ? { moment: '', ask: fixture.trigger.text }
+      : { moment: fixture.trigger.text }),
     ...(relevant.length
       ? {
           gold: {

package/src/feedback/warden-prefilter.ts

@@ -6,8 +6,9 @@
 import type { WardenTriggerKind } from './warden-labels';
 
 /**
- * Where a moment arrives: before (the user's message) or after (the agent's action or plan, and its
- * finished turn). The labelled moments are `WardenFixture`s (`warden-labels`).
+ * Where a moment arrives: before (the user's message), after (the agent's actions of a turn or its
+ * plan, and its finished turn), or at a handoff to a subagent. The labelled moments are
+ * `WardenFixture`s (`warden-labels`).
  */
 export type PrefilterTrigger = WardenTriggerKind | 'post-turn';
 
@@ -172,8 +173,9 @@ export function prefilterQuestion(description: string) {
 export function prefilterState(trigger: PrefilterTrigger, text: string, context?: string): string {
   const label = {
     'user-message': "The user's message",
-    'agent-action': "The agent's action",
+    'agent-action': "The agent's actions this turn",
     'agent-plan': "The agent's plan",
+    'subagent-spawn': 'The task the agent is handing to a subagent',
     'post-turn': "The agent's finished turn",
   }[trigger];
   const moment = window(text.trim(), PREFILTER_MOMENT_CHARS);

package/src/feedback/warden-probes.ts

@@ -2,8 +2,28 @@
 // scope and right. Data and pure functions only, so Oracle can score runs on a core-only dependency;
 // callers bring the probes, the Warden calls and the judge call.
 //
-// A probe is one moment of a real session. A positive probe is an agent turn that drew a sharp
-// correction of an already-recorded rule; a negative probe is an agent turn the user let pass.
+// A probe is one moment of a real session. A positive probe is a moment that drew the user's sharp
+// correction; a negative probe is one the user let pass. Each trigger point asks about its own part
+// of the moment: `user-message` about the user's ask (advise), `agent-action` about the agent's turn
+// (guard). A Warden anticipated a correction when it said it first, at either trigger.
+
+import type { TokenCounts } from '../token-counts';
+
+/** Where the Prospector found a probe. */
+export type ProbeSource = 'session' | 'github' | 'linear';
+
+/**
+ * Whether the person wrote a correction or an agent wrote it under their account. `strong` rests on
+ * a marker (an agent footer, a posting command in a session, text typed in the web UI); `weak` on style.
+ */
+export interface Authorship {
+  readonly by: 'human' | 'agent';
+  readonly confidence: 'strong' | 'weak';
+  readonly signals: readonly string[];
+}
+
+/** The trigger points a probe is asked at (live: `user-message` advises, `agent-action` guards). */
+export type WardenProbeTrigger = 'user-message' | 'agent-action';
 
 /** One real moment a chorus is asked about. Never commit probes: they hold session text. */
 export interface WardenProbe {
@@ -12,29 +32,62 @@ export interface WardenProbe {
   /** Which context's Wardens may see it (UserEvidence probes only ever see the UserEvidence ladder). */
   readonly ctx: string;
   readonly project?: string;
-  /** The moment: what the agent just did or said, as the Warden sees it. */
+  /** Where the Prospector found it: a session, a GitHub PR review, a Linear issue. Absent means session. */
+  readonly source?: ProbeSource;
+  /** Who wrote the correction, for sources where the person's account also posts agent-written text. */
+  readonly authorship?: Authorship;
+  /** How much the probe counts in weighted scores (default 1): generic code-correctness findings count less. */
+  readonly weight?: number;
+  /** What the agent just did or said, as the Warden sees it ('' when only the user's ask was recorded). */
   readonly moment: string;
-  /** Positive probes: the Warden domains that own the rule the user enforced next, and its one-line statements. */
-  readonly gold?: { readonly domains: readonly string[]; readonly statements: readonly string[] };
+  /** The user's message the agent was answering: what the `user-message` trigger advises on. */
+  readonly ask?: string;
+  /** When the user answered (ISO), and the period it falls in, so a backtest trains on earlier probes only. */
+  readonly at?: string;
+  readonly period?: 'train' | 'test';
+  /** Positive probes: the Warden domains that own the rule the user enforced next (when known), and its one-line statements. */
+  readonly gold?: {
+    readonly domains: readonly string[];
+    readonly statements: readonly string[];
+    /** What the user pushed the agent toward: the existing rule, primitive, system or pattern. */
+    readonly target?: CorrectionTarget;
+  };
   /** The user's actual next message. The judge sees it; Wardens never do. */
   readonly hidden?: string;
+  /** The Warden's own understanding of the thread at this moment, as a live call supplies it. */
+  readonly threadKnowledge?: string;
+}
+
+/** The trigger points that can ask about a probe: those whose input it recorded. */
+export function probeTriggers(probe: WardenProbe): WardenProbeTrigger[] {
+  return [
+    ...(probe.ask?.trim() ? (['user-message'] as const) : []),
+    ...(probe.moment.trim() ? (['agent-action'] as const) : []),
+  ];
 }
 
 /** One Warden's answer on one probe, and the judge's verdict when it spoke. */
 export interface WardenProbeAnswer {
   readonly probeId: string;
   readonly domain: string;
+  /** The trigger point that asked; `agent-action` when unrecorded. */
+  readonly trigger?: WardenProbeTrigger;
   readonly noComment: boolean;
   /** The protocol was broken; counted apart, never as silence or speech. */
   readonly error?: string;
   readonly text?: string;
   readonly elapsedMs?: number;
+  /** What the call used, as the provider reported it (cache reads show a warm, primed prefix). */
+  readonly tokens?: Omit<TokenCounts, 'providerUsage'>;
+  /** Transport failures of earlier attempts at this call, re-asked before this answer. */
+  readonly retried?: readonly string[];
   readonly judged?: WardenJudgement;
 }
 
 /** One probe run as a turn: every Warden asked at once, as the live chorus is. */
 export interface WardenProbeTurn {
   readonly probeId: string;
+  readonly trigger?: WardenProbeTrigger;
   /** Warden calls made for this probe. */
   readonly calls: number;
   /** Wall clock from the first ask to the last answer. */
@@ -65,8 +118,30 @@ export interface CharterScore {
   readonly speakPrecision: number | null;
   /** Remarks outside the speaking Warden's domain. */
   readonly scopeViolations: number;
-  /** Positive probes where a gold (owning) Warden named the correction before the user did. */
+  /** Of positive probes with gold domains, those where an owning Warden named the correction before the user did. */
   readonly recall: number | null;
+  /** The primary measure: of all positive probes, those where any Warden, at any trigger, said the correction first. */
+  readonly anticipated: number | null;
+  /** `anticipated` with each positive counted at its `weight`. */
+  readonly weightedAnticipated: number | null;
+  /** Remarks the judge did not match to a real correction (on negative probes, or saying something else). */
+  readonly wrongRemarks: number;
+  /** Wrong remarks per probe asked: how often the chorus speaks when the user would not have. */
+  readonly wrongPerProbe: number | null;
+  /** The same measures per trigger point, over the probes that trigger could ask about. */
+  readonly byTrigger: Partial<
+    Record<
+      WardenProbeTrigger,
+      {
+        readonly probes: number;
+        readonly positives: number;
+        readonly anticipated: number | null;
+        readonly remarks: number;
+        readonly speakPrecision: number | null;
+        readonly wrongRemarks: number;
+      }
+    >
+  >;
   readonly remarks: number;
   readonly silences: number;
   /** Remarks the judge could not grade: counted as unmatched, reported apart. */
@@ -88,6 +163,16 @@ function percentile(sorted: readonly number[], p: number): number {
 
 const ratio = (n: number, d: number) => (d ? Math.round((n / d) * 1000) / 1000 : null);
 
+/** The 95% Wilson interval of `n` successes in `d` trials, to three places; null when nothing was tried. */
+export function wilsonInterval(n: number, d: number): [number, number] | null {
+  if (!d) return null;
+  const z = 1.96;
+  const p = n / d;
+  const centre = (p + (z * z) / (2 * d)) / (1 + (z * z) / d);
+  const half = (z * Math.sqrt((p * (1 - p)) / d + (z * z) / (4 * d * d))) / (1 + (z * z) / d);
+  return [Math.round((centre - half) * 1000) / 1000, Math.round((centre + half) * 1000) / 1000];
+}
+
 /**
  * Score one charter run. "Nothing applied" means a negative probe, or a positive probe whose gold
  * domains do not include this Warden; a remark there that the judge matched to the real correction
@@ -109,6 +194,11 @@ export function scoreCharterRun(
     silences = 0,
     unjudged = 0;
   const recalled = new Set<string>();
+  const anticipated = new Set<string>();
+  const perTrigger = new Map<
+    WardenProbeTrigger,
+    { probes: Set<string>; anticipated: Set<string>; remarks: number; right: number }
+  >();
   for (const a of answers) {
     calls++;
     const probe = byId.get(a.probeId);
@@ -117,16 +207,32 @@ export function scoreCharterRun(
     if (a.error) {
       // A broken answer is neither silence nor a remark; where nothing applied, it is a failed silence.
       errors++;
+      perTrigger.get(a.trigger ?? 'agent-action')?.probes.add(probe.id);
       if (!owned) quietCases++;
       continue;
     }
+    const trigger = a.trigger ?? 'agent-action';
+    const tally = perTrigger.get(trigger) ?? {
+      probes: new Set<string>(),
+      anticipated: new Set<string>(),
+      remarks: 0,
+      right: 0,
+    };
+    perTrigger.set(trigger, tally);
+    tally.probes.add(probe.id);
     if (a.noComment) silences++;
     else {
       remarks++;
+      tally.remarks++;
       if (!a.judged) unjudged++;
       if (a.judged?.matches) {
         remarksRight++;
+        tally.right++;
         if (owned) recalled.add(probe.id);
+        if (probe.kind === 'positive') {
+          anticipated.add(probe.id);
+          tally.anticipated.add(probe.id);
+        }
       }
       if (a.judged && !a.judged.inDomain) scope++;
     }
@@ -135,7 +241,28 @@ export function scoreCharterRun(
       if (a.noComment) quietRight++;
     }
   }
-  const positives = probes.filter((p) => p.kind === 'positive').length;
+  const positives = probes.filter((p) => p.kind === 'positive');
+  const owners = positives.filter((p) => p.gold?.domains.length).length;
+  const asked = new Set(answers.map((a) => a.probeId));
+  const byTrigger: CharterScore['byTrigger'] = Object.fromEntries(
+    [...perTrigger].map(([trigger, t]) => {
+      const reached = probes.filter((p) => t.probes.has(p.id));
+      return [
+        trigger,
+        {
+          probes: reached.length,
+          positives: reached.filter((p) => p.kind === 'positive').length,
+          anticipated: ratio(
+            t.anticipated.size,
+            reached.filter((p) => p.kind === 'positive').length,
+          ),
+          remarks: t.remarks,
+          speakPrecision: ratio(t.right, t.remarks),
+          wrongRemarks: t.remarks - t.right,
+        },
+      ];
+    }),
+  );
   return {
     probes: probes.length,
     calls,
@@ -143,7 +270,18 @@ export function scoreCharterRun(
     silencePrecision: ratio(quietRight, quietCases),
     speakPrecision: ratio(remarksRight, remarks),
     scopeViolations: scope,
-    recall: ratio(recalled.size, positives),
+    recall: ratio(recalled.size, owners),
+    anticipated: ratio(anticipated.size, positives.length),
+    weightedAnticipated: (() => {
+      const total = positives.reduce((n, p) => n + (p.weight ?? 1), 0);
+      const said = positives
+        .filter((p) => anticipated.has(p.id))
+        .reduce((n, p) => n + (p.weight ?? 1), 0);
+      return total ? Math.round((said / total) * 1000) / 1000 : null;
+    })(),
+    wrongRemarks: remarks - remarksRight,
+    wrongPerProbe: ratio(remarks - remarksRight, probes.filter((p) => asked.has(p.id)).length),
+    byTrigger,
     remarks,
     silences,
     unjudged,
@@ -166,31 +304,205 @@ export function scoreCharterRun(
   };
 }
 
+/** What a correction pushed the agent toward. Absent when it pushed toward nothing that already existed. */
+export interface CorrectionTarget {
+  /** The thing itself, named as the codebase names it (e.g. "Inquiry handler autoApprove"). */
+  readonly name: string;
+  readonly kind: 'primitive' | 'system' | 'pattern' | 'rule';
+  /** The concept cluster it belongs to (kebab-case, e.g. "concurrency-locking"): the routing label. */
+  readonly concept: string;
+  /** Where it lives, when the moment says (file, package, doc). */
+  readonly where?: string;
+  /** The canonical name shared by every correction that pushed toward the same thing. */
+  readonly canonical?: string;
+  /** What was built instead of using it, when the source says (PR reviews do). */
+  readonly builtInstead?: string;
+  /**
+   * Why it was missed, from the thread: `unaware` (didn't know it existed), `misfit` (knew it and
+   * worked around a gap instead of extending it), `wrapper` (wrapped it under a new name), `unclear`.
+   */
+  readonly miss?: MissKind;
+}
+
+export const MISS_KINDS = ['unaware', 'misfit', 'wrapper', 'unclear'] as const;
+export type MissKind = (typeof MISS_KINDS)[number];
+
+/** Concept clusters the labeler starts from; it may add one when none fits. */
+export const CONCEPT_CLUSTERS = [
+  'concurrency-locking',
+  'requests-inquiry',
+  'access-signets-permissions',
+  'audit-log',
+  'errors-responses',
+  'data-schema-db',
+  'queries-db-client',
+  'jobs-queues-cron',
+  'caching',
+  'http-routes-api',
+  'validation-types',
+  'testing-fixtures-vcr',
+  'frontend-ui',
+  'email-communications',
+  'config-env-setup',
+  'tooling-ci-lint',
+  'naming',
+  'docs-conventions',
+  'shared-helpers-utils',
+  'process-merge-ship',
+  'process-communication',
+] as const;
+
+export const CORRECTION_TARGET_PROMPT = `You label corrections a developer gave an AI coding agent. Each item shows the developer's request, the agent's turn when recorded, and the developer's correction.
+
+Most corrections push the agent toward something that ALREADY EXISTS: a primitive (a helper, wrapper, class, module, package export), a system (an existing subsystem or flow, e.g. the inquiry system, the audit log), a pattern (an established way the codebase does a thing), or a rule (a standing convention or process rule, e.g. "merge yourself once green", "no backwards compatibility"). Name that target.
+
+For each item:
+- target: null when the correction pushes toward nothing that already existed (a new requirement, a bug report, a fact about the world, a scope change). Otherwise an object:
+  - name: the thing itself, as the codebase would name it, at most 80 characters (e.g. "Inquiry handler autoApprove", "shared VCR utilities", "SELECT FOR UPDATE lock helper", "audit log records the actor"). Name the thing, not the advice.
+  - kind: "primitive" | "system" | "pattern" | "rule"
+  - concept: the concept cluster it belongs to; use one of the given clusters when one fits, else a new short kebab-case cluster.
+  - where: the file, package or doc it lives in, only when the item says so; else omit.
+
+Respond with JSON only: { "results": { "<id>": { "target": null | { "name": string, "kind": string, "concept": string, "where"?: string } } } }`;
+
+/** The labeler's input for a batch of positive probes. */
+export function correctionTargetMessages(
+  probes: readonly Pick<WardenProbe, 'id' | 'ask' | 'moment' | 'hidden'>[],
+): { role: 'system' | 'user'; content: string }[] {
+  const body = probes
+    .map(
+      (p) =>
+        `## ${p.id}\n### Request\n${p.ask?.slice(0, 1500) || '(not recorded)'}\n\n### Agent turn\n${p.moment.slice(-1500) || '(not recorded)'}\n\n### Correction\n${(p.hidden ?? '').slice(0, 1500)}`,
+    )
+    .join('\n\n');
+  return [
+    { role: 'system', content: CORRECTION_TARGET_PROMPT },
+    {
+      role: 'user',
+      content: `Concept clusters: ${CONCEPT_CLUSTERS.join(', ')}\n\nLabel each item below.\n\n${body}`,
+    },
+  ];
+}
+
+const TARGET_KINDS = new Set(['primitive', 'system', 'pattern', 'rule']);
+
+/** One answer per id: a target, null for no existing target, undefined when missing or malformed. */
+export function parseCorrectionTargets(
+  content: string,
+  ids: readonly string[],
+): (CorrectionTarget | null | undefined)[] {
+  const start = content.indexOf('{');
+  const end = content.lastIndexOf('}');
+  let results: Record<string, { target?: unknown }> = {};
+  try {
+    results =
+      (JSON.parse(content.slice(start, end + 1)) as { results?: typeof results }).results ?? {};
+  } catch {
+    return ids.map(() => undefined);
+  }
+  return ids.map((id) => {
+    const item = results[id];
+    if (!item || !('target' in item)) return undefined;
+    if (item.target === null) return null;
+    const t = item.target as Record<string, unknown>;
+    if (typeof t.name !== 'string' || !t.name.trim() || typeof t.concept !== 'string')
+      return undefined;
+    return {
+      name: t.name.trim().slice(0, 120),
+      kind: (TARGET_KINDS.has(String(t.kind)) ? t.kind : 'pattern') as CorrectionTarget['kind'],
+      concept: t.concept
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-|-$/g, ''),
+      ...(typeof t.where === 'string' && t.where.trim()
+        ? { where: t.where.trim().slice(0, 160) }
+        : {}),
+    };
+  });
+}
+
+export const TARGET_CANONICAL_PROMPT = `You merge names of existing codebase things (primitives, systems, patterns, rules) that developers' corrections pointed to. All names given share one concept cluster. Names that refer to the same thing get the same canonical name; different things stay apart (when unsure, keep them apart). A canonical name is the clearest of the merged names, at most 80 characters.
+Respond with JSON only: { "canonical": { "<N1>": "<canonical name>", ... } } with every given key.`;
+
+/** The canonicalization input: one concept cluster's distinct target names, keyed N1..Nn. */
+export function targetCanonicalMessages(
+  concept: string,
+  names: readonly string[],
+): { role: 'system' | 'user'; content: string }[] {
+  return [
+    { role: 'system', content: TARGET_CANONICAL_PROMPT },
+    {
+      role: 'user',
+      content: `Cluster: ${concept}\n\n${names.map((n, i) => `N${i + 1}: ${n}`).join('\n')}`,
+    },
+  ];
+}
+
+/** Canonical names in order; a missing key keeps the name as given. */
+export function parseTargetCanonical(content: string, names: readonly string[]): string[] {
+  try {
+    const parsed = JSON.parse(
+      content.slice(content.indexOf('{'), content.lastIndexOf('}') + 1),
+    ) as {
+      canonical?: Record<string, unknown>;
+    };
+    return names.map((name, i) => {
+      const value = parsed.canonical?.[`N${i + 1}`];
+      return typeof value === 'string' && value.trim() ? value.trim().slice(0, 120) : name;
+    });
+  } catch {
+    return [...names];
+  }
+}
+
 /** The judge's instructions: one remark against the user's real next message. */
-export const WARDEN_JUDGE_PROMPT = `You grade one remark a narrow expert reviewer (a "Warden") made about an AI coding agent's turn.
-You see the Warden's domain, the agent's turn, the remark, and what the user actually said next.
+export const WARDEN_JUDGE_PROMPT = `You grade one remark a narrow expert reviewer (a "Warden") made during an AI coding session.
+The Warden spoke either on the user's message, before the agent worked, or on the agent's turn, after it.
+You see the Warden's domain, what the Warden saw, the remark, and what the user actually said next.
+When a TARGET is given (the existing rule, primitive, system or pattern the user pushed the agent toward), the test is the target, not wording: the remark matches when it names that same target (or points the agent to it unmistakably), however differently it is phrased.
 Answer two questions:
-- matches: does the remark say what the user's next message enforced: the same rule, or the same fix? A remark that is merely related, or generic, does not match.
+- matches: with a target, does the remark name the same target? Without one, does the remark say what the user's next message enforced: the same rule, or the same fix? A remark that is merely related, or generic, does not match.
 - inDomain: does the remark stay inside the Warden's stated domain?
 Respond with JSON only: { "matches": boolean, "inDomain": boolean, "reason": string } where reason is one short sentence.`;
 
-/** The judge's input for one remark. */
+/** The judge's input for one remark: what the Warden saw at its trigger point, and what came next. */
 export function wardenJudgeMessage(input: {
   domain: string;
   domainDescription: string;
+  /** The agent's turn; '' when the Warden spoke on the user's message only. */
   moment: string;
+  /** The user's message the agent was answering, when recorded. */
+  ask?: string;
+  trigger?: WardenProbeTrigger;
+  /** What the user pushed toward, when labelled. */
+  target?: CorrectionTarget;
   remark: string;
   hidden: string;
 }): string {
+  const before = input.trigger === 'user-message';
   return [
     `## Warden domain: ${input.domain}`,
     input.domainDescription,
-    '## Agent turn',
-    input.moment,
-    '## Remark',
+    ...(input.ask ? ["## The user's message", input.ask] : []),
+    ...(input.moment
+      ? [
+          before ? '## Agent turn (after the remark; the Warden did not see it)' : '## Agent turn',
+          input.moment,
+        ]
+      : []),
+    before
+      ? "## Remark (made on the user's message, before the agent worked)"
+      : '## Remark (made on the agent turn)',
     input.remark,
     "## The user's actual next message",
     input.hidden || '(the user let the turn pass without correcting it)',
+    ...(input.target
+      ? [
+          '## TARGET (what the user pushed the agent toward)',
+          `${input.target.canonical ?? input.target.name} (${input.target.kind}, ${input.target.concept}${input.target.where ? `, ${input.target.where}` : ''})`,
+        ]
+      : []),
   ].join('\n\n');
 }
 
@@ -210,3 +522,59 @@ export function parseWardenJudgement(text: string): WardenJudgement | undefined
     return undefined;
   }
 }
+
+/**
+ * The pointer judge: a Warden that classifies (relevant, and if so "look over here") is graded on
+ * where its pointer leads, not on advice quality. A pointer is as specific as the Warden can make
+ * it, and a general one is better than none (Aron, 2026-10-15): the exact thing, the target among a
+ * few candidates, or the right class.
+ */
+export const WARDEN_POINTER_JUDGE_PROMPT = `You grade one pointer a narrow classifier (a "Warden") gave a coding agent. The Warden only says whether something it knows applies to the agent's moment and, if so, points at it ("look over here: ..."); the agent then follows the pointer itself.
+You see the agent's moment, the TARGET (the existing thing that actually applies, with where it is written) and the pointer.
+Place the pointer on this ladder, leniently on wording (a doc section that holds the TARGET counts as naming it):
+- "exact": it points at the TARGET itself, alone or clearly first.
+- "candidates": it names at most three specific things to choose between, and the TARGET is one of them.
+- "class": it names no specific TARGET but points at the right class or area (the family, doc or section the TARGET belongs to), near enough to find it.
+- "wrong": it steers away from the TARGET (a different specific thing, an unrelated area, more than three candidates without the TARGET singled out).
+Respond with JSON only: { "level": "exact" | "candidates" | "class" | "wrong", "reason": string } where reason is one short sentence.`;
+
+export const POINTER_LEVELS = ['exact', 'candidates', 'class', 'wrong'] as const;
+export type PointerLevel = (typeof POINTER_LEVELS)[number];
+
+export interface WardenPointerJudgement {
+  readonly level: PointerLevel;
+  readonly reason?: string;
+}
+
+/** The pointer judge's input for one pointer. */
+export function wardenPointerJudgeMessage(input: {
+  moment: string;
+  target: CorrectionTarget;
+  pointer: string;
+}): string {
+  return [
+    '## Agent moment',
+    input.moment,
+    '## TARGET',
+    `${input.target.canonical ?? input.target.name} (${input.target.kind}${input.target.where ? `, ${input.target.where}` : ''})`,
+    '## Pointer',
+    input.pointer,
+  ].join('\n\n');
+}
+
+/** Parse a pointer judgement strictly; undefined when it is not the shape. */
+export function parseWardenPointerJudgement(text: string): WardenPointerJudgement | undefined {
+  const trimmed = text.trim();
+  const fenced = /^```(?:json)?\s*\n([\s\S]*?)\n?\s*```$/.exec(trimmed);
+  try {
+    const value = JSON.parse(fenced ? fenced[1]! : trimmed) as Record<string, unknown>;
+    const level = POINTER_LEVELS.find((l) => l === value.level);
+    if (!level) return undefined;
+    return {
+      level,
+      ...(typeof value.reason === 'string' ? { reason: value.reason.slice(0, 300) } : {}),
+    };
+  } catch {
+    return undefined;
+  }
+}

package/src/index.ts

@@ -36,6 +36,7 @@ export { HttpMemory } from './adapters/http-memory';
 export {
   claudemdSource,
   formatInstructionFiles,
+  INSTRUCTION_FILE_LIMIT,
   type InstructionFile,
   type InstructionReadOptions,
   instructionImports,
@@ -189,6 +190,30 @@ export {
   scrubSecrets,
   type TranscriptTurn,
 } from './feedback/correction';
+export {
+  DESIGN_SECTIONS,
+  type ExperimentRecord,
+  experimentProblems,
+  requireExperiment,
+  reviewPathOf,
+  TINY_MOMENTS,
+} from './feedback/experiment-gate';
+export {
+  AUTHORSHIP_MARKERS,
+  authorshipOf,
+  evidenceSnippet,
+  type FindingScope,
+  parseReviewFindings,
+  REUSE_HINT,
+  REVIEW_FINDINGS_PROMPT,
+  type ReviewFinding,
+  type ReviewMoment,
+  type ReviewReading,
+  reviewFindingMessages,
+  SCOPE_WEIGHT,
+  type SessionEvidence,
+  styleOf,
+} from './feedback/review-findings';
 export {
   type DomainAgreement,
   fixtureProbe,
@@ -222,15 +247,36 @@ export {
   scorePrefilter,
 } from './feedback/warden-prefilter';
 export {
+  type Authorship,
   type CharterScore,
+  CONCEPT_CLUSTERS,
+  CORRECTION_TARGET_PROMPT,
+  type CorrectionTarget,
+  correctionTargetMessages,
+  MISS_KINDS,
+  type MissKind,
+  POINTER_LEVELS,
+  type PointerLevel,
+  type ProbeSource,
+  parseCorrectionTargets,
+  parseTargetCanonical,
   parseWardenJudgement,
+  parseWardenPointerJudgement,
+  probeTriggers,
   scoreCharterRun,
+  TARGET_CANONICAL_PROMPT,
+  targetCanonicalMessages,
   WARDEN_JUDGE_PROMPT,
+  WARDEN_POINTER_JUDGE_PROMPT,
   type WardenJudgement,
+  type WardenPointerJudgement,
   type WardenProbe,
   type WardenProbeAnswer,
+  type WardenProbeTrigger,
   type WardenProbeTurn,
   wardenJudgeMessage,
+  wardenPointerJudgeMessage,
+  wilsonInterval,
 } from './feedback/warden-probes';
 export {
   type FlowConfig,
@@ -345,6 +391,7 @@ export {
   type ThreadMeta,
   type ThreadName,
   type ThreadReference,
+  type ThreadSetup,
   type ThreadSpawn,
   type ThreadStatus,
   threadTitle,

package/src/thread.ts

@@ -96,6 +96,12 @@ export interface ThreadMeta {
   /** 1 for a child of a main thread. */
   depth?: number;
 
+  /**
+   * Start-up of a thread whose Wardens are held in its own process (docs/THREAD-TREE.md spec C):
+   * turns typed meanwhile wait as `queued` until it is `ready` (or `degraded`).
+   */
+  setup?: ThreadSetup;
+
   /** Project that owns this thread. Scopes memory sources and tool calls. */
   projectId?: string;
 
@@ -109,6 +115,15 @@ export interface ThreadMeta {
   archivedAt?: number;
 }
 
+export interface ThreadSetup {
+  status: 'starting' | 'ready' | 'degraded';
+  startedAt: number;
+  readyAt?: number;
+  /** Every configured Warden, those holding a spare, and those that did not by the deadline. */
+  wardens: { expected: number; held: number; failed: string[] };
+  runtime: 'claude-in-session' | 'codex-in-process' | 'side-session';
+}
+
 export interface Dispatch<T = unknown> {
   readonly agentId: string;
   readonly timestamp: number;

package/src/types.ts

@@ -114,6 +114,11 @@ export interface CompletionOpts {
    * cached prefix; others ignore it. Messages are sent unchanged either way.
    */
   stablePrefix?: string;
+  /**
+   * Text right after `stablePrefix` that changes only between turns (a Warden's thread knowledge and
+   * the thread state). Providers that pre-start a call shape hold it; others ignore it.
+   */
+  threadPrefix?: string;
   /**
    * The executor's context split into standing parts and per-turn text. A provider that keeps a
    * native session delivers standing parts once and then only what changed (session-delivery.ts);
@@ -175,6 +180,13 @@ export interface LLMProvider {
   };
   complete(messages: LLMMessage[], opts?: CompletionOpts): Promise<CompletionResult>;
   stream?(messages: LLMMessage[], opts?: CompletionOpts): AsyncGenerator<LLMStreamEvent>;
+  /**
+   * Keep this call shape pre-started, so a later `complete` with the same `stablePrefix` and
+   * `threadPrefix` starts at once. `messages` end at those prefixes; no decision is made. Optional.
+   */
+  prestart?(messages: LLMMessage[], opts: CompletionOpts): void;
+  /** A thread closed: release whatever the provider holds for it. Optional. */
+  releaseThread?(threadId: string): Promise<void>;
 }
 
 export interface EmbeddingProvider {