ytdb-slate 0.1.0

package/docs/review-rules.md

@@ -0,0 +1,172 @@
+# Slate review rules
+
+How the orchestrator reviews work produced by worker threads. Review
+threads are created dynamically like any other thread; there is no fixed
+roster. These rules govern how reviews are composed, not who performs
+them. Worker threads do not automatically load this document. When
+dispatching a reviewer, either embed in the task text the perspective's
+charter (§3), the reasoning obligations (§7), and the output contract
+(§4: the perspective's ID prefix, the severity vocabulary
+blocker/should-fix/suggestion, and a closing compact findings block —
+one `ID` | `severity` | `location` | `one-line summary` |
+`counterexample gist` line per finding, see §5), or direct the
+reviewer to read the relevant sections of this file itself (worker
+threads can read files; they just do not receive this one
+automatically).
+
+## 1. When to review
+
+- Every non-trivial change gets reviewed before it is declared done.
+- Rigor scales with risk of the change, never with effort already spent.
+  When in doubt, review more.
+- For long multi-step work streams, review high-risk steps in isolation
+  right after they land — defects localized to one step get buried once
+  the diff folds into the cumulative result — and always review the
+  cumulative diff at the end regardless of per-step reviews.
+
+## 2. Reviewers are fresh threads
+
+- A review perspective is always a NEW thread. Never reuse the
+  implementing thread and never review substantial work yourself: fresh
+  eyes are the point.
+- Do not pass implementer episodes or implementer reasoning to
+  reviewers. Give a reviewer the artifact/diff, the intent of the
+  change, its in-scope files, and its charter plus reasoning/output
+  obligations (see the intro).
+- Independent perspectives run in PARALLEL on the same artifact.
+
+## 3. Choose perspectives by what the change touches
+
+There is no fixed roster — compose perspectives per change. Each
+bullet below is that perspective's charter:
+
+- **Code baseline** (any production/test code change): correctness &
+  bugs (logic, null safety, resource leaks, lifecycle); code quality
+  (readability, duplication, error handling); test quality (do tests
+  verify behavior, cover the change, and would they fail on
+  regression?).
+- **Specialists**, added when the change touches their domain:
+  - concurrency — any defect requiring reasoning about thread
+    interleavings (locks, shared state, atomicity);
+  - security — public API surface, authentication, user input,
+    network, (de)serialization;
+  - performance — hot paths, lock contention, caching, algorithmic
+    complexity, large data structures;
+  - test structure — complex fixtures, shared state between tests,
+    isolation and lifecycle concerns.
+- **Project-supplied perspectives**: a consuming project may add
+  review perspectives via the `reviewPerspectivesPath` key in its
+  `slate.json` — a markdown file of additional charters (typically
+  domain specialists). Each charter in that file MUST declare its own
+  stable finding-ID prefix (uniqueness rules in §4). Compose them per
+  change exactly like the built-in perspectives above.
+- **Non-code artifacts** (docs, prompts, process rules, extension
+  guidance like this file) get their own perspectives INSTEAD of the
+  code baseline: internal consistency & cross-references; instruction
+  completeness (can a reader execute this without guessing?); context
+  budget (what becomes always-loaded vs on-demand); writing style;
+  and safety of any scripts/hooks/config touched.
+- **Mixed diffs**: scope each reviewer to its in-scope files. Code
+  reviewers never review process/docs files, and vice versa.
+- Selection is a judgment call, not a rigid filter — when in doubt,
+  include the perspective. Risk/complexity changes how deep iteration
+  goes (§6), never which perspectives run.
+
+## 4. Findings
+
+- Each reviewer emits findings with stable IDs prefixed by perspective
+  (BG = bugs, CQ = code quality, TQ = test quality, CN = concurrency,
+  SE = security, PF = performance, TS = test structure,
+  WC = consistency, WI = completeness, WB = context budget,
+  WS = writing style, WH = script/hook/config safety, RG = regression
+  (filed by gate threads)). IDs are cumulative across iterations and
+  are never renumbered — they are the sole addressing key for fixes
+  and verification.
+- Project-supplied perspectives (§3) emit findings under the prefix
+  their charter declares; those prefixes join the orchestrator's
+  cumulative ledger exactly like the built-in ones. Declared prefixes
+  MUST NOT collide with the built-in roster above (BG, CQ, TQ, CN, SE,
+  PF, TS, WC, WI, WB, WS, WH, RG) nor with each other. On collision
+  the built-in roster wins: the orchestrator assigns the colliding
+  charter a fresh non-colliding prefix at dispatch, records the
+  substitution in the ledger, and uses the substitute everywhere — the
+  declared prefix is never used. When two project charters collide
+  with each other, the charter appearing first in the perspectives
+  file keeps its declared prefix; later ones are reassigned.
+- The orchestrator owns the cumulative finding-ID ledger: when
+  spawning a later-iteration reviewer or gate thread, tell it the next
+  free number for its prefix.
+- Severity: **blocker** (must fix before done), **should-fix** (fix
+  unless explicitly justified and reported), **suggestion** (optional).
+- Synthesize across reviewers: deduplicate by location/root cause,
+  keep all contributing IDs on the merged finding, and take the
+  highest severity when duplicates disagree (upgrade-only — never
+  downgrade a severity during synthesis).
+
+## 5. Reviewers find, implementers fix
+
+- Review threads never edit files; fix work is dispatched to an
+  implementation thread (usually the one that produced the change, or
+  a fresh one if it is gone or compromised — context-poisoned or
+  repeatedly failing). The orchestrator never edits files itself.
+- Episodes are compressed summaries (~300–800 words), so full finding
+  prose does not reliably survive them. Reviewers must therefore end
+  their final response with a self-contained compact findings block —
+  one `ID` | `severity` | `location` | `one-line summary` |
+  `counterexample gist` line per finding — sized to survive episode
+  compression. Route fixes by passing the reviewer's episode reference
+  (`context`) plus the compact finding index (the orchestrator's
+  synthesized list of all open findings, one `ID` | `severity` |
+  `location` | `one-line summary` line each); fixers re-read the
+  affected code themselves instead of relying on reviewer prose.
+
+## 6. Iteration and termination
+
+- After fixes, re-verify each addressed finding — in a gate thread,
+  not by trusting the fixer's claim. A gate thread is a fresh thread
+  whose sole job is verdicts; it receives the compact finding index
+  (§5) and the fix diff, but not the fixer's or implementer's
+  episodes. Verdict per finding:
+  - **VERIFIED** — the fix resolves the finding;
+  - **REJECTED** — the change claimed as the fix does not address the
+    finding;
+  - **STILL OPEN** — the finding was not addressed, or the attempted
+    fix leaves the defect in place;
+  - **MOOT** — the finding is obsoleted by other changes;
+  - **REGRESSION** — the fix broke something else; file the breakage
+    as a new blocker (RG prefix).
+- Blockers loop until clear. Should-fix findings get up to 3
+  iterations for normal changes; go deeper only for high-risk changes.
+- No-progress rule: if an iteration clears nothing and surfaces no new
+  fixable finding, stop and escalate to the user instead of spinning.
+- Done = no blockers remain, addressed findings VERIFIED, and any
+  remaining should-fix/suggestions explicitly reported to the user.
+
+## 7. Semi-formal reasoning (how reviewers argue)
+
+Reviewers use semi-formal reasoning — structured argument between
+free-form chain-of-thought and formal proof (Ugare & Chandra, "Agentic
+Code Reasoning", arXiv:2603.01896). Embed these obligations in every
+review dispatch:
+
+- State the decision criteria (definitions) and numbered premises
+  before reaching any verdict.
+- Trace, don't guess: cite evidence from code actually read (file:line
+  or diff hunk) for every claim about behavior. Read third-party /
+  library code instead of assuming its semantics.
+- Enumerate cases exhaustively along the changed execution paths
+  (branches, error paths, boundary values); mark each case as checked
+  or explicitly out of scope.
+- Back every defect claim (blocker or should-fix) with a concrete
+  counterexample: the input, state, or interleaving that triggers the
+  defect, traced through the code.
+- Back every correctness claim ("no issue here") with a justification
+  for why no counterexample exists — not merely the absence of one
+  found.
+- Before finalizing, run an alternative-hypothesis check: "if the
+  opposite verdict were true, what evidence would exist?" — then look
+  for that evidence.
+- While exploring, log hypotheses explicitly (hypothesis → evidence
+  sought → confirmed / refuted / refined) instead of wandering.
+- Derive the final verdict explicitly from the stated definitions and
+  claims, not from overall impression.

package/docs/track-workflow.md

@@ -0,0 +1,310 @@
+# Track-based development workflow
+
+The mandatory flow for every change delivered under this workflow:
+
+Research → (lazy) research log → user design review → adversarial
+review → user approves the track split → per-track loop (implement →
+track code review → fixes → mandatory user review → marker commit) →
+delivery.
+
+Publishing is conditional on `workflow.draftPRs` in the project's
+`slate.json` (default: false). When it is ENABLED, an umbrella draft
+PR is created after both reviews pass and before implementation
+starts — see pr-publishing.md in this directory for all PR mechanics.
+When it is DISABLED, the workflow log is the change's durable record;
+its lifecycle is defined in § Research log below. Marker commits work
+identically in both modes.
+
+The flow scales with change size:
+
+| Change size | What applies |
+| --- | --- |
+| Multi-track change | Full flow as described above. |
+| Single-track change | No track split, no marker commits. Everything else applies. |
+| Trivial change (typo, doc-only, mechanical rename, obvious one-file fix) | No split. The planned-changes statement is a 2–3-sentence paragraph; the design review collapses into user consent to it. Micro adversarial review, or skip it with explicit user consent. |
+
+The mandatory user review gate applies at EVERY tier. For single-track
+and trivial changes the whole branch diff is the track, so the user
+review sits after the agent code review and before delivery.
+
+Throughout this document, the "planned-changes statement" is the
+high-level design summary of the change. With publishing enabled it
+becomes the Planned-changes section of the PR description (see
+pr-publishing.md); with publishing disabled it lives in the workflow
+log.
+
+## Research phase (lightweight)
+
+Research is interactive exploration before any implementation: read
+real source code, trace call chains, and clarify aims and constraints
+with the user. There is no design document, no implementation plan,
+and no mandatory artifacts. The phase ends when the initial design of
+the change is understood and has passed the user design review (see
+below).
+
+## Research log (lazy-triggered)
+
+Start research WITHOUT a log. Open one the moment any trigger below
+fires, then backfill the decisions already made — backfilling is cheap
+while they are still in context.
+
+| # | Trigger |
+| --- | --- |
+| 1 | Second non-trivial decision (a choice where a plausible alternative was rejected for a reason). |
+| 2 | First surprise — the codebase behaves differently than assumed. |
+| 3 | First risky invariant identified — concurrency, durability or recovery, transactional semantics, a public API or behavioral change. |
+| 4 | Research will cross a session boundary. |
+| 5 | The change is multi-track. |
+| 6 | The user requests it. |
+
+### Log format
+
+Four sections, opened with the log:
+
+- **Initial request** — verbatim, written once.
+- **Decision Log** — append-only. Each entry is at most 4 lines: the
+  decision, why, and the alternatives rejected. Each entry MUST be
+  self-sufficient in one sentence; optional evidence citations go in
+  as deep links.
+- **Surprises & Discoveries**
+- **Open Questions**
+
+Two more named sections join as the corresponding phase begins:
+
+- **Planned changes** — the planned-changes statement, added when the
+  design converges; the design review and adversarial review verdict
+  lines are appended at its end. (With publishing enabled this section
+  feeds the PR description at umbrella-PR creation.)
+- **Track table** — publishing disabled only: added when the user
+  approves the track split (constraints in § Track table). With
+  publishing enabled the table lives in the PR description from
+  creation instead.
+
+### Persistence
+
+During research the log lives as an untracked file `research-log.md`
+at the repo root. What happens next depends on `workflow.draftPRs`:
+
+- **Enabled** — the log's life ends at umbrella-PR creation: its
+  content folds into the PR description and the file is deleted
+  (mechanics owned by pr-publishing.md § Creation).
+- **Disabled (default)** — the log is RETAINED at the repo root as the
+  change's workflow log until the change is delivered (§ Delivery
+  below). The planned-changes statement and both verdict lines anchor
+  in its Planned changes section, the track table in its Track table
+  section (§ Log format), and post-design decisions keep appending to
+  the Decision Log.
+
+### Delivery (publishing disabled)
+
+A change is DELIVERED when its final squashed commit lands on the
+repository's default development branch, or when the user explicitly
+abandons it. At delivery the agent folds the log into the delivery
+commit's message body — the motivation, the planned-changes statement,
+and both verdict lines: the same content that would have become the PR
+description — strips the track table (track numbers are ephemeral
+branch-life identifiers and would dangle in history), resolves or
+explicitly hands any remaining Open Questions to the user, then
+deletes the log file. On abandonment the agent deletes the log file
+after offering its content to the user for archiving.
+
+### Under-trigger guardrail
+
+When shaping the planned-changes statement without a log, state this
+explicitly (e.g. "no log kept — one trivial decision, no surprises")
+so the user can override and request one.
+
+## User design review (mandatory, pre-adversarial)
+
+When research converges, the agent presents the design to the user:
+the proposed approach, key decisions with the alternatives rejected,
+risks, and open questions. The presentation input is keyed on log
+existence, the same way as the adversarial review's: log exists →
+present from the log; no log → present the draft planned-changes
+statement. The agent then loops on user feedback — revising the design
+(and log) — until the user explicitly approves. Only after that
+approval does the adversarial review run.
+
+Rationale: the user owns the design direction. Reviewing with the user
+first means the adversarial review attacks a stabilized, user-endorsed
+design instead of one the user may still redirect — adversarial rounds
+are not spent on designs that would change anyway. The loop mechanics
+mirror the track loop's mandatory user review (present → feedback →
+explicit approval); the position relative to machine review is
+deliberately inverted — here the user reviews first.
+
+Durable record — append a verdict line to the log:
+
+```
+Design review: user-approved — YYYY-MM-DD
+```
+
+With no log, append the line to the draft planned-changes statement
+instead. With publishing enabled it travels into the PR description at
+umbrella-PR creation (pr-publishing.md § Creation); with publishing
+disabled the workflow log's Planned changes section is the verdict
+line's only durable home — writing the first verdict line opens the
+log if none exists, seeded with the planned-changes statement. (Crossing a session boundary before the change is published
+or delivered is research-log trigger #4.) The verdict line is written
+at every tier; at the trivial tier it is appended after the
+planned-changes paragraph, which stands in for the Risks & accepted
+trade-offs subsection.
+
+Tier scaling: at the trivial tier the design review collapses into the
+user's consent to the 2–3-sentence planned-changes paragraph. With
+publishing enabled, the ask for trivial and single-track changes may
+be batched: the agent presents the design together with the draft PR
+description in ONE pre-adversarial ask, and the user's single approval
+covers both. Umbrella-PR creation still follows the adversarial
+review; the description is re-presented only if adversarial triage
+changed it.
+
+## Adversarial review (mandatory, pre-implementation)
+
+Adversarial review runs after the user approves the design in the user
+design review, BEFORE the planned-changes statement is finalized and
+implementation starts, for EVERY change. The rationale, briefly:
+critique activates latent knowledge that constructive planning does
+not (generator/critic asymmetry), and a fresh-context reviewer has no
+anchoring on the author's rationale.
+
+The reviewer must be a fresh context (sub-agent or fresh session) that
+did not author the decisions.
+
+Input is keyed on log existence:
+
+- Log exists → the adversary attacks the log (plus its cited
+  evidence).
+- No log → the adversary attacks the draft planned-changes statement.
+- Trivial tier → micro-review with one bounded question ("what breaks
+  / what am I not seeing?"), or skipped with explicit user consent.
+
+Charter scaling: for single-track changes, limit the mandate to
+correctness, hidden coupling, and missed alternatives — style and
+speculative scope creep are out of bounds.
+
+Licensed null verdict: "no substantive findings" is an acceptable,
+respected outcome — the review prompt must say so.
+
+Triage each finding with the user. Three outcomes:
+
+- **Strengthen** — enrich the alternatives-rejected rationale of the
+  attacked decision.
+- **Reverse** — change the decision now, while it is still cheap.
+- **Accept-as-risk** — record it in Open Questions / Risks.
+
+Triage runs with the user, so a Reverse outcome is itself
+user-endorsed; after any reversal, refresh the design-review verdict
+line (new date) before any further adversarial round (a round-2
+reversal refreshes the line before the change is declared reviewed).
+
+One round by default; run a second round only if any decision was
+actually reversed. Append a verdict line to the log (or to the draft
+planned-changes statement if there is no log — same homing rules as
+the design-review verdict line):
+
+```
+Adversarial review: passed, N accepted risks — YYYY-MM-DD
+```
+
+## Track loop
+
+A track is one unit in a stacked series: it builds on the tracks
+before it, stands alone as an independently reviewable diff, and
+carries as much of the change as one reviewable diff holds.
+
+Sizing (soft bounds): a track of ≤~12 in-scope files folds into a
+neighbor; >~20–25 in-scope files is a split candidate.
+
+The user approves the proposed track split before implementation
+starts. Mid-flight changes to the split are re-presented to the user.
+
+All development is linear on the single working branch; each track is
+a contiguous commit range. Track numbering is append-only: completed
+tracks never renumber, a replanned remainder gets new numbers, and
+abandoned planned tracks are struck through in the track table — their
+numbers are never reused.
+
+Per-track sequence:
+
+1. Implement the track, following the project's own engineering
+   guidelines for commit/test/push discipline.
+2. MANDATORY agent code review of the cumulative track diff
+   `git diff <prev-marker>..HEAD` — correctness, test coverage, style,
+   API surface, documentation sync — composed per review-rules.md in
+   this directory.
+3. Fix findings as normal commits.
+4. MANDATORY user review: present the track summary and the track diff
+   to the user, then loop on user feedback — landing fixes as normal
+   commits — until the user explicitly approves. The agent waits for
+   that approval; the marker commit certifies a fully user-reviewed
+   track.
+5. Land the marker commit.
+6. Update the track's row in the track table (status, scope drift);
+   revise the planned-changes statement only if reality diverged from
+   it.
+
+### Track table
+
+This section owns the track-table constraints. The table is a
+display-only index of the split: track names, one-line scopes,
+statuses — never commit SHAs, and never the source of truth for track
+boundaries (marker commits are, see § Marker commits). It lives in the
+umbrella PR description when publishing is enabled and in the workflow
+log's Track table section when it is disabled.
+
+## Marker commits (source of truth for track boundaries)
+
+Format — an empty commit with a zero-padded two-digit track number:
+
+```bash
+git commit --allow-empty -m "Track NN complete: <short name>"
+# e.g.  Track 03 complete: cache-refactor
+```
+
+List all boundaries offline:
+
+```bash
+git log --oneline --grep '^Track [0-9]* complete:'
+```
+
+Track N's diff is `marker(N-1)..marker(N)`; track 01's base is the
+merge-base with the repository's default development branch.
+
+Properties:
+
+- **Rebase-resilient** — markers are in the history being rebased, so
+  they move with it.
+- **Zero cleanup** — delivering the change as a single squashed unit
+  erases them.
+- The track table is never an alternative source of truth for
+  boundaries (constraints owned by § Track table).
+
+Single-track changes land no markers — the whole branch diff is the
+track.
+
+## Rebase note
+
+After any rebase of the working branch the markers move with the
+rebased history — nothing to fix in this baseline. Any layered process
+that pins refs to marker commits must re-pin them after a rebase.
+
+## Peer review (project-layered)
+
+This baseline contains no peer-review process. Projects may layer one
+— e.g. per-track satellite review PRs for separate peer reviewers —
+via a doctrine extension (the `doctrineExtraPath` key in the project's
+`slate.json`). A layered peer review supplements, never replaces, the
+mandatory per-track user review.
+
+## Layering richer workflows on top
+
+Richer internal planning and execution machinery — whatever agent
+tooling is in use — may be layered on top of this baseline, provided
+it satisfies the mandatory gates: a user design review before
+adversarial review, pre-implementation adversarial review, an agent
+code review per track, a mandatory user review per track, marker
+commits at track boundaries, and — when draft-PR publishing is
+enabled — the obligations of pr-publishing.md (umbrella draft PR
+before coding starts, user-performed merge). This document defines the
+baseline that applies regardless of the tooling.

package/extension/episodes.ts

@@ -0,0 +1,200 @@
+/**
+ * Episode compression (ExecPlan D5, D6, D8).
+ *
+ * An episode is the compressed, structured record of ONE completed thread
+ * action. It is produced by a single LLM call over the messages generated
+ * during that action, stored at <config dir>/slate/episodes/<id>.md, and returned to
+ * the orchestrator as the tool result — it IS the synchronization mechanism.
+ *
+ * Compressor model resolution (D5): config episodeModel → newest available
+ * Anthropic Sonnet → the worker's own model.
+ */
+
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { complete } from "@earendil-works/pi-ai/compat";
+import {
+	CONFIG_DIR_NAME,
+	convertToLlm,
+	serializeConversation,
+	type ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+
+const MAX_TRANSCRIPT_CHARS = 300_000;
+const COMPRESSOR_MAX_TOKENS = 4096;
+
+const EPISODE_SECTIONS = [
+	"## Intent",
+	"## Actions Taken",
+	"## Key Findings",
+	"## Artifacts Changed",
+	"## Open Issues",
+	"## Handoff Notes",
+];
+
+function compressorPrompt(task: string, transcript: string): string {
+	return `You are compressing one completed action of a worker thread into an episode:
+a durable, structured record another agent will rely on WITHOUT seeing the
+raw transcript. Retain decisions, discoveries, exact identifiers (paths,
+symbols, commands, versions, error messages) and outcomes. Drop tactical
+noise (retries, scrolling, dead ends — unless a dead end is itself a finding).
+Note: the transcript covers only THIS action; the thread may legitimately use
+context from its earlier actions that you cannot see — do not flag that as
+fabrication.
+Target 300-800 words. Output ONLY markdown with EXACTLY these sections:
+
+${EPISODE_SECTIONS.join("\n")}
+
+The action's task was:
+${task}
+
+Transcript:
+${transcript}`;
+}
+
+async function resolveCompressorModel(
+	ctx: ExtensionContext,
+	configured: string | undefined,
+	workerModel: { provider: string; id: string } | undefined,
+) {
+	if (configured) {
+		const slash = configured.indexOf("/");
+		if (slash > 0) {
+			const m = ctx.modelRegistry.find(configured.slice(0, slash), configured.slice(slash + 1));
+			if (m) return m;
+		}
+	}
+	try {
+		const available = await ctx.modelRegistry.getAvailable();
+		const sonnets = available
+			.filter((m: { provider: string; id: string }) => m.provider === "anthropic" && m.id.includes("sonnet"))
+			.sort((a: { id: string }, b: { id: string }) => b.id.localeCompare(a.id));
+		if (sonnets.length > 0) return sonnets[0];
+	} catch {
+		/* fall through */
+	}
+	if (workerModel) return ctx.modelRegistry.find(workerModel.provider, workerModel.id) ?? undefined;
+	return undefined;
+}
+
+export interface CompressEpisodeOptions {
+	ctx: ExtensionContext;
+	episodeId: string;
+	threadId: string;
+	threadName: string;
+	task: string;
+	status: "ok" | "failed";
+	diagnostics?: string; // failure diagnostics (D6)
+	messages: unknown[]; // AgentMessages produced during this action
+	workerModel?: { provider: string; id: string };
+	configuredModel?: string;
+	signal?: AbortSignal;
+}
+
+export interface CompressedEpisode {
+	text: string; // full episode markdown (header + body) as returned to the orchestrator
+	file: string;
+	compressor: string; // model used, or "(uncompressed fallback)"
+	costUsd: number; // USD cost of the compression LLM call (0 on fallback)
+}
+
+function lastAssistantText(messages: unknown[]): string {
+	for (let i = messages.length - 1; i >= 0; i--) {
+		const m = messages[i] as { role?: string; content?: Array<{ type: string; text?: string }> };
+		if (m.role === "assistant" && Array.isArray(m.content)) {
+			const text = m.content
+				.filter((c) => c.type === "text")
+				.map((c) => c.text ?? "")
+				.join("\n")
+				.trim();
+			if (text) return text;
+		}
+	}
+	return "(no output)";
+}
+
+export async function compressEpisode(opts: CompressEpisodeOptions): Promise<CompressedEpisode> {
+	const { ctx } = opts;
+	const dir = join(ctx.cwd, CONFIG_DIR_NAME, "slate", "episodes");
+	mkdirSync(dir, { recursive: true });
+	const file = join(dir, `${opts.episodeId}.md`);
+
+	let body: string | undefined;
+	let compressor = "(uncompressed fallback)";
+	let costUsd = 0;
+
+	try {
+		const model = await resolveCompressorModel(ctx, opts.configuredModel, opts.workerModel);
+		if (model) {
+			const auth = await ctx.modelRegistry.getApiKeyAndHeaders(model);
+			if (auth.ok && auth.apiKey) {
+				let transcript = serializeConversation(convertToLlm(opts.messages as never));
+				if (transcript.length > MAX_TRANSCRIPT_CHARS) {
+					transcript = `[transcript head truncated]\n...${transcript.slice(-MAX_TRANSCRIPT_CHARS)}`;
+				}
+				if (opts.diagnostics) {
+					transcript += `\n\n[dispatch diagnostics: ${opts.diagnostics}]`;
+				}
+				const response = await complete(
+					model,
+					{
+						messages: [
+							{
+								role: "user" as const,
+								content: [{ type: "text" as const, text: compressorPrompt(opts.task, transcript) }],
+								timestamp: Date.now(),
+							},
+						],
+					},
+					{
+						apiKey: auth.apiKey,
+						headers: auth.headers,
+						env: auth.env,
+						maxTokens: COMPRESSOR_MAX_TOKENS,
+						signal: opts.signal,
+					},
+				);
+				costUsd = response.usage?.cost?.total ?? 0;
+				const text = response.content
+					.filter((c: { type: string }): c is { type: "text"; text: string } => c.type === "text")
+					.map((c: { text: string }) => c.text)
+					.join("\n")
+					.trim();
+				if (text) {
+					body = text;
+					compressor = `${model.provider}/${model.id}`;
+				}
+			}
+		}
+	} catch {
+		/* fall back below */
+	}
+
+	if (!body) {
+		body = [
+			"## Intent",
+			opts.task,
+			"",
+			"## Key Findings",
+			"(episode compression unavailable — raw final worker output follows)",
+			"",
+			lastAssistantText(opts.messages).slice(0, 8000),
+			...(opts.diagnostics ? ["", "## Open Issues", opts.diagnostics] : []),
+		].join("\n");
+	}
+
+	const statusLabel = opts.status === "ok" ? "OK" : "FAILED";
+	const header = [
+		`# Episode ${opts.episodeId} — thread ${opts.threadId} (${opts.threadName}) — STATUS: ${statusLabel}`,
+		"",
+		`> task: ${opts.task.replace(/\s+/g, " ").slice(0, 200)}`,
+		`> date: ${new Date().toISOString()} | compressor: ${compressor}`,
+		...(opts.status === "failed" && opts.diagnostics ? [`> failure: ${opts.diagnostics.slice(0, 300)}`] : []),
+		"",
+		"",
+	].join("\n");
+
+	const text = `${header}${body}\n`;
+	writeFileSync(file, text, "utf8");
+	return { text, file, compressor, costUsd };
+}