@gavin-hu/my-pi-agent 0.12.0 → 0.13.1

package/extensions/bytefly/footer/budget.ts

@@ -0,0 +1,64 @@
+/**
+ * The session spend guardrail: one warning when the session's cost reaches the
+ * configured budget.
+ *
+ * A budget is an alert, not a limit. Nothing is blocked or aborted — a hard stop
+ * loses work, and the footer already shows the running cost — so this decides only
+ * whether the threshold has been crossed and what the one notice says.
+ *
+ * Pure: the caller has the priced spend and the currency, this shapes the answer.
+ * The amount formatting reuses the footer's own `formatCost`, so the notice and the
+ * status bar cannot disagree about precision or about a sub-minor-unit amount.
+ */
+
+import { noticeMessage, type NoticeMessage } from "../../../lib/notice.ts";
+import { formatCost } from "./render/format.ts";
+import type { Currency } from "./price/types.ts";
+
+/** Where the session stands against its budget. */
+export interface BudgetState {
+	/** The configured budget, in `currency`; `0` means the guardrail is off. */
+	limit: number;
+	/** What the session has spent so far, in `currency`. */
+	spent: number;
+	/** Whether the budget is on and has been reached. Inclusive: exactly `limit` counts. */
+	exceeded: boolean;
+}
+
+/** The session's position against its budget. */
+export function budgetState(limit: number, spent: number): BudgetState {
+	const safeLimit = Number.isFinite(limit) && limit > 0 ? limit : 0;
+	const safeSpent = Number.isFinite(spent) && spent > 0 ? spent : 0;
+	return { limit: safeLimit, spent: safeSpent, exceeded: safeLimit > 0 && safeSpent >= safeLimit };
+}
+
+/**
+ * The one notice a crossing posts.
+ *
+ * `warn` rather than `bad`: nothing failed, and nothing will be stopped. The
+ * content names the figures so the model reads the same sentence the user does,
+ * and says plainly that the session keeps running.
+ */
+export function budgetNotice(state: BudgetState, currency: Currency): NoticeMessage {
+	const spent = formatCost(state.spent, currency);
+	const limit = formatCost(state.limit, currency);
+	return noticeMessage({
+		content:
+			`Session spend reached the configured budget: ${spent} of ${limit}. ` +
+			"This is a warning only — the session continues; raise or clear `price.budget` to silence it.",
+		details: {
+			source: "bytefly",
+			title: "Session budget reached",
+			severity: "warn",
+			items: [
+				{ label: "spent", detail: spent },
+				{ label: "budget", detail: limit },
+			],
+		},
+	});
+}
+
+/** The one-line body an OS notification carries. */
+export function budgetBody(state: BudgetState, currency: Currency): string {
+	return `Session budget reached · ${formatCost(state.spent, currency)} of ${formatCost(state.limit, currency)}`;
+}

package/extensions/bytefly/footer/collect/snapshot.ts

@@ -7,12 +7,17 @@
  * hold thousands of entries and the footer renders on every frame. The config is
  * captured when the reader is built, so re-reading the file means building a new
  * reader (which is what installing the footer does).
+ *
+ * The child-run ledger's version joins the memo key: a finished subagent invalidates
+ * the same way an appended entry does, so the roll-up appears on the next frame
+ * without re-pricing every frame.
  */
 
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { DelegationLedger } from "../delegation.ts";
 import { createPricer } from "../price/price.ts";
 import type { ByteflyConfig } from "../price/types.ts";
-import type { ContextInfo, FooterData, StatusSnapshot } from "../types.ts";
+import type { ContextInfo, FooterData, StatusSnapshot, UsageTotals } from "../types.ts";
 import { emptyUsage, usageRecords } from "./entries.ts";
 
 /**
@@ -23,22 +28,41 @@ import { emptyUsage, usageRecords } from "./entries.ts";
  * are stale; this avoids copying the full entry list and rebuilding the session
  * projection per frame. Pi's own footer memoizes its stats on the same idea.
  */
-export function createSnapshotReader(config: ByteflyConfig) {
+export interface SnapshotReader {
+	/** Read a snapshot, re-pricing only when the session moved. */
+	(ctx: ExtensionContext, footerData: FooterData): StatusSnapshot;
+	/**
+	 * The usage totals from the last read, or undefined before the first frame.
+	 *
+	 * The budget guardrail reads the number the footer already priced instead of
+	 * walking the session a second time; if no frame has rendered yet there is
+	 * nothing stale to act on.
+	 */
+	peek(): UsageTotals | undefined;
+}
+
+export function createSnapshotReader(config: ByteflyConfig, delegation: DelegationLedger): SnapshotReader {
 	const price = createPricer(config);
 	let key: string | null = null;
 	let usage = emptyUsage();
+	let delegationTotals = { runs: 0, usage: emptyUsage() };
 	let cacheHitRate: number | null = null;
 	let context: ContextInfo = { tokens: null, contextWindow: 0, percent: null };
 
-	return (ctx: ExtensionContext, footerData: FooterData): StatusSnapshot => {
+	let last: UsageTotals | undefined;
+
+	const reader = ((ctx: ExtensionContext, footerData: FooterData): StatusSnapshot => {
 		const session = ctx.sessionManager;
 		const current = ctx.model;
-		const nextKey = `${session.getSessionId()}:${session.getLeafId() ?? ""}:${current?.provider ?? ""}/${current?.id ?? ""}`;
+		const nextKey = `${session.getSessionId()}:${session.getLeafId() ?? ""}:${current?.provider ?? ""}/${current?.id ?? ""}:${delegation.version()}`;
 		if (nextKey !== key) {
 			const active = current ? { provider: current.provider, model: current.id } : undefined;
 			const scanned = usageRecords(session.getEntries(), active);
 			usage = price(scanned.records);
 			cacheHitRate = scanned.cacheHitRate;
+			// The child runs are priced by the same pricer, so a currency or rate
+			// change moves both numbers together — and neither is folded into the other.
+			delegationTotals = { runs: delegation.runs(), usage: price(delegation.records()) };
 
 			const usageInfo = ctx.getContextUsage();
 			context = {
@@ -47,6 +71,7 @@ export function createSnapshotReader(config: ByteflyConfig) {
 				percent: usageInfo?.percent ?? null,
 			};
 			key = nextKey;
+			last = usage;
 		}
 
 		const model = current
@@ -65,6 +90,9 @@ export function createSnapshotReader(config: ByteflyConfig) {
 			currency: config.currency,
 			cacheHitRate,
 			providerCount: footerData.getAvailableProviderCount(),
+			delegation: delegationTotals,
 		};
-	};
+	}) as SnapshotReader;
+	reader.peek = () => last;
+	return reader;
 }

package/extensions/bytefly/footer/config.ts

@@ -16,7 +16,13 @@ export const CONFIG = {
 	gauge: { full: GLYPHS.gaugeFull, empty: GLYPHS.gaugeEmpty, widths: [10, 5, 3, 0] as const },
 	/** Separators printed before grouped and other segments. */
 	separators: { group: SEPARATORS.group, item: SEPARATORS.item },
-	icons: { branch: GLYPHS.branch, detached: GLYPHS.detached, worktree: GLYPHS.worktree, browse: GLYPHS.browse },
+	icons: {
+		branch: GLYPHS.branch,
+		detached: GLYPHS.detached,
+		worktree: GLYPHS.worktree,
+		browse: GLYPHS.browse,
+		delegation: GLYPHS.delegation,
+	},
 	/** Status key the worktree extension uses; routed to line 1's right zone. */
 	worktreeStatusKey: STATUS_KEYS.worktree,
 	/** Status key the file-browse extension uses; routed to line 1's right zone. */

package/extensions/bytefly/footer/delegation.ts

@@ -0,0 +1,100 @@
+/**
+ * The child-run ledger: what this session's delegated runs spent.
+ *
+ * `subagent` publishes one event per finished child process on
+ * `SUBAGENT_FINISHED_CHANNEL`. The footer shows that spend as its own number, so
+ * the session's total keeps meaning what it always did.
+ *
+ * The ledger keeps *pricing inputs*, not a total: `currency.code` can change
+ * between sessions (a settings edit re-installs the footer and rebuilds the
+ * pricer), and a stored figure would then be in the wrong unit. It also keeps the
+ * peak tariff honest, because each record carries the time the run finished.
+ *
+ * Bounded on purpose: the last {@link MAX_DELEGATION_RECORDS} runs are retained —
+ * each is a full child `pi` process, so hundreds in one session is already
+ * extraordinary — while the run count keeps counting past the window. Every field
+ * of an event is re-validated, because the bus is not a trusted channel.
+ */
+
+import type { SubagentFinishedEvent } from "../../../lib/events.ts";
+import type { UsageRecord } from "./types.ts";
+
+/** Runs whose pricing inputs are retained. */
+export const MAX_DELEGATION_RECORDS = 500;
+
+export interface DelegationLedger {
+	/** Note one finished child run; a malformed payload is ignored. */
+	note(event: unknown): void;
+	/** How many runs finished this session, including ones past the window. */
+	runs(): number;
+	/** Pricing inputs for the retained runs, oldest first. */
+	records(): UsageRecord[];
+	/** Changes on every noted run, so a reader can tell its totals are stale. */
+	version(): number;
+	/** Forget everything; called at session start. */
+	reset(): void;
+}
+
+/** A finite, non-negative number, or `null` when the field is not one. */
+function count(value: unknown): number | null {
+	return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : null;
+}
+
+/** A non-empty string, or `null`. */
+function text(value: unknown): string | null {
+	return typeof value === "string" && value.trim() !== "" ? value : null;
+}
+
+/** The event as a usage record, or `null` when it is not one we can price. */
+function toRecord(event: SubagentFinishedEvent): UsageRecord | null {
+	if (text(event.agent) === null) return null;
+	const input = count(event.input);
+	const output = count(event.output);
+	const cacheRead = count(event.cacheRead);
+	const cacheWrite = count(event.cacheWrite);
+	const recordedCost = count(event.recordedCost);
+	// A type-mismatched field is a malformed event, not a zero: refuse the whole
+	// record rather than counting a run whose spend is unknown.
+	if (input === null || output === null || cacheRead === null || cacheWrite === null || recordedCost === null) {
+		return null;
+	}
+	return {
+		provider: text(event.provider),
+		model: text(event.model),
+		input,
+		output,
+		cacheRead,
+		cacheWrite,
+		recordedCost,
+		at: typeof event.at === "number" && Number.isFinite(event.at) ? event.at : null,
+		isAssistant: true,
+	};
+}
+
+export function createDelegationLedger(): DelegationLedger {
+	let retained: UsageRecord[] = [];
+	let total = 0;
+	let version = 0;
+
+	return {
+		note(event) {
+			if (!event || typeof event !== "object") return;
+			const record = toRecord(event as SubagentFinishedEvent);
+			if (!record) return;
+			total += 1;
+			version += 1;
+			retained.push(record);
+			// Keep the window at the cap without re-allocating the whole array per run
+			// until it is actually exceeded.
+			if (retained.length > MAX_DELEGATION_RECORDS) retained = retained.slice(-MAX_DELEGATION_RECORDS);
+		},
+		runs: () => total,
+		records: () => [...retained],
+		version: () => version,
+		reset() {
+			retained = [];
+			total = 0;
+			version = 0;
+		},
+	};
+}

package/extensions/bytefly/footer/price/config.ts

@@ -79,6 +79,18 @@ export const CURRENCY_DEFAULTS: Readonly<Record<CurrencyCode, Currency>> = {
 	USD: { code: "USD", decimals: 3 },
 };
 
+/**
+ * The day the built-in tables were last checked against the published page.
+ *
+ * `doctor` reports how old this is, so a tariff change is visible instead of
+ * silently wrong. What was checked on this date (UTC): DeepSeek's published USD figures
+ * (flash $0.3 in / $1.2 out per 1M, cache hit $0.006; v4-pro $1.32 / $3.96, cache
+ * hit $0.044), the off-peak rule (half the peak rate), and the peak windows (01:00
+ * - 04:00 and 06:00 - 10:00 UTC, Monday to Friday). The yuan table is the same
+ * page's CNY view. Re-check the page, then update this date.
+ */
+export const PRICE_VERIFIED_AT = "2026-10-18";
+
 /** Yuan, the currency `DEFAULT_RATES` is stated in. */
 export const DEFAULT_CURRENCY: Currency = CURRENCY_DEFAULTS.CNY;
 
@@ -86,9 +98,12 @@ export const DEFAULT_BYTEFLY_CONFIG: ByteflyConfig = {
 	currency: DEFAULT_CURRENCY,
 	rates: DEFAULT_RATES,
 	peak: DEFAULT_PEAK,
+	budget: 0,
 };
 
 const MAX_DECIMALS = 4;
+/** Upper bound for `budget`; large enough for any real session, small enough to clamp a typo. */
+const MAX_BUDGET = 10_000_000;
 const MAX_RATE = 1_000_000;
 const MAX_RATE_KEYS = 200;
 const MAX_WINDOWS = 16;
@@ -182,6 +197,7 @@ export function normalizeByteflyConfig(raw: Record<string, unknown> | undefined,
 		currency,
 		rates: ratesValue(raw.rates, rateBase),
 		peak: peakValue(raw.peak, base.peak),
+		budget: clampNumber(raw.budget, base.budget, 0, MAX_BUDGET),
 	};
 }
 

package/extensions/bytefly/footer/price/types.ts

@@ -56,4 +56,9 @@ export interface ByteflyConfig {
 	/** Rates keyed by `provider/model`, matched through wildcards. */
 	rates: Readonly<Record<string, ModelRates>>;
 	peak: PeakSchedule;
+	/**
+	 * Session spend that triggers one warning, in `currency`; `0` turns the
+	 * guardrail off. It warns, it does not stop anything.
+	 */
+	budget: number;
 }

package/extensions/bytefly/footer/register.ts

@@ -11,16 +11,36 @@
 
 import { homedir } from "node:os";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { createSnapshotReader } from "./collect/snapshot.ts";
+import { SUBAGENT_FINISHED_CHANNEL } from "../../../lib/events.ts";
+import { budgetBody, budgetNotice, budgetState } from "./budget.ts";
+import { createSnapshotReader, type SnapshotReader } from "./collect/snapshot.ts";
+import { createDelegationLedger } from "./delegation.ts";
 import { loadByteflyConfig } from "./price/config.ts";
 import { createFooter } from "./render/footer.ts";
 
+/** Host seams, injected by the composition root and by tests. */
+export interface FooterDeps {
+	/** Raise one OS notification through bytefly's notify capability. */
+	notify?: (body: string) => void;
+}
+
 /** Register the footer install/restore lifecycle. */
-export function registerFooter(pi: ExtensionAPI): void {
+export function registerFooter(pi: ExtensionAPI, deps: FooterDeps = {}): void {
+	// One ledger per load: it is this session's child-run accounting, priced by
+	// whichever reader is installed (a config change installs a new one).
+	const delegation = createDelegationLedger();
+	pi.events.on(SUBAGENT_FINISHED_CHANNEL, (event) => delegation.note(event));
+
+	/** The installed reader and the budget it was priced with, while a footer is up. */
+	let budget: { limit: number; read: SnapshotReader } | undefined;
+	/** One warning per session: the notice stays in scrollback, and a re-install must not repeat it. */
+	let warned = false;
+
 	const install = (ctx: ExtensionContext): void => {
 		if (ctx.mode !== "tui") return;
 		const config = loadByteflyConfig(ctx.cwd);
-		const read = createSnapshotReader(config);
+		const read = createSnapshotReader(config, delegation);
+		budget = { limit: config.budget, read };
 
 		ctx.ui.setFooter((tui, _theme, footerData) =>
 			createFooter(
@@ -33,9 +53,31 @@ export function registerFooter(pi: ExtensionAPI): void {
 		);
 	};
 
-	pi.on("session_start", (_event, ctx) => install(ctx));
+	pi.on("session_start", (_event, ctx) => {
+		// A new session in this process starts from zero: the ledger is not branch state,
+		// and a budget that was already reported is unreported again.
+		delegation.reset();
+		warned = false;
+		install(ctx);
+	});
 	pi.on("session_tree", (_event, ctx) => install(ctx));
+
+	// A turn's cost is final when the run settles, and that is when the user can act
+	// on it. Rendering never posts anything: the footer is derived state.
+	pi.on("agent_settled", (_event, ctx) => {
+		if (warned || !budget || budget.limit <= 0 || ctx.mode !== "tui") return;
+		const usage = budget.read.peek();
+		if (!usage) return;
+		const state = budgetState(budget.limit, usage.cost);
+		if (!state.exceeded) return;
+		warned = true;
+		const currency = loadByteflyConfig(ctx.cwd).currency;
+		pi.sendMessage(budgetNotice(state, currency));
+		deps.notify?.(budgetBody(state, currency));
+	});
+
 	pi.on("session_shutdown", (_event, ctx) => {
+		budget = undefined;
 		if (ctx.mode !== "tui") return;
 		ctx.ui.setFooter(undefined);
 	});

package/extensions/bytefly/footer/render/lines.ts

@@ -12,6 +12,7 @@ import {
 	cacheSegment,
 	contextSegment,
 	costSegment,
+	delegationSegment,
 	modelSegment,
 	modesSegment,
 	pwdSegment,
@@ -39,6 +40,7 @@ export function buildLines(snapshot: StatusSnapshot, theme: Theme, home: string
 		contextSegment(snapshot, theme),
 		windowSegment(snapshot, theme),
 		costSegment(snapshot, theme),
+		delegationSegment(snapshot, theme),
 		tokensSegment(snapshot, theme),
 		cacheSegment(snapshot, theme),
 		modesSegment(snapshot, theme),

package/extensions/bytefly/footer/render/segments.ts

@@ -182,6 +182,33 @@ export function costSegment(snapshot: StatusSnapshot, theme: Theme): Segment | n
 	};
 }
 
+/**
+ * Child-run spend, next to the session's own cost and never inside it: a
+ * subagent runs in its own process, so its tokens are not the session's. The
+ * roll-up covers the ledger's retained window (the last 500 runs).
+ */
+export function delegationSegment(snapshot: StatusSnapshot, theme: Theme): Segment | null {
+	const { runs, usage } = snapshot.delegation;
+	if (runs === 0) return null;
+	const icon = CONFIG.icons.delegation;
+	const cost = formatCost(usage.cost, snapshot.currency);
+	// Detailed first; the run count survives longer than the price, because "some
+	// delegation happened" is the part a narrow bar can still say.
+	const forms = [
+		`${paint(theme, "meta", `${icon} ${runs} · ${cost}`)}`,
+		`${paint(theme, "meta", `${icon} ${cost}`)}`,
+		paint(theme, "meta", `${icon} ${runs}`),
+		paint(theme, "meta", icon),
+	];
+	return {
+		id: "delegation",
+		weight: 4,
+		droppable: true,
+		separator: faint(theme, CONFIG.separators.item),
+		forms,
+	};
+}
+
 export function tokensSegment(snapshot: StatusSnapshot, theme: Theme): Segment | null {
 	const { input, output } = snapshot.usage;
 	if (input === 0 && output === 0) return null;

package/extensions/bytefly/footer/types.ts

@@ -70,6 +70,17 @@ export interface StatusSnapshot {
 	/** Latest cache hit rate as a percentage, or `null` when unknown. */
 	cacheHitRate: number | null;
 	providerCount: number;
+	/**
+	 * What this session's delegated child runs spent, priced like `usage` but kept
+	 * apart from it: the session total never includes child spend.
+	 */
+	delegation: DelegationTotals;
+}
+
+/** Child-run totals: how many runs finished, and what the retained window spent. */
+export interface DelegationTotals {
+	runs: number;
+	usage: UsageTotals;
 }
 
 /** One renderable piece of a line. */

package/extensions/bytefly/index.ts

@@ -59,7 +59,10 @@ export default function bytefly(pi: ExtensionAPI, deps: ByteflyDeps = {}): void
 	// the header reads it, so the marker and every re-install agree.
 	const updates = createUpdateState();
 	const header = registerHeader(pi, updates);
-	registerFooter(pi);
+	// Notify first, so the footer's budget guardrail can raise one OS notification
+	// through the same capability the triggers use instead of a second dispatch path.
+	const notifications = registerNotify(pi, deps.notify);
+	registerFooter(pi, { notify: notifications.notify });
 	registerUserMessage(pi);
 	// One store per load: the tool frame and the notice record Pi's output pad and
 	// the turn separator reads it, so bytefly's transcript blocks share one margin.
@@ -72,8 +75,8 @@ export default function bytefly(pi: ExtensionAPI, deps: ByteflyDeps = {}): void
 	registerTurnSeparator(pi, pad);
 	registerWorkingTimer(pi);
 	const doctor = registerDoctor(pi, deps.doctor);
-	registerPanel(pi, { doctor, discover: deps.extensions?.discover });
-	registerNotify(pi, deps.notify);
-	// Last, so a version that arrives after startup can re-install the header.
-	registerUpdate(pi, updates, { ...deps.update, onUpdate: () => header.refresh() });
+	// The returned handle is what `/bytefly update` re-runs, so the update surface is
+	// registered before the panel that offers the command.
+	const update = registerUpdate(pi, updates, { ...deps.update, onUpdate: () => header.refresh() });
+	registerPanel(pi, { doctor, update, discover: deps.extensions?.discover });
 }

package/extensions/bytefly/notify/config.ts

@@ -25,6 +25,7 @@ export const DEFAULT_NOTIFY_CONFIG: NotifyConfig = {
 	turnFinished: true,
 	needsInput: true,
 	jobFinished: true,
+	matchFound: true,
 	method: "auto",
 	title: "Pi",
 };
@@ -49,6 +50,7 @@ export function normalizeNotifyConfig(raw: Record<string, unknown> | undefined,
 		turnFinished: bool(raw.turnFinished, base.turnFinished),
 		needsInput: bool(raw.needsInput, base.needsInput),
 		jobFinished: bool(raw.jobFinished, base.jobFinished),
+		matchFound: bool(raw.matchFound, base.matchFound),
 		method: method(raw.method, base.method),
 		title: cleanString(raw.title, base.title).slice(0, MAX_TITLE_LENGTH),
 	};

package/extensions/bytefly/notify/format.ts

@@ -8,7 +8,7 @@
  */
 
 import { basename } from "node:path";
-import type { JobFinishedEvent } from "../../../lib/events.ts";
+import type { JobFinishedEvent, WatchMatchEvent } from "../../../lib/events.ts";
 import { sanitizeLine } from "../../../lib/format.ts";
 
 /** A short session label, so concurrent unattended runs can be told apart. */
@@ -37,3 +37,21 @@ export function formatJobBody(job: JobFinishedEvent): string {
 	const label = sanitizeLine(job.label);
 	return `Job ${job.id} ${verb}${code}${label ? ` · ${label}` : ""}`;
 }
+
+/** How much of a matched line an OS notification carries. */
+export const MAX_WATCH_LINE = 80;
+
+/**
+ * Body for a `watch` wake match: the newest line that matched, and how many did.
+ *
+ * The line is watched output rather than something this package wrote, so it is
+ * sanitized and clipped here — the one place a notification's text is shaped.
+ */
+export function formatWatchBody(event: WatchMatchEvent): string {
+	const count = Math.max(1, event.count);
+	const label = sanitizeLine(event.label);
+	const line = sanitizeLine(event.line).slice(0, MAX_WATCH_LINE).trimEnd();
+	const head = `${count} watched line${count === 1 ? "" : "s"} matched`;
+	const source = `${sanitizeLine(event.watcherId)}${label ? ` ${label}` : ""}`;
+	return line ? `${head} · ${source}: ${line}` : `${head} · ${source}`;
+}

package/extensions/bytefly/notify/register.ts

@@ -9,8 +9,9 @@
  *   asking for input. A prompt while idle is a command the user typed, so it
  *   does not fire;
  * - a finished background job, announced by the `job` extension on
- *   {@link JOB_FINISHED_CHANNEL}. The two extensions never import each other;
- *   the bus and its payload are the whole contract.
+ *   {@link JOB_FINISHED_CHANNEL}; and a `watch` wake match, announced by the
+ *   `watch` extension on {@link WATCH_MATCH_CHANNEL}. The three extensions never
+ *   import each other; the bus and its payload are the whole contract.
  *
  * The config is read at `session_start` and the bus subscription is a
  * long-lived resource, so it is created there too and released in an
@@ -18,10 +19,15 @@
  */
 
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { JOB_FINISHED_CHANNEL, type JobFinishedEvent } from "../../../lib/events.ts";
+import {
+	JOB_FINISHED_CHANNEL,
+	type JobFinishedEvent,
+	WATCH_MATCH_CHANNEL,
+	type WatchMatchEvent,
+} from "../../../lib/events.ts";
 import { DEFAULT_NOTIFY_CONFIG, loadNotifyConfig } from "./config.ts";
 import { defaultSeams, type NotifySeams, sendNotification } from "./dispatch.ts";
-import { formatInputBody, formatJobBody, formatTurnBody, sessionLabel } from "./format.ts";
+import { formatInputBody, formatJobBody, formatTurnBody, formatWatchBody, sessionLabel } from "./format.ts";
 import type { NotifyConfig } from "./types.ts";
 
 /** Host seams, injected by tests. */
@@ -37,12 +43,31 @@ function isJobFinished(value: unknown): value is JobFinishedEvent {
 	return typeof event.id === "string" && typeof event.label === "string" && typeof event.status === "string";
 }
 
-/** Register the three notification triggers. */
-export function registerNotify(pi: ExtensionAPI, deps: NotifyDeps = {}): void {
+/** Narrow an untrusted bus payload to a wake match. */
+function isWatchMatch(value: unknown): value is WatchMatchEvent {
+	if (!value || typeof value !== "object") return false;
+	const event = value as Partial<WatchMatchEvent>;
+	return (
+		typeof event.count === "number" &&
+		typeof event.watcherId === "string" &&
+		typeof event.label === "string" &&
+		typeof event.line === "string"
+	);
+}
+
+/** What the notify capability offers the rest of bytefly. */
+export interface NotifyHandle {
+	/** Raise one notification; inert while `notify.enabled` is off. */
+	notify(body: string): void;
+}
+
+/** Register the notification triggers. */
+export function registerNotify(pi: ExtensionAPI, deps: NotifyDeps = {}): NotifyHandle {
 	const seams = deps.seams ?? defaultSeams();
 	let config: NotifyConfig = DEFAULT_NOTIFY_CONFIG;
 	let busy = false;
-	let unsubscribe: (() => void) | undefined;
+	/** Bus subscriptions: one per emitting extension, all created at session start. */
+	const unsubscribes: Array<() => void> = [];
 
 	const fire = (body: string): void => {
 		sendNotification(config, config.title, body, seams);
@@ -59,11 +84,17 @@ export function registerNotify(pi: ExtensionAPI, deps: NotifyDeps = {}): void {
 	pi.on("session_start", (_event, ctx) => {
 		config = loadNotifyConfig(ctx.cwd);
 		busy = false;
-		unsubscribe?.();
-		unsubscribe = pi.events.on(JOB_FINISHED_CHANNEL, (data) => {
-			if (!config.jobFinished || !isJobFinished(data)) return;
-			fire(formatJobBody(data));
-		});
+		while (unsubscribes.length > 0) unsubscribes.pop()?.();
+		unsubscribes.push(
+			pi.events.on(JOB_FINISHED_CHANNEL, (data) => {
+				if (!config.jobFinished || !isJobFinished(data)) return;
+				fire(formatJobBody(data));
+			}),
+			pi.events.on(WATCH_MATCH_CHANNEL, (data) => {
+				if (!config.matchFound || !isWatchMatch(data)) return;
+				fire(formatWatchBody(data));
+			}),
+		);
 	});
 
 	pi.on("agent_settled", (event, ctx) => {
@@ -78,8 +109,15 @@ export function registerNotify(pi: ExtensionAPI, deps: NotifyDeps = {}): void {
 	});
 
 	pi.on("session_shutdown", () => {
-		unsubscribe?.();
-		unsubscribe = undefined;
+		while (unsubscribes.length > 0) unsubscribes.pop()?.();
 		busy = false;
 	});
+
+	return {
+		notify(body) {
+			// The master switch governs every path, including one another capability asks for.
+			if (!config.enabled) return;
+			fire(body);
+		},
+	};
 }

package/extensions/bytefly/notify/types.ts

@@ -21,6 +21,8 @@ export interface NotifyConfig {
 	needsInput: boolean;
 	/** Notify when a background `job` finishes. */
 	jobFinished: boolean;
+	/** Notify when a `watch` wake match fires while the agent is idle. */
+	matchFound: boolean;
 	/** Delivery method; `auto` chooses by terminal and platform. */
 	method: NotifyMethod;
 	/** Notification title, e.g. `Pi`. */