@oh-my-pi/pi-coding-agent 16.2.2 → 16.2.3

package/src/advisor/__tests__/config.test.ts

@@ -0,0 +1,173 @@
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import * as fsp from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import {
+	advisorConfigFilePath,
+	discoverAdvisorConfigs,
+	loadWatchdogConfigFile,
+	resolveAdvisorConfigEditPath,
+	saveWatchdogConfigFile,
+	serializeWatchdogConfig,
+	slugifyAdvisorName,
+	type WatchdogConfigDoc,
+} from "../config";
+
+describe("discoverAdvisorConfigs", () => {
+	let tmp: string;
+	let agentDir: string;
+
+	beforeEach(async () => {
+		tmp = await fsp.mkdtemp(path.join(os.tmpdir(), "omp-advisor-config-"));
+		// Empty agent dir so the user-level search path can't pick up a real ~/.omp/WATCHDOG.yml.
+		agentDir = await fsp.mkdtemp(path.join(os.tmpdir(), "omp-advisor-agentdir-"));
+	});
+
+	afterEach(async () => {
+		await fsp.rm(tmp, { recursive: true, force: true });
+		await fsp.rm(agentDir, { recursive: true, force: true });
+	});
+
+	it("parses advisors, the model thinking suffix, tool filtering, and shared instructions", async () => {
+		const yaml = [
+			"instructions: Shared baseline for all advisors.",
+			"advisors:",
+			"  - name: Architecture",
+			"    model: x-ai/grok-code-fast:high",
+			"    instructions: Watch module boundaries.",
+			"  - name: Security Reviewer",
+			"    tools: [read, definitely-not-a-tool]",
+		].join("\n");
+		await Bun.write(path.join(tmp, "WATCHDOG.yml"), yaml);
+
+		const { advisors, sharedInstructions } = await discoverAdvisorConfigs(tmp, agentDir);
+		expect(advisors).toHaveLength(2);
+		const [arch, sec] = advisors;
+		expect(arch.name).toBe("Architecture");
+		// The model selector (incl. the `:high` thinking suffix) is stored verbatim;
+		// resolution happens later in the session, not here.
+		expect(arch.model).toBe("x-ai/grok-code-fast:high");
+		expect(arch.instructions).toBe("Watch module boundaries.");
+		expect(sec.name).toBe("Security Reviewer");
+		expect(sec.model).toBeUndefined();
+		// The unknown/non-read-only tool is dropped; only `read` survives.
+		expect(sec.tools).toEqual(["read"]);
+		expect(sharedInstructions).toBe("Shared baseline for all advisors.");
+	});
+
+	it("ignores a malformed YAML file without throwing", async () => {
+		await Bun.write(path.join(tmp, "WATCHDOG.yml"), "advisors: [unclosed bracket");
+		const result = await discoverAdvisorConfigs(tmp, agentDir);
+		expect(result.advisors).toEqual([]);
+		expect(result.sharedInstructions).toBeUndefined();
+	});
+
+	it("skips a file whose shape fails the schema (advisors must be a list)", async () => {
+		await Bun.write(path.join(tmp, "WATCHDOG.yml"), "advisors: not-an-array");
+		const result = await discoverAdvisorConfigs(tmp, agentDir);
+		expect(result.advisors).toEqual([]);
+	});
+
+	it("returns an empty roster when no config file exists", async () => {
+		const result = await discoverAdvisorConfigs(tmp, agentDir);
+		expect(result.advisors).toEqual([]);
+		expect(result.sharedInstructions).toBeUndefined();
+	});
+});
+
+describe("slugifyAdvisorName", () => {
+	it("lowercases and collapses non-alphanumeric runs to single hyphens", () => {
+		expect(slugifyAdvisorName("Security Reviewer")).toBe("security-reviewer");
+		expect(slugifyAdvisorName("  Arch/Boundaries!  ")).toBe("arch-boundaries");
+	});
+
+	it("falls back to 'advisor' when nothing alphanumeric survives", () => {
+		expect(slugifyAdvisorName("!!!")).toBe("advisor");
+	});
+});
+
+describe("WATCHDOG.yml file round-trip", () => {
+	let tmp: string;
+	beforeEach(async () => {
+		tmp = await fsp.mkdtemp(path.join(os.tmpdir(), "omp-advisor-file-"));
+	});
+	afterEach(async () => {
+		await fsp.rm(tmp, { recursive: true, force: true });
+	});
+
+	const doc: WatchdogConfigDoc = {
+		instructions: 'Shared baseline.\nSecond line with: a colon and "quotes".',
+		advisors: [
+			{ name: "Architecture", model: "x-ai/grok-code-fast:high", instructions: "Watch module boundaries." },
+			{ name: "Security", tools: ["read", "grep"] },
+		],
+	};
+
+	it("saves and reloads a doc byte-equivalently (incl. multiline and special chars)", async () => {
+		const file = path.join(tmp, "WATCHDOG.yml");
+		await saveWatchdogConfigFile(file, doc);
+		const loaded = await loadWatchdogConfigFile(file);
+		expect(loaded).toEqual(doc);
+	});
+
+	it("serializes block-style YAML that the discovery path also parses", async () => {
+		const file = path.join(tmp, "WATCHDOG.yml");
+		await saveWatchdogConfigFile(file, doc);
+		const text = await Bun.file(file).text();
+		// Block style (not the flow `{...}` form), so it stays hand-editable.
+		expect(text).toContain("advisors:");
+		expect(text).not.toMatch(/^\{/);
+		const { advisors, sharedInstructions } = await discoverAdvisorConfigs(tmp, tmp);
+		expect(advisors.map(a => a.name)).toEqual(["Architecture", "Security"]);
+		expect(sharedInstructions).toContain("Shared baseline.");
+	});
+
+	it("removes the file when the doc is empty so legacy discovery resumes", async () => {
+		const file = path.join(tmp, "WATCHDOG.yml");
+		await saveWatchdogConfigFile(file, doc);
+		await saveWatchdogConfigFile(file, { advisors: [] });
+		expect(await Bun.file(file).exists()).toBe(false);
+		// Loading a missing file yields an empty doc, never throws.
+		expect(await loadWatchdogConfigFile(file)).toEqual({ advisors: [] });
+	});
+
+	it("returns an empty serialization for an empty doc", () => {
+		expect(serializeWatchdogConfig({ advisors: [] })).toBe("");
+	});
+
+	it("resolves project and user scope paths", () => {
+		expect(advisorConfigFilePath("project", { projectDir: "/repo", agentDir: "/home/.omp" })).toBe(
+			path.join("/repo", "WATCHDOG.yml"),
+		);
+		expect(advisorConfigFilePath("user", { projectDir: "/repo", agentDir: "/home/.omp" })).toBe(
+			path.join("/home/.omp", "WATCHDOG.yml"),
+		);
+	});
+});
+
+describe("resolveAdvisorConfigEditPath", () => {
+	let tmp: string;
+	beforeEach(async () => {
+		tmp = await fsp.mkdtemp(path.join(os.tmpdir(), "omp-advisor-resolve-"));
+	});
+	afterEach(async () => {
+		await fsp.rm(tmp, { recursive: true, force: true });
+	});
+
+	const dirs = (d: string) => ({ projectDir: d, agentDir: d });
+
+	it("defaults to .yml when neither file exists", async () => {
+		expect(await resolveAdvisorConfigEditPath("project", dirs(tmp))).toBe(path.join(tmp, "WATCHDOG.yml"));
+	});
+
+	it("edits an existing .yaml in place when only it exists", async () => {
+		await Bun.write(path.join(tmp, "WATCHDOG.yaml"), "advisors: []\n");
+		expect(await resolveAdvisorConfigEditPath("project", dirs(tmp))).toBe(path.join(tmp, "WATCHDOG.yaml"));
+	});
+
+	it("prefers the canonical .yml when both exist", async () => {
+		await Bun.write(path.join(tmp, "WATCHDOG.yml"), "advisors: []\n");
+		await Bun.write(path.join(tmp, "WATCHDOG.yaml"), "advisors: []\n");
+		expect(await resolveAdvisorConfigEditPath("project", dirs(tmp))).toBe(path.join(tmp, "WATCHDOG.yml"));
+	});
+});

package/src/advisor/advise-tool.ts

@@ -6,7 +6,7 @@ import type {
 	AgentToolResult,
 	AgentToolUpdateCallback,
 } from "@oh-my-pi/pi-agent-core";
-import { escapeXmlText } from "@oh-my-pi/pi-utils";
+import { escapeXmlAttribute, escapeXmlText } from "@oh-my-pi/pi-utils";
 import { type } from "arktype";
 import adviseDescription from "../prompts/advisor/advise-tool.md" with { type: "text" };
 
@@ -24,12 +24,16 @@ export type AdvisorSeverity = "nit" | "concern" | "blocker";
 export interface AdviseDetails {
 	note: string;
 	severity?: AdvisorSeverity;
+	/** Which configured advisor produced this note (omitted for the default advisor). */
+	advisor?: string;
 }
 
 /** One queued advice note. */
 export interface AdvisorNote {
 	note: string;
 	severity?: AdvisorSeverity;
+	/** Which configured advisor produced this note (omitted for the default advisor). */
+	advisor?: string;
 }
 
 /** Details payload on the batched `advisor` custom message rendered in the transcript. */
@@ -55,7 +59,8 @@ export function formatAdvisorBatchContent(notes: readonly AdvisorNote[]): string
 	return notes
 		.map(n => {
 			const severity = n.severity ? ` severity="${n.severity}"` : "";
-			return `<advisory${severity} guidance="${ADVISOR_GUIDANCE}">\n${escapeXmlText(n.note)}\n</advisory>`;
+			const who = n.advisor ? ` advisor="${escapeXmlAttribute(n.advisor)}"` : "";
+			return `<advisory${who}${severity} guidance="${ADVISOR_GUIDANCE}">\n${escapeXmlText(n.note)}\n</advisory>`;
 		})
 		.join("\n");
 }
@@ -133,11 +138,11 @@ export function deriveAdvisorTelemetry(
 }
 
 /**
- * Side-effect-free investigation tools handed to the advisor agent so it can
- * inspect the workspace before weighing in. Names match the primary session's
- * tool instances, which the advisor reuses.
+ * The tools an advisor receives by default when its config omits `tools` — the
+ * read-only investigative set. The full available pool is every built tool the
+ * session has (the advisor is a full agent); a config's `tools` selects from it.
  */
-export const ADVISOR_READONLY_TOOL_NAMES: ReadonlySet<string> = new Set(["read", "grep", "glob"]);
+export const ADVISOR_DEFAULT_TOOL_NAMES: ReadonlySet<string> = new Set(["read", "grep", "glob"]);
 
 function advisorNoteDedupeKey(note: string): string {
 	return note.trim().replace(/\s+/g, " ");

package/src/advisor/config.ts

@@ -0,0 +1,256 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { isEnoent, logger } from "@oh-my-pi/pi-utils";
+import { type } from "arktype";
+import { YAML } from "bun";
+import { expandAtImports } from "../discovery/at-imports";
+import { BUILTIN_TOOL_NAMES, normalizeToolNames } from "../tools/builtin-names";
+import { collectConfigCandidates } from "./watchdog";
+
+/**
+ * One advisor declared in a `WATCHDOG.yml` file. `model` is a model selector
+ * with an optional `:level` thinking suffix (e.g. `x-ai/grok-code-fast:high`),
+ * resolved exactly like any other model override; `tools` is a subset of the
+ * read-only investigative tool names (default: all). `instructions` is the
+ * advisor's specialization, appended to the shared baseline.
+ */
+export interface AdvisorConfig {
+	name: string;
+	model?: string;
+	tools?: string[];
+	instructions?: string;
+}
+
+/**
+ * The result of walking the `WATCHDOG.yml`/`WATCHDOG.yaml` search path: the
+ * deduped advisor roster plus the concatenated top-level `instructions` baseline
+ * that is prepended (alongside `WATCHDOG.md`) to every advisor.
+ */
+export interface DiscoveredAdvisors {
+	advisors: AdvisorConfig[];
+	sharedInstructions: string | undefined;
+}
+
+const advisorEntrySchema = type({
+	name: "string",
+	"model?": "string",
+	"tools?": "string[]",
+	"instructions?": "string",
+});
+
+const watchdogYamlSchema = type({
+	"instructions?": "string",
+	"advisors?": advisorEntrySchema.array(),
+});
+
+/**
+ * Normalize an advisor name into a filesystem-/id-safe slug used for its
+ * transcript filename and session id: lowercase, non-alphanumerics collapsed to
+ * `-`, leading/trailing `-` trimmed. Falls back to `"advisor"` when nothing
+ * survives; callers dedupe collisions.
+ */
+export function slugifyAdvisorName(name: string): string {
+	const slug = name
+		.toLowerCase()
+		.replace(/[^a-z0-9]+/g, "-")
+		.replace(/^-+|-+$/g, "");
+	return slug || "advisor";
+}
+
+/** Built tool names, for validating an advisor's `tools` list. */
+const KNOWN_TOOL_NAMES = new Set<string>(BUILTIN_TOOL_NAMES);
+
+/**
+ * Keep only valid tool names from an advisor's `tools` list, dropping unknowns
+ * with a warning. The advisor is a full agent, so any built tool may be granted;
+ * the runtime further filters to what's actually available this session. An empty
+ * result (or no list) means "use the default subset" (read/grep/glob).
+ */
+function filterAdvisorTools(tools: string[] | undefined, sourcePath: string): string[] | undefined {
+	if (!tools || tools.length === 0) return undefined;
+	// Normalize legacy aliases (search→grep, find→glob) and dedupe before validating.
+	const filtered = normalizeToolNames(tools).filter(name => {
+		if (KNOWN_TOOL_NAMES.has(name)) return true;
+		logger.warn("Advisor config: dropping unknown tool", { path: sourcePath, tool: name });
+		return false;
+	});
+	return filtered.length > 0 ? filtered : undefined;
+}
+
+/**
+ * Discover advisor configs from `WATCHDOG.yml`/`WATCHDOG.yaml` files on the same
+ * user + project search path as `WATCHDOG.md`. Advisors are keyed by slug; a
+ * more-specific file (project leaf > project ancestor > user) replaces an earlier
+ * entry with the same slug. Top-level `instructions` across all files concatenate
+ * into the shared baseline. A malformed file is logged and skipped — never
+ * thrown — so a bad project config can't kill the session.
+ */
+export async function discoverAdvisorConfigs(cwd: string, agentDir?: string): Promise<DiscoveredAdvisors> {
+	const items = await collectConfigCandidates(cwd, agentDir, ["WATCHDOG.yml", "WATCHDOG.yaml"]);
+	const advisors = new Map<string, AdvisorConfig>();
+	const sharedParts: string[] = [];
+
+	for (const item of items) {
+		let parsed: unknown;
+		try {
+			parsed = YAML.parse(item.content);
+		} catch (err) {
+			logger.warn("Advisor config: failed to parse YAML", { path: item.path, error: String(err) });
+			continue;
+		}
+		if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+			logger.warn("Advisor config: expected a YAML mapping", { path: item.path });
+			continue;
+		}
+		const result = watchdogYamlSchema(parsed);
+		if (result instanceof type.errors) {
+			logger.warn("Advisor config: invalid schema", { path: item.path, error: result.summary });
+			continue;
+		}
+
+		if (result.instructions?.trim()) {
+			const expanded = (await expandAtImports(result.instructions, item.path)).trim();
+			if (expanded) sharedParts.push(expanded);
+		}
+
+		for (const entry of result.advisors ?? []) {
+			const slug = slugifyAdvisorName(entry.name);
+			const instructions = entry.instructions?.trim()
+				? (await expandAtImports(entry.instructions, item.path)).trim() || undefined
+				: undefined;
+			advisors.set(slug, {
+				name: entry.name,
+				model: entry.model?.trim() || undefined,
+				tools: filterAdvisorTools(entry.tools, item.path),
+				instructions,
+			});
+		}
+	}
+
+	return {
+		advisors: [...advisors.values()],
+		sharedInstructions: sharedParts.length > 0 ? sharedParts.join("\n\n") : undefined,
+	};
+}
+
+/** Which level a `WATCHDOG.yml` lives at: the project root or the user agent dir. */
+export type AdvisorConfigScope = "project" | "user";
+
+/**
+ * The editable contents of a single `WATCHDOG.yml` file: the shared top-level
+ * `instructions` plus the advisor roster. Unlike {@link DiscoveredAdvisors}, this
+ * is one file's raw view (no cross-level merge, no `@import` expansion) so the
+ * config editor round-trips exactly what the user wrote.
+ */
+export interface WatchdogConfigDoc {
+	instructions?: string;
+	advisors: AdvisorConfig[];
+}
+
+/**
+ * Resolve the `WATCHDOG.yml` path for a scope: `project` → `<projectDir>/WATCHDOG.yml`
+ * (discovered by the project-level walk), `user` → `<agentDir>/WATCHDOG.yml` (the
+ * user-level candidate).
+ */
+export function advisorConfigFilePath(
+	scope: AdvisorConfigScope,
+	dirs: { projectDir: string; agentDir: string },
+): string {
+	return path.join(scope === "user" ? dirs.agentDir : dirs.projectDir, "WATCHDOG.yml");
+}
+
+/**
+ * Resolve which `WATCHDOG.{yml,yaml}` to edit for a scope: prefer the canonical
+ * `.yml`, but when only a `.yaml` exists for that scope, edit it in place so an
+ * existing `.yaml` user isn't shown a blank editor and left with two files at the
+ * same precedence. Falls back to `.yml` when neither exists.
+ */
+export async function resolveAdvisorConfigEditPath(
+	scope: AdvisorConfigScope,
+	dirs: { projectDir: string; agentDir: string },
+): Promise<string> {
+	const dir = scope === "user" ? dirs.agentDir : dirs.projectDir;
+	const yml = path.join(dir, "WATCHDOG.yml");
+	const yaml = path.join(dir, "WATCHDOG.yaml");
+	if (!(await Bun.file(yml).exists()) && (await Bun.file(yaml).exists())) return yaml;
+	return yml;
+}
+
+/**
+ * Load one `WATCHDOG.yml` file for editing — raw, un-merged, un-expanded. Missing,
+ * unparseable, or schema-invalid files yield an empty doc (never throws) so the
+ * editor opens cleanly on a fresh or broken file.
+ */
+export async function loadWatchdogConfigFile(filePath: string): Promise<WatchdogConfigDoc> {
+	let text: string;
+	try {
+		text = await Bun.file(filePath).text();
+	} catch (err) {
+		if (!isEnoent(err))
+			logger.warn("Advisor config: failed to read for edit", { path: filePath, error: String(err) });
+		return { advisors: [] };
+	}
+	let parsed: unknown;
+	try {
+		parsed = YAML.parse(text);
+	} catch (err) {
+		logger.warn("Advisor config: failed to parse for edit", { path: filePath, error: String(err) });
+		return { advisors: [] };
+	}
+	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return { advisors: [] };
+	const result = watchdogYamlSchema(parsed);
+	if (result instanceof type.errors) {
+		logger.warn("Advisor config: invalid schema for edit", { path: filePath, error: result.summary });
+		return { advisors: [] };
+	}
+	return {
+		instructions: result.instructions?.trim() ? result.instructions : undefined,
+		advisors: (result.advisors ?? []).map(a => ({
+			name: a.name,
+			model: a.model?.trim() || undefined,
+			tools: a.tools?.length ? [...a.tools] : undefined,
+			instructions: a.instructions?.trim() ? a.instructions : undefined,
+		})),
+	};
+}
+
+/**
+ * Serialize an editable doc back to block-style `WATCHDOG.yml` text via Bun's
+ * `YAML.stringify` (the same API the repo uses for other hand-editable config),
+ * omitting empty fields. Round-trips through {@link loadWatchdogConfigFile}.
+ * Returns `""` for an empty doc.
+ */
+export function serializeWatchdogConfig(doc: WatchdogConfigDoc): string {
+	const out: { instructions?: string; advisors?: AdvisorConfig[] } = {};
+	if (doc.instructions?.trim()) out.instructions = doc.instructions;
+	if (doc.advisors.length > 0) {
+		out.advisors = doc.advisors.map(a => {
+			const entry: AdvisorConfig = { name: a.name };
+			if (a.model?.trim()) entry.model = a.model;
+			if (a.tools?.length) entry.tools = [...a.tools];
+			if (a.instructions?.trim()) entry.instructions = a.instructions;
+			return entry;
+		});
+	}
+	if (out.instructions === undefined && out.advisors === undefined) return "";
+	const text = YAML.stringify(out, null, 2);
+	return text.endsWith("\n") ? text : `${text}\n`;
+}
+
+/**
+ * Write an editable doc to `WATCHDOG.yml`. An empty doc removes the file so
+ * discovery falls back to the legacy single-advisor path rather than leaving an
+ * empty config behind.
+ */
+export async function saveWatchdogConfigFile(filePath: string, doc: WatchdogConfigDoc): Promise<void> {
+	const content = serializeWatchdogConfig(doc);
+	if (!content.trim()) {
+		try {
+			await fs.rm(filePath, { force: true });
+		} catch (err) {
+			if (!isEnoent(err)) throw err;
+		}
+		return;
+	}
+	await Bun.write(filePath, content);
+}

package/src/advisor/index.ts

@@ -1,4 +1,5 @@
 export * from "./advise-tool";
+export * from "./config";
 export * from "./emission-guard";
 export * from "./runtime";
 export * from "./transcript-recorder";

package/src/advisor/runtime.ts

@@ -209,6 +209,7 @@ export class AdvisorRuntime {
 			includeToolIntent: true,
 			watchedRoles: true,
 			expandPrimaryContext: true,
+			expandEditDiffs: true,
 		});
 		if (!md.trim()) return null;
 		return `### Session update\n\n${md}`;
@@ -434,11 +435,20 @@ function obfuscateDetails(
 function obfuscateAdvisorMessage(obfuscator: SecretObfuscator, message: AgentMessage): AgentMessage {
 	switch (message.role) {
 		case "user":
-		case "developer":
-		case "toolResult": {
+		case "developer": {
 			const content = obfuscateTextualContent(obfuscator, message.content as TextualContent);
 			return content === message.content ? message : ({ ...(message as object), content } as AgentMessage);
 		}
+		case "toolResult": {
+			const msg = message as AgentMessage & {
+				content: TextualContent;
+				details?: Record<string, unknown>;
+			};
+			const content = obfuscateTextualContent(obfuscator, msg.content);
+			const details = obfuscateDetails(obfuscator, msg.details);
+			if (content === msg.content && details === msg.details) return message;
+			return { ...(message as object), content, details } as AgentMessage;
+		}
 		case "assistant":
 			return obfuscateAssistantMessage(obfuscator, message as AssistantMessage) as AgentMessage;
 		case "custom":

package/src/advisor/transcript-recorder.ts

@@ -14,6 +14,23 @@ export const ADVISOR_TRANSCRIPT_FILENAME = `${ADVISOR_TRANSCRIPT_STEM}.jsonl`;
 
 const JSONL_SUFFIX = ".jsonl";
 
+/**
+ * Transcript filename for an advisor: `__advisor.jsonl` for the legacy/default
+ * advisor (empty slug), `__advisor.<slug>.jsonl` for a named advisor. The `.`
+ * separator keeps named files out of the output manager's `-<n>` bump namespace.
+ */
+export function advisorTranscriptFilename(slug: string): string {
+	return slug ? `${ADVISOR_TRANSCRIPT_STEM}.${slug}${JSONL_SUFFIX}` : ADVISOR_TRANSCRIPT_FILENAME;
+}
+
+/** Whether a filename is any advisor transcript (`__advisor.jsonl` or `__advisor.<slug>.jsonl`). */
+export function isAdvisorTranscriptName(name: string): boolean {
+	return (
+		name === ADVISOR_TRANSCRIPT_FILENAME ||
+		(name.startsWith(`${ADVISOR_TRANSCRIPT_STEM}.`) && name.endsWith(JSONL_SUFFIX))
+	);
+}
+
 /**
  * Append-only persister for an advisor agent's transcript.
  *
@@ -38,19 +55,25 @@ const JSONL_SUFFIX = ".jsonl";
 export class AdvisorTranscriptRecorder {
 	#manager: SessionManager | undefined;
 	#file: string | undefined;
+	#filename: string;
 	/** Serializes the async open/close against synchronous appends so records land in order. */
 	#queue: Promise<void>;
 
 	/**
+	 * @param filename Transcript filename within the session dir. Defaults to
+	 *   `__advisor.jsonl`; named advisors pass `__advisor.<slug>.jsonl` via
+	 *   {@link advisorTranscriptFilename}.
 	 * @param after Optional barrier the queue starts behind — used on the advisor
 	 *   on→off→on toggle so a fresh recorder's first `open` waits for the prior
-	 *   recorder's `close` and the two never hold the same `__advisor.jsonl` at once.
+	 *   recorder's `close` and the two never hold the same file at once.
 	 */
 	constructor(
 		private readonly resolveSessionFile: () => string | undefined,
 		private readonly resolveCwd: () => string,
+		filename: string = ADVISOR_TRANSCRIPT_FILENAME,
 		after?: Promise<unknown>,
 	) {
+		this.#filename = filename;
 		this.#queue = after
 			? after.then(
 					() => {},
@@ -83,7 +106,7 @@ export class AdvisorTranscriptRecorder {
 		}
 		const sessionFile = this.resolveSessionFile();
 		if (!sessionFile?.endsWith(JSONL_SUFFIX)) return;
-		const file = path.join(sessionFile.slice(0, -JSONL_SUFFIX.length), ADVISOR_TRANSCRIPT_FILENAME);
+		const file = path.join(sessionFile.slice(0, -JSONL_SUFFIX.length), this.#filename);
 		const cwd = this.resolveCwd();
 		this.#enqueue(async () => {
 			if (file !== this.#file) {