@kr78/pi-coding-agent 17.2.10

package/scripts/omp

@@ -0,0 +1,51 @@
+#!/bin/sh
+# Dev launcher for the omp CLI, installed by `bun run setup`.
+#
+# Problem it solves: Bun reads `bunfig.toml` from the *current working
+# directory* at startup and evaluates its `preload` entries before running the
+# script. A bun-shebang bin (what `bun link` creates for `src/cli.ts`)
+# therefore inherits whatever `preload` the directory you happen to be in
+# declares. Running `omp`/`pi` inside an unrelated Bun project can execute — and
+# crash on — that project's preload, e.g.
+#   error: Cannot find module '@v12sh/utils/frontmatter' from '.../loader.ts'
+#
+# Bun only reads the *exact* cwd (it does not walk parents) and ignores
+# `--config`/`BUN_BE_BUN` for this, so the fix is to launch Bun from an empty,
+# bunfig-free directory and restore the real cwd inside the process via the
+# preload shim alongside this file.
+set -e
+
+# Resolve this script's real location even when invoked through a symlink
+# (`$HOME/.bun/bin/omp` -> this file).
+self=$0
+while [ -L "$self" ]; do
+	link=$(readlink "$self")
+	case $link in
+	/*) self=$link ;;
+	*) self=$(dirname "$self")/$link ;;
+	esac
+done
+scripts_dir=$(CDPATH= cd -- "$(dirname -- "$self")" && pwd -P)
+cli=$scripts_dir/../src/cli.ts
+preload=$scripts_dir/omp.ts
+timing_preload=$scripts_dir/../../utils/src/module-timer.ts
+
+launch_dir=${OMP_DEV_LAUNCH_DIR:-${HOME}/.omp/.dev-cwd}
+mkdir -p "$launch_dir"
+
+OMP_LAUNCH_CWD=$PWD
+export OMP_LAUNCH_CWD
+cd "$launch_dir"
+# Herdr 0.7.5 validates the foreground process name. The macOS shell can
+# preserve OMP's identity while still running the development CLI through Bun.
+run_bun() {
+	if [ "${HERDR_ENV:-}" = 1 ] && [ "$(uname -s)" = Darwin ]; then
+		exec -a omp bun "$@"
+	fi
+	exec bun "$@"
+}
+
+if [ -n "${PI_TIMING:-}" ]; then
+	run_bun --preload "$preload" --preload "$timing_preload" "$cli" "$@"
+fi
+run_bun --preload "$preload" "$cli" "$@"

package/scripts/omp.ts

@@ -0,0 +1,19 @@
+/**
+ * Bun `--preload` shim for the omp dev launcher (`scripts/omp`).
+ *
+ * The launcher starts Bun from an empty, bunfig-free directory so a foreign
+ * project's `bunfig.toml` `preload` cannot run inside the omp CLI: Bun reads
+ * `bunfig.toml` from the *current working directory* on startup and evaluates
+ * its `preload` entries before the entrypoint, so a bun-shebang bin inherits
+ * whatever `preload` the directory you launched from declares (and crashes if
+ * that preload can't resolve). This shim is loaded before the entrypoint's
+ * imports run, so it restores the user's real working directory in time for
+ * import-time snapshots (e.g. `getProjectDir()` in `@oh-my-pi/pi-utils/dirs`).
+ */
+const launchCwd = process.env.OMP_LAUNCH_CWD;
+if (launchCwd) {
+	delete process.env.OMP_LAUNCH_CWD;
+	try {
+		process.chdir(launchCwd);
+	} catch {}
+}

package/scripts/security-compare.ts

@@ -0,0 +1,40 @@
+#!/usr/bin/env bun
+import * as path from "node:path";
+import { isEnoent } from "@oh-my-pi/pi-utils";
+import { compareSecurityProducers, importCodexSecurityBundle, parseSecurityScanBundle } from "../src/security";
+
+async function readBundle(directory: string) {
+	const root = path.resolve(directory);
+	let scan: unknown;
+	try {
+		scan = JSON.parse(await Bun.file(path.join(root, "scan.json")).text()) as unknown;
+	} catch (error) {
+		if (!isEnoent(error)) throw error;
+		return importCodexSecurityBundle(root, { repositoryRoot: root });
+	}
+	const findings = JSON.parse(await Bun.file(path.join(root, "findings.json")).text()) as unknown;
+	const report = await Bun.file(path.join(root, "report.md"))
+		.text()
+		.catch(() => undefined);
+	const sarifText = await Bun.file(path.join(root, "results.sarif"))
+		.text()
+		.catch(() => undefined);
+	return parseSecurityScanBundle({
+		scan,
+		findings,
+		report,
+		sarif: sarifText ? (JSON.parse(sarifText) as Record<string, unknown>) : undefined,
+	});
+}
+
+const [referenceDirectory, candidateDirectory, outputPath] = process.argv.slice(2);
+if (!referenceDirectory || !candidateDirectory) {
+	process.stderr.write(
+		"Usage: bun scripts/security-compare.ts <reference-scan-dir> <candidate-scan-dir> [output.json]\n",
+	);
+	process.exit(2);
+}
+const report = compareSecurityProducers(await readBundle(referenceDirectory), await readBundle(candidateDirectory));
+const serialized = `${JSON.stringify(report, null, 2)}\n`;
+if (outputPath) await Bun.write(path.resolve(outputPath), serialized);
+else process.stdout.write(serialized);

package/src/advisor/advise-tool.ts

@@ -0,0 +1,234 @@
+import { type } from "@oh-my-pi/omptype";
+import type {
+	AgentIdentity,
+	AgentTelemetryConfig,
+	AgentTool,
+	AgentToolContext,
+	AgentToolResult,
+	AgentToolUpdateCallback,
+} from "@oh-my-pi/pi-agent-core";
+import { escapeXmlAttribute, escapeXmlText } from "@oh-my-pi/pi-utils";
+import adviseDescription from "../prompts/advisor/advise-tool.md" with { type: "text" };
+
+const adviseSchema = type({
+	note: type("string").describe(
+		"One concrete piece of advice for the agent you are watching. Terse, specific, actionable.",
+	),
+	"severity?": type("'nit' | 'concern' | 'blocker'").describe("How strongly to weigh this. Omit for a plain nit."),
+});
+
+export type AdviseParams = typeof adviseSchema.infer;
+
+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. */
+export interface AdvisorMessageDetails {
+	notes: AdvisorNote[];
+}
+
+/**
+ * Behavioral framing for the watched agent — advice, not orders. Carried as a
+ * tag attribute (rather than a prose header) so the rendered agent-facing output
+ * stays a clean `<advisory>` block. The primary agent's system prompt never
+ * mentions advisories, so this is its only cue for how to treat them.
+ */
+const ADVISOR_GUIDANCE = "weigh, don't blindly obey";
+
+/**
+ * Render a batch of advisor notes as the agent-facing message body: one
+ * `<advisory>` element per note, severity as an attribute. Shared by the
+ * non-interrupting YieldQueue dispatcher and the interrupting steer path so both
+ * build byte-identical content.
+ */
+export function formatAdvisorBatchContent(notes: readonly AdvisorNote[]): string {
+	return notes
+		.map(n => {
+			const severity = n.severity ? ` severity="${n.severity}"` : "";
+			const who = n.advisor ? ` advisor="${escapeXmlAttribute(n.advisor)}"` : "";
+			return `<advisory${who}${severity} guidance="${ADVISOR_GUIDANCE}">\n${escapeXmlText(n.note)}\n</advisory>`;
+		})
+		.join("\n");
+}
+
+/**
+ * Whether advice at this severity should interrupt the running agent (delivered
+ * via the steering channel, aborting in-flight tools) rather than ride the
+ * non-interrupting aside queue that lands at the next step boundary. `concern`
+ * and `blocker` interrupt; a plain `nit` queues.
+ */
+export function isInterruptingSeverity(severity: AdvisorSeverity | undefined): boolean {
+	return severity === "concern" || severity === "blocker";
+}
+
+/** How an advisor note is routed to the primary. */
+export type AdvisorDeliveryChannel = "aside" | "steer" | "preserve";
+/** Half-open turn-count fence for the post-interrupt cooldown. */
+export function isAdvisorInterruptImmuneTurnActive(opts: {
+	completedTurns: number;
+	immuneTurnStart: number | undefined;
+	immuneTurns: number;
+}): boolean {
+	if (opts.immuneTurnStart === undefined || opts.immuneTurns <= 0) return false;
+	return opts.completedTurns < opts.immuneTurnStart + opts.immuneTurns;
+}
+
+/**
+ * Decide how one advisor note reaches the primary agent.
+ *
+ * - A `preserveOnly` caller records every note that arrives while the primary
+ *   is idle as a visible card and never starts a new primary turn.
+ * - A non-interrupting `nit` always rides the non-interrupting aside queue.
+ * - An interrupting `concern`/`blocker` is normally steered into the agent: into
+ *   the live turn while one is streaming, or (when idle) a triggered turn so the
+ *   advice is acted on immediately.
+ * - If the primary tail is already a terminal text answer and there is no queued
+ *   work, a late `concern` is preserved as a visible card instead of waking the
+ *   primary to restate completion. A `blocker` is the exception: it means the
+ *   agent handed off broken or unexercised work, so it still steers a triggered
+ *   turn to force the primary to acknowledge and continue before the turn is
+ *   considered done (#5628) — deferring it to the next user turn is the bug.
+ * - After a deliberate user interrupt (`autoResumeSuppressed`) the advisor must
+ *   not auto-resume the stopped run. While the agent is idle — or still tearing
+ *   the interrupted turn down (`aborting`) — the note is preserved as a visible
+ *   card instead of restarting the run. But once a turn is actively streaming
+ *   again (a resume the user already drove), steering the note in does NOT
+ *   auto-resume anything, so it is delivered live. Parking it during an active
+ *   run instead strands it (it never reaches the running agent) and the withheld
+ *   notes dump as one burst at the next user prompt — the bug this guards.
+ * - During the post-interrupt immune-turn window, further `concern`/`blocker`
+ *   notes are downgraded to asides; preservation still wins.
+ */
+export function resolveAdvisorDeliveryChannel(opts: {
+	severity: AdvisorSeverity | undefined;
+	autoResumeSuppressed: boolean;
+	streaming: boolean;
+	aborting: boolean;
+	terminalAnswerNoQueuedWork?: boolean;
+	interruptImmuneTurnActive?: boolean;
+	preserveOnly?: boolean;
+}): AdvisorDeliveryChannel {
+	if (opts.preserveOnly && !opts.streaming) return "preserve";
+	if (!isInterruptingSeverity(opts.severity)) return "aside";
+	if (opts.autoResumeSuppressed && (opts.aborting || !opts.streaming)) return "preserve";
+	if (opts.terminalAnswerNoQueuedWork && opts.severity !== "blocker" && !opts.streaming && !opts.aborting)
+		return "preserve";
+	if (opts.interruptImmuneTurnActive) return "aside";
+	return "steer";
+}
+
+/**
+ * Derive the advisor loop's telemetry from the primary session's config so the
+ * advisor model's GenAI spans and usage/cost hooks (onChatUsage, onCostDelta,
+ * costEstimator) fire under the same pipeline as every other model call —
+ * stamped with the advisor's own agent identity. `conversationId` is cleared so
+ * the advisor loop falls back to its own `-advisor` session id for
+ * `gen_ai.conversation.id` instead of inheriting the primary's conversation.
+ *
+ * Returns undefined when the primary has no telemetry (instrumentation off), so
+ * the advisor `Agent` stays a zero-overhead no-op as well.
+ */
+export function deriveAdvisorTelemetry(
+	primaryTelemetry: AgentTelemetryConfig | undefined,
+	identity: AgentIdentity,
+): AgentTelemetryConfig | undefined {
+	if (!primaryTelemetry) return undefined;
+	return { ...primaryTelemetry, agent: identity, conversationId: undefined };
+}
+
+/**
+ * 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_DEFAULT_TOOL_NAMES: ReadonlySet<string> = new Set(["read", "grep", "glob"]);
+
+function advisorNoteDedupeKey(note: string): string {
+	return note.trim().replace(/\s+/g, " ");
+}
+
+/** Rank advisor severities so the dedupe state can detect a real escalation
+ *  (nit → concern → blocker) versus a verbatim repeat. `undefined` defers to
+ *  `nit` because the schema treats an omitted severity as a plain nit. */
+const ADVISOR_SEVERITY_RANK: Record<AdvisorSeverity, number> = { nit: 1, concern: 2, blocker: 3 };
+function advisorSeverityRank(severity: AdvisorSeverity | undefined): number {
+	return ADVISOR_SEVERITY_RANK[severity ?? "nit"];
+}
+
+export class AdviseTool implements AgentTool<typeof adviseSchema, AdviseDetails> {
+	readonly name = "advise";
+	readonly label = "Advise";
+	readonly description = adviseDescription;
+	readonly parameters = adviseSchema;
+	readonly intent = "omit" as const;
+	/** Highest delivered severity rank per normalized note. A new call passes
+	 *  through only when its rank strictly exceeds the recorded one (a real
+	 *  escalation: nit → concern → blocker), so an advisor cannot bypass dedupe
+	 *  by retagging the same text at a lower or equal severity. */
+	#deliveredNoteSeverities = new Map<string, number>();
+	#inProgressUpdate = false;
+
+	constructor(private readonly onAdvice: (note: string, severity?: AdviseDetails["severity"]) => void) {}
+
+	/**
+	 * Mark whether the next advisor prompt reviews an in-progress primary turn.
+	 * Non-blockers are withheld until a completed update so partial work does
+	 * not interrupt the primary before it can finish its planned steps.
+	 */
+	beginUpdate(inProgress: boolean): void {
+		this.#inProgressUpdate = inProgress;
+	}
+
+	/** Clear delivered-note memory when the advisor starts a fresh conversation. */
+	resetDeliveredNotes(): void {
+		this.#deliveredNoteSeverities.clear();
+		this.#inProgressUpdate = false;
+	}
+
+	async execute(
+		_toolCallId: string,
+		args: AdviseParams,
+		_signal?: AbortSignal,
+		_onUpdate?: AgentToolUpdateCallback<AdviseDetails>,
+		_context?: AgentToolContext,
+	): Promise<AgentToolResult<AdviseDetails>> {
+		if (this.#inProgressUpdate && args.severity !== "blocker") {
+			return {
+				content: [{ type: "text", text: "Recorded." }],
+				details: { note: args.note, severity: args.severity },
+				useless: true,
+			};
+		}
+		const key = advisorNoteDedupeKey(args.note);
+		const rank = advisorSeverityRank(args.severity);
+		const previousRank = this.#deliveredNoteSeverities.get(key) ?? 0;
+		if (rank <= previousRank) {
+			return {
+				content: [{ type: "text", text: "Duplicate advice ignored." }],
+				details: { note: args.note, severity: args.severity },
+				useless: true,
+			};
+		}
+		this.#deliveredNoteSeverities.set(key, rank);
+		this.onAdvice(args.note, args.severity);
+		return {
+			content: [{ type: "text", text: "Recorded." }],
+			details: { note: args.note, severity: args.severity },
+			useless: true,
+		};
+	}
+}

package/src/advisor/config.ts

@@ -0,0 +1,341 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { type } from "@oh-my-pi/omptype";
+import { isEnoent, logger } from "@oh-my-pi/pi-utils";
+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
+ * `BUILTIN_TOOL_NAMES` — any built-in name, including mutating tools such as
+ * `edit`/`write`/`bash` (the advisor is a full agent). Omitted falls back to
+ * the default `read`/`grep`/`glob` subset; an explicit empty list grants no
+ * tools. `instructions` is the advisor's specialization, appended to the shared
+ * baseline.
+ */
+export interface AdvisorConfig {
+	name: string;
+	model?: string;
+	tools?: string[];
+	instructions?: string;
+	/** Per-advisor on/off toggle (default `true`). When `false`, the advisor
+	 *  stays in the roster but its runtime is never built — it shows `○` in
+	 *  the status line and `/advisor status` rather than disappearing. */
+	enabled?: boolean;
+}
+
+/**
+ * Runtime health of a single advisor, surfaced in stats and the status line.
+ * - `running` — actively processing primary turns
+ * - `paused` — user-toggled off via per-advisor switch (runtime disposed)
+ * - `quota_exhausted` — provider returned a quota/rate-limit error; the
+ *   runtime auto-retries after a cooldown so it can resume without user action
+ * - `error` — repeated transient failures; backlog dropped to prevent stall
+ * - `no_model` — no model resolved for this advisor's role/explicit model
+ */
+export type AdvisorRuntimeStatus = "running" | "paused" | "quota_exhausted" | "error" | "no_model";
+
+/**
+ * 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",
+	"enabled?": "boolean",
+});
+
+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";
+}
+
+const UUID_V7_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const ADVISOR_PROVIDER_SESSION_KEY_SEPARATOR = "\u0000";
+
+/**
+ * Returns a stable provider-facing UUIDv7 for one advisor within one primary session.
+ *
+ * Codex treats `session_id`/`conversation_id` as a UUID-shaped routing identity,
+ * so advisor labels such as `-advisor` stay local-only.
+ */
+export function getOrCreateAdvisorProviderSessionId(
+	ids: Map<string, string>,
+	primarySessionId: string | undefined,
+	slug: string,
+	randomSessionId: () => string = () => Bun.randomUUIDv7(),
+): string | undefined {
+	if (!primarySessionId) return undefined;
+	const key = `${primarySessionId}${ADVISOR_PROVIDER_SESSION_KEY_SEPARATOR}${slug}`;
+	const existing = ids.get(key);
+	if (existing) return existing;
+
+	const next = randomSessionId();
+	if (!UUID_V7_PATTERN.test(next)) {
+		throw new Error("Advisor provider session id generator returned a non-UUIDv7 value");
+	}
+	ids.set(key, next);
+	return next;
+}
+
+/** 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.
+ * `undefined` means "use the default subset" (read/grep/glob); only an explicit
+ * raw empty list means "no tools".
+ */
+function filterAdvisorTools(tools: string[] | undefined, sourcePath: string): string[] | undefined {
+	if (tools === undefined) return undefined;
+	if (tools.length === 0) return [];
+	// 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,
+				enabled: entry.enabled,
+			});
+		}
+	}
+
+	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: [] };
+	}
+	const advisors = (result.advisors ?? []).map(a => {
+		const advisor: AdvisorConfig = { name: a.name };
+		if (a.model?.trim()) advisor.model = a.model;
+		if (a.tools !== undefined) advisor.tools = [...a.tools];
+		if (a.instructions?.trim()) advisor.instructions = a.instructions;
+		if (a.enabled !== undefined) advisor.enabled = a.enabled;
+		return advisor;
+	});
+	const doc: WatchdogConfigDoc = { advisors };
+	if (result.instructions?.trim()) doc.instructions = result.instructions;
+	return doc;
+}
+
+/**
+ * Serialize an editable doc back to canonical, hand-editable `WATCHDOG.yml`.
+ * Multiline instruction fields use literal block scalars while scalar quoting
+ * delegates to Bun's YAML encoder. Round-trips through {@link loadWatchdogConfigFile}.
+ * Returns `""` for an empty doc.
+ */
+
+function appendYamlString(lines: string[], indent: string, key: string, value: string): void {
+	const hasSignificantLeadingWhitespace = value.split("\n").some(line => /^[ \t]/.test(line));
+	if (!value.includes("\n") || hasSignificantLeadingWhitespace) {
+		lines.push(`${indent}${key}: ${YAML.stringify(value)}`);
+		return;
+	}
+	const normalized = value.replaceAll("\r\n", "\n");
+	let trailingNewlines = 0;
+	for (let index = normalized.length - 1; index >= 0 && normalized[index] === "\n"; index--) {
+		trailingNewlines++;
+	}
+	const chomp = trailingNewlines === 0 ? "|2-" : trailingNewlines === 1 ? "|2" : "|2+";
+	const body = trailingNewlines === 0 ? normalized : normalized.slice(0, -trailingNewlines);
+	lines.push(`${indent}${key}: ${chomp}`);
+	for (const line of body.split("\n")) {
+		lines.push(`${indent}  ${line}`);
+	}
+	for (let index = 1; index < trailingNewlines; index++) {
+		lines.push(`${indent}  `);
+	}
+}
+
+export function serializeWatchdogConfig(doc: WatchdogConfigDoc): string {
+	const lines: string[] = [];
+	if (doc.instructions?.trim()) appendYamlString(lines, "", "instructions", doc.instructions);
+	if (doc.advisors.length > 0) {
+		lines.push("advisors:");
+		for (const advisor of doc.advisors) {
+			lines.push(`  - name: ${YAML.stringify(advisor.name)}`);
+			if (advisor.model?.trim()) lines.push(`    model: ${YAML.stringify(advisor.model)}`);
+			if (advisor.tools !== undefined) {
+				if (advisor.tools.length === 0) {
+					lines.push("    tools: []");
+				} else {
+					lines.push("    tools:");
+					for (const tool of advisor.tools) {
+						lines.push(`      - ${YAML.stringify(tool)}`);
+					}
+				}
+			}
+			if (advisor.instructions?.trim()) {
+				appendYamlString(lines, "    ", "instructions", advisor.instructions);
+			}
+			if (advisor.enabled !== undefined) lines.push(`    enabled: ${advisor.enabled}`);
+		}
+	}
+	return lines.length === 0 ? "" : `${lines.join("\n")}\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);
+}