oma-coding-agent 1.1.4

package/src/advisor/advise-tool.ts

@@ -0,0 +1,165 @@
+import type {
+	AgentIdentity,
+	AgentTelemetryConfig,
+	AgentTool,
+	AgentToolContext,
+	AgentToolResult,
+	AgentToolUpdateCallback,
+} from "@oh-my-pi/pi-agent-core";
+import { escapeXmlText } from "@oh-my-pi/pi-utils";
+import { type } from "arktype";
+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;
+}
+
+/** One queued advice note. */
+export interface AdvisorNote {
+	note: string;
+	severity?: AdvisorSeverity;
+}
+
+/** 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}"` : "";
+			return `<advisory${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 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.
+ * - 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; suppression preservation still wins.
+ */
+export function resolveAdvisorDeliveryChannel(opts: {
+	severity: AdvisorSeverity | undefined;
+	autoResumeSuppressed: boolean;
+	streaming: boolean;
+	aborting: boolean;
+	interruptImmuneTurnActive?: boolean;
+}): AdvisorDeliveryChannel {
+	if (!isInterruptingSeverity(opts.severity)) return "aside";
+	if (opts.autoResumeSuppressed && (opts.aborting || !opts.streaming)) 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 };
+}
+
+/**
+ * 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.
+ */
+export const ADVISOR_READONLY_TOOL_NAMES: ReadonlySet<string> = new Set(["read", "search", "find"]);
+
+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;
+
+	constructor(private readonly onAdvice: (note: string, severity?: AdviseDetails["severity"]) => void) {}
+
+	async execute(
+		_toolCallId: string,
+		args: AdviseParams,
+		_signal?: AbortSignal,
+		_onUpdate?: AgentToolUpdateCallback<AdviseDetails>,
+		_context?: AgentToolContext,
+	): Promise<AgentToolResult<AdviseDetails>> {
+		this.onAdvice(args.note, args.severity);
+		return {
+			content: [{ type: "text", text: "Recorded." }],
+			details: { note: args.note, severity: args.severity },
+			useless: true,
+		};
+	}
+}

package/src/advisor/index.ts

@@ -0,0 +1,4 @@
+export * from "./advise-tool";
+export * from "./runtime";
+export * from "./transcript-recorder";
+export * from "./watchdog";

package/src/advisor/runtime.ts

@@ -0,0 +1,270 @@
+import type { AgentMessage } from "@oh-my-pi/pi-agent-core";
+import { estimateTokens } from "@oh-my-pi/pi-agent-core/compaction";
+import { logger } from "@oh-my-pi/pi-utils";
+import { formatSessionHistoryMarkdown } from "../session/session-history-format";
+
+/** Minimal slice of `Agent` the runtime drives — satisfied by pi-agent-core `Agent`. */
+export interface AdvisorAgent {
+	prompt(input: string): Promise<void>;
+	abort(reason?: unknown): void;
+	reset(): void;
+	readonly state: { messages: AgentMessage[] };
+}
+
+export interface AdvisorRuntimeHost {
+	/** Live primary transcript (use `agent.state.messages`). */
+	snapshotMessages(): AgentMessage[];
+	/** Surface one advice note to the primary (enqueues into the session YieldQueue). */
+	enqueueAdvice(note: string, severity?: "nit" | "concern" | "blocker"): void;
+	/**
+	 * Pre-prompt context maintenance for the advisor's own append-only context.
+	 * Promotes the advisor model to a larger sibling when its context nears the
+	 * window (mirroring the primary's promote-first policy) and resolves `true`
+	 * when the advisor should re-prime — reset and replay the current
+	 * primary-bounded transcript — because promotion did not free enough room.
+	 * Optional: hosts that omit it get no maintenance (context only shrinks when
+	 * the primary's next compaction triggers {@link AdvisorRuntime.reset}).
+	 */
+	maintainContext?(incomingTokens: number): Promise<boolean>;
+}
+
+interface PendingDelta {
+	text: string;
+	turns: number;
+}
+
+interface CatchupWaiter {
+	threshold: number;
+	resolve: () => void;
+	finish: () => void;
+	timer?: NodeJS.Timeout;
+}
+
+export class AdvisorRuntime {
+	#lastCount = 0;
+	#pending: PendingDelta[] = [];
+	#busy = false;
+	#backlog = 0;
+	#consecutiveFailures = 0;
+	#latestMessages?: AgentMessage[];
+	#waiters: CatchupWaiter[] = [];
+	/** Bumped by every external {@link reset}/{@link dispose}. A drain iteration
+	 *  captures it before its awaits; a mismatch on resume means a reset aborted
+	 *  the in-flight advisor prompt, so the stale batch is dropped instead of
+	 *  being retried/requeued into the post-reset conversation. */
+	#epoch = 0;
+	disposed = false;
+
+	constructor(
+		private readonly agent: AdvisorAgent,
+		private readonly host: AdvisorRuntimeHost,
+		private readonly retryDelayMs = 1000,
+	) {}
+
+	get backlog(): number {
+		return this.#backlog;
+	}
+
+	onTurnEnd(messages?: AgentMessage[]): void {
+		if (this.disposed) return;
+		const all = messages ?? this.host.snapshotMessages();
+		this.#latestMessages = all;
+		const render = this.#renderDelta(all);
+		if (render) {
+			this.#pending.push({ text: render, turns: 1 });
+			this.#backlog++;
+			this.#notifyWaiters();
+			void this.#drain();
+		}
+	}
+
+	waitForCatchup(maxMs: number, threshold: number, signal?: AbortSignal): Promise<void> {
+		if (this.disposed || signal?.aborted || this.#backlog < threshold) return Promise.resolve();
+		const { promise, resolve } = Promise.withResolvers<void>();
+		let waiter!: CatchupWaiter;
+		const finish = (): void => {
+			const idx = this.#waiters.indexOf(waiter);
+			if (idx >= 0) this.#waiters.splice(idx, 1);
+			clearTimeout(waiter.timer);
+			signal?.removeEventListener("abort", finish);
+			resolve();
+		};
+		waiter = { threshold, resolve, finish, timer: setTimeout(finish, maxMs) };
+		this.#waiters.push(waiter);
+		signal?.addEventListener("abort", finish, { once: true });
+		if (signal?.aborted) {
+			finish();
+		}
+		return promise;
+	}
+
+	dispose(): void {
+		this.disposed = true;
+		this.#epoch++;
+		this.#pending = [];
+		this.#backlog = 0;
+		this.#consecutiveFailures = 0;
+		this.#wakeAllWaiters();
+		try {
+			this.agent.abort("advisor disposed");
+		} catch {}
+	}
+
+	#resetAdvisorContext(clearBacklog: boolean, wakeWaiters: boolean): void {
+		this.#lastCount = 0;
+		this.#pending = [];
+		this.#consecutiveFailures = 0;
+		if (clearBacklog) {
+			this.#backlog = 0;
+		}
+		if (wakeWaiters) {
+			this.#wakeAllWaiters();
+		}
+		try {
+			this.agent.reset();
+		} catch {}
+		try {
+			this.agent.abort("advisor reset");
+		} catch {}
+	}
+
+	/**
+	 * Re-prime the advisor after a history rewrite (compaction, session
+	 * switch/resume, branch). Clears the advisor's own (non-persisted) context
+	 * and rewinds the cursor to 0 so the NEXT turn replays the full current —
+	 * post-compaction — transcript, giving the advisor fresh context instead of
+	 * leaving it blind to everything before the rewrite.
+	 */
+	reset(): void {
+		this.#epoch++;
+		this.#resetAdvisorContext(true, true);
+	}
+
+	/**
+	 * Seed the cursor to the current transcript length when the advisor is enabled
+	 * mid-session. Prevents the next turn from replaying the entire history to the
+	 * advisor (which would be expensive and likely stale).
+	 */
+	seedTo(count: number): void {
+		this.#lastCount = count;
+		this.#pending = [];
+		this.#backlog = 0;
+		this.#consecutiveFailures = 0;
+		this.#wakeAllWaiters();
+	}
+
+	#renderDelta(messages?: AgentMessage[]): string | null {
+		const all = messages ?? this.#latestMessages ?? this.host.snapshotMessages();
+		if (all.length < this.#lastCount) {
+			this.#lastCount = all.length;
+			return null;
+		}
+		const delta = all
+			.slice(this.#lastCount)
+			.filter(m => !(m.role === "custom" && (m as { customType?: string }).customType === "advisor"));
+		this.#lastCount = all.length;
+		if (delta.length === 0) return null;
+		const md = formatSessionHistoryMarkdown(delta, {
+			includeThinking: true,
+			includeToolIntent: true,
+			watchedRoles: true,
+		});
+		if (!md.trim()) return null;
+		return `### Session update\n\n${md}`;
+	}
+
+	#notifyWaiters(): void {
+		for (let i = this.#waiters.length - 1; i >= 0; i--) {
+			const w = this.#waiters[i];
+			if (this.#backlog < w.threshold) {
+				w.finish();
+			}
+		}
+	}
+
+	#wakeAllWaiters(): void {
+		for (const w of [...this.#waiters]) {
+			w.finish();
+		}
+	}
+
+	async #drain(): Promise<void> {
+		if (this.#busy) return;
+		this.#busy = true;
+		try {
+			while (!this.disposed && this.#pending.length) {
+				const popped = this.#pending.splice(0);
+				const epoch = this.#epoch;
+				// Each delta already opens with a `### Session update` heading, so
+				// join with a blank line rather than a `---` rule.
+				const candidateBatch = popped.map(b => b.text).join("\n\n");
+				const turnsCovered = popped.reduce((sum, b) => sum + b.turns, 0);
+				const incomingTokens = estimateTokens({
+					role: "user",
+					content: candidateBatch,
+					timestamp: Date.now(),
+				});
+
+				let shouldReprime = false;
+				if (this.host.maintainContext) {
+					try {
+						shouldReprime = await this.host.maintainContext(incomingTokens);
+					} catch (err) {
+						logger.debug("advisor context maintenance failed", { err: String(err) });
+					}
+				}
+				// A reset/dispose during context maintenance invalidates this batch.
+				if (this.#epoch !== epoch) continue;
+
+				let batch: string | null;
+				let finalTurns: number;
+				if (shouldReprime) {
+					// Promotion could not fit the advisor's context — re-prime.
+					const newTurns = this.#pending.reduce((sum, b) => sum + b.turns, 0);
+					this.#resetAdvisorContext(false, false);
+					batch = this.#renderDelta(this.#latestMessages);
+					finalTurns = turnsCovered + newTurns;
+				} else {
+					batch = candidateBatch;
+					finalTurns = turnsCovered;
+				}
+
+				if (this.disposed || batch === null) {
+					this.#backlog = Math.max(0, this.#backlog - finalTurns);
+					this.#notifyWaiters();
+					continue;
+				}
+
+				let success = false;
+				try {
+					await this.agent.prompt(batch);
+					success = true;
+					this.#consecutiveFailures = 0;
+				} catch (err) {
+					// reset()/dispose() aborts the in-flight prompt; the rejection is the
+					// reset itself, not a transient advisor failure. Drop the stale batch
+					// (reset already cleared #pending and rewound the cursor) instead of
+					// requeuing it into the post-reset conversation.
+					if (this.#epoch !== epoch) continue;
+					logger.debug("advisor turn failed", { err: String(err) });
+					this.#consecutiveFailures++;
+					if (this.#consecutiveFailures >= 3) {
+						logger.warn("advisor failed consecutively 3 times; dropping backlog to prevent stall");
+						this.#consecutiveFailures = 0;
+						success = true;
+					} else {
+						this.#pending.unshift({ text: batch, turns: finalTurns });
+						await Bun.sleep(this.retryDelayMs);
+					}
+				}
+
+				if (success && this.#epoch === epoch) {
+					this.#backlog = Math.max(0, this.#backlog - finalTurns);
+					this.#notifyWaiters();
+				}
+			}
+		} finally {
+			this.#busy = false;
+		}
+	}
+}

package/src/advisor/transcript-recorder.ts

@@ -0,0 +1,136 @@
+import * as path from "node:path";
+import type { AgentMessage } from "@oh-my-pi/pi-agent-core";
+import type { Message, UserMessage } from "@oh-my-pi/pi-ai";
+import { logger } from "@oh-my-pi/pi-utils";
+import { SessionManager } from "../session/session-manager";
+
+/**
+ * Reserved transcript stem for advisor session files. Chosen so it cannot
+ * collide with a task subagent's `<id>.jsonl` (task ids are reserved against
+ * this exact stem in {@link AgentOutputManager}).
+ */
+export const ADVISOR_TRANSCRIPT_STEM = "__advisor";
+export const ADVISOR_TRANSCRIPT_FILENAME = `${ADVISOR_TRANSCRIPT_STEM}.jsonl`;
+
+const JSONL_SUFFIX = ".jsonl";
+
+/**
+ * Append-only persister for an advisor agent's transcript.
+ *
+ * The advisor is a passive reviewer with its own model usage, so — like a task
+ * subagent — its turns are written to a JSONL inside the owning session's
+ * artifacts dir (`<session>/__advisor.jsonl`, `<session>/<SubId>/__advisor.jsonl`
+ * for subagent advisors). That single file gives the advisor model proper usage
+ * attribution in `omp stats` (the stats parser scans the session dir
+ * recursively) and a read-only transcript in the Agent Hub, without making the
+ * advisor a registered, messageable peer.
+ *
+ * The target is derived from the *session file* (`getSessionFile()`), never
+ * `getArtifactsDir()` — subagents adopt the parent's artifact manager, so the
+ * artifacts dir points at the parent root and every subagent advisor would
+ * collide. The file path is resolved synchronously when a message finalizes and
+ * captured for the queued write, so a `/new`, resume, or session switch in
+ * flight can never misattribute an old advisor turn into the new session's file.
+ * On such a switch the previous writer is closed and the new file opened on the
+ * next recorded turn. The recorder never truncates: the advisor's in-memory
+ * context resets/compacts independently, but every billed turn is appended here.
+ */
+export class AdvisorTranscriptRecorder {
+	#manager: SessionManager | undefined;
+	#file: string | undefined;
+	/** Serializes the async open/close against synchronous appends so records land in order. */
+	#queue: Promise<void>;
+
+	/**
+	 * @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.
+	 */
+	constructor(
+		private readonly resolveSessionFile: () => string | undefined,
+		private readonly resolveCwd: () => string,
+		after?: Promise<unknown>,
+	) {
+		this.#queue = after
+			? after.then(
+					() => {},
+					() => {},
+				)
+			: Promise.resolve();
+	}
+
+	/**
+	 * Persist one finalized advisor message. Assistant turns carry the usage the
+	 * stats parser reads; tool results round out the Hub transcript; user deltas
+	 * (the advisor's "session update" prompts) are persisted but flagged
+	 * `synthetic`/agent-attributed so they never inflate user-message metrics.
+	 * Non-conversational message kinds are skipped.
+	 */
+	record(message: AgentMessage): void {
+		let persisted: Message;
+		switch (message.role) {
+			case "assistant":
+			case "toolResult":
+				persisted = message;
+				break;
+			case "user":
+				// Clone so the live advisor message stays untouched; mark synthetic so
+				// stats' user-message metrics skip these agent-internal review prompts.
+				persisted = { ...(message as UserMessage), synthetic: true, attribution: "agent" };
+				break;
+			default:
+				return;
+		}
+		const sessionFile = this.resolveSessionFile();
+		if (!sessionFile?.endsWith(JSONL_SUFFIX)) return;
+		const file = path.join(sessionFile.slice(0, -JSONL_SUFFIX.length), ADVISOR_TRANSCRIPT_FILENAME);
+		const cwd = this.resolveCwd();
+		this.#enqueue(async () => {
+			if (file !== this.#file) {
+				await this.#closeManager();
+				this.#manager = await SessionManager.open(file, undefined, undefined, {
+					initialCwd: cwd,
+					suppressBreadcrumb: true,
+				});
+				this.#file = file;
+			}
+			this.#manager?.appendMessage(persisted);
+		});
+	}
+
+	/** Flush pending writes (best-effort). */
+	flush(): Promise<void> {
+		return this.#enqueueResult(async () => {
+			if (this.#manager) await this.#manager.flush();
+		});
+	}
+
+	/** Flush and close the writer, releasing the session file. */
+	close(): Promise<void> {
+		return this.#enqueueResult(() => this.#closeManager());
+	}
+
+	async #closeManager(): Promise<void> {
+		const manager = this.#manager;
+		this.#manager = undefined;
+		this.#file = undefined;
+		if (!manager) return;
+		try {
+			await manager.close();
+		} catch (err) {
+			logger.debug("advisor transcript close failed", { err: String(err) });
+		}
+	}
+
+	#enqueue(work: () => Promise<void>): void {
+		this.#queue = this.#queue.then(work, work).catch(err => {
+			logger.debug("advisor transcript record failed", { err: String(err) });
+		});
+	}
+
+	#enqueueResult(work: () => Promise<void>): Promise<void> {
+		const next = this.#queue.then(work, work);
+		this.#queue = next.catch(() => {});
+		return next;
+	}
+}

package/src/advisor/watchdog.ts

@@ -0,0 +1,83 @@
+import * as os from "node:os";
+import * as path from "node:path";
+import { getAgentDir, isEnoent, logger } from "@oh-my-pi/pi-utils";
+import { expandAtImports } from "../discovery/at-imports";
+import { repo } from "../utils/git";
+
+/**
+ * Discover and load WATCHDOG.md files walking up from cwd, project .omp folder, and user agent dir.
+ * Returns formatted watchdog file blocks ready to be appended to the advisor system prompt.
+ */
+export async function discoverWatchdogFiles(cwd: string, agentDir?: string): Promise<string[]> {
+	const home = os.homedir();
+	const resolvedAgentDir = agentDir ?? getAgentDir();
+	const userPath = resolvedAgentDir ? path.resolve(resolvedAgentDir, "WATCHDOG.md") : null;
+	let repoRoot: string | null = null;
+	try {
+		repoRoot = await repo.root(cwd);
+	} catch (err) {
+		logger.debug("Failed to resolve git root for watchdog discovery", { err: String(err) });
+	}
+
+	const candidates = new Set<string>();
+
+	// 1. User level: ~/.omp/WATCHDOG.md (or active profile agent dir)
+	if (resolvedAgentDir) {
+		candidates.add(path.resolve(resolvedAgentDir, "WATCHDOG.md"));
+	}
+
+	// 2. Project levels (both standalone and native config .omp/): walk up from cwd to repoRoot / home
+	let current = cwd;
+	while (true) {
+		candidates.add(path.resolve(current, ".omp", "WATCHDOG.md"));
+		candidates.add(path.resolve(current, "WATCHDOG.md"));
+
+		if (current === (repoRoot ?? home)) break;
+		const parent = path.dirname(current);
+		if (parent === current) break;
+		current = parent;
+	}
+
+	const items: Array<{ path: string; content: string; level: "user" | "project"; depth: number }> = [];
+
+	for (const candidate of candidates) {
+		try {
+			const content = await Bun.file(candidate).text();
+			const expanded = await expandAtImports(content, candidate);
+			const parent = path.dirname(candidate);
+			const baseName = parent.split(path.sep).pop() ?? "";
+
+			const isUser = userPath !== null && candidate === userPath;
+			const ownerDir = baseName === ".omp" ? path.dirname(parent) : parent;
+			const ownerBaseName = ownerDir.split(path.sep).pop() ?? "";
+
+			if (isUser || !ownerBaseName.startsWith(".") || baseName === ".omp") {
+				const relative = path.relative(cwd, ownerDir);
+				const depth = relative === "" ? 0 : relative.split(path.sep).filter(Boolean).length;
+				items.push({
+					path: candidate,
+					content: expanded,
+					level: isUser ? "user" : "project",
+					depth,
+				});
+			}
+		} catch (err) {
+			if (!isEnoent(err)) {
+				logger.warn("Failed to read WATCHDOG.md candidate", { path: candidate, error: String(err) });
+			}
+		}
+	}
+
+	// Sort files so that user level comes first, then project level sorted by depth (descending).
+	// This means user-level rules are first, then project-level rules from ancestor directories down to the leaf directory (depth 0 is last/most prominent).
+	items.sort((a, b) => {
+		if (a.level !== b.level) {
+			return a.level === "user" ? -1 : 1;
+		}
+		return b.depth - a.depth;
+	});
+
+	return items.map(item => {
+		return `Especially pay attention to:\n<attention>\n${item.content}\n</attention>`;
+	});
+}

package/src/async/index.ts

@@ -0,0 +1 @@
+export * from "./job-manager";