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

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/register.ts

@@ -11,16 +11,23 @@
 
 import { homedir } from "node:os";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { SUBAGENT_FINISHED_CHANNEL } from "../../../lib/events.ts";
 import { createSnapshotReader } from "./collect/snapshot.ts";
+import { createDelegationLedger } from "./delegation.ts";
 import { loadByteflyConfig } from "./price/config.ts";
 import { createFooter } from "./render/footer.ts";
 
 /** Register the footer install/restore lifecycle. */
 export function registerFooter(pi: ExtensionAPI): 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));
+
 	const install = (ctx: ExtensionContext): void => {
 		if (ctx.mode !== "tui") return;
 		const config = loadByteflyConfig(ctx.cwd);
-		const read = createSnapshotReader(config);
+		const read = createSnapshotReader(config, delegation);
 
 		ctx.ui.setFooter((tui, _theme, footerData) =>
 			createFooter(
@@ -33,7 +40,11 @@ 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.
+		delegation.reset();
+		install(ctx);
+	});
 	pi.on("session_tree", (_event, ctx) => install(ctx));
 	pi.on("session_shutdown", (_event, ctx) => {
 		if (ctx.mode !== "tui") return;

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

@@ -72,8 +72,9 @@ 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,25 @@ 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. */
+/** 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"
+	);
+}
+
+/** Register the notification triggers. */
 export function registerNotify(pi: ExtensionAPI, deps: NotifyDeps = {}): void {
 	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 +78,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 +103,7 @@ export function registerNotify(pi: ExtensionAPI, deps: NotifyDeps = {}): void {
 	});
 
 	pi.on("session_shutdown", () => {
-		unsubscribe?.();
-		unsubscribe = undefined;
+		while (unsubscribes.length > 0) unsubscribes.pop()?.();
 		busy = false;
 	});
 }

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`. */

package/extensions/bytefly/panel/commands.ts

@@ -1,23 +1,28 @@
 /**
- * The `/bytefly` surface: one command, `/bytefly [doctor] [settings] [extension] [refresh]`.
+ * The `/bytefly` surface: one command, `/bytefly [doctor] [settings] [update] [extension] [refresh]`.
  *
  * Without `doctor` it opens the extension screen: the dock in `tui`, the
  * grouped listing elsewhere. `settings` opens the Settings section, or prints
- * its grouped listing outside `tui` without resolving packages. With `doctor`
- * it produces the doctor report — the same text `run_doctor` returns — for the
- * whole set or one named extension; in `tui` the report is the dock screen.
- * Discovery, the doctor probe, and the dirty-to-reload confirm all live here.
- * The doctor runtime is injected by the composition root, so `run_doctor` and
- * the screen keep reading one cache.
+ * its grouped listing outside `tui` without resolving packages. `update`
+ * re-runs the published-version check and reports what it found, which is the
+ * one place a request is made on demand. With `doctor` it produces the doctor
+ * report — the same text `run_doctor` returns — for the whole set or one named
+ * extension; in `tui` the report is the dock screen. Discovery, the doctor
+ * probe, and the dirty-to-reload confirm all live here. The doctor runtime and
+ * the update handle are injected by the composition root, so `run_doctor` and
+ * the screen keep reading one cache, and the command paints the marker it finds.
  */
 
 import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import pkg from "../../../package.json";
 import { sanitizeLine } from "../../../lib/format.ts";
 import { withRailsSuppressed } from "../../../lib/rails.ts";
 import { REQUIREMENTS, type ExtensionReport } from "../../../lib/requirements.ts";
 import { formatExtension, formatReport, hasProblems } from "../doctor/format.ts";
 import type { DoctorRuntime } from "../doctor/runtime.ts";
+import { updateOutcomeText } from "../update/format.ts";
+import type { UpdateHandle } from "../update/register.ts";
 import { createSettingsStores, discoverExtensions, type DiscoveryDeps } from "../picker/discovery.ts";
 import { createExtensionsPickerRuntime, type ExtensionsPickerRuntime } from "../picker/runtime.ts";
 import type { Discovery } from "../picker/types.ts";
@@ -31,6 +36,8 @@ import type { PanelSection } from "./types.ts";
 export interface PanelCommandDeps {
 	/** The doctor runtime created by `registerDoctor`; shared with `run_doctor`. */
 	doctor: DoctorRuntime;
+	/** The update handle `registerUpdate` returns, for `/bytefly update`. */
+	update: UpdateHandle;
 	/** The picker's discovery seam. */
 	discover?: (deps: DiscoveryDeps) => Promise<Discovery>;
 	/** The Settings runtime seam. */
@@ -49,13 +56,14 @@ function selectableNames(discovery: Discovery): Set<string> {
 }
 
 /** The values a bare `/bytefly <tab>` offers, in screen order. */
-const FIRST_TOKENS = ["doctor", "settings", ...Object.keys(REQUIREMENTS), "refresh"] as const;
+const FIRST_TOKENS = ["doctor", "settings", "update", ...Object.keys(REQUIREMENTS), "refresh"] as const;
 
 /**
  * Argument completions. The host replaces the whole argument text with the
  * returned `value`, so a second token returns the full `doctor <name>` or
- * `<name> refresh` argument rather than just the word. `/bytefly settings` takes
- * no name, and `refresh` is never followed by another token.
+ * `<name> refresh` argument rather than just the word. `/bytefly settings` and
+ * `/bytefly update` take no name, and `refresh` is never followed by another
+ * token.
  */
 function completions(prefix: string): Array<{ value: string; label: string }> | null {
 	const [first = "", second, ...rest] = prefix.trimStart().split(/\s+/);
@@ -64,7 +72,7 @@ function completions(prefix: string): Array<{ value: string; label: string }> |
 		const options = FIRST_TOKENS.filter((option) => option.startsWith(first));
 		return options.length > 0 ? options.map((option) => ({ value: `${option} `, label: option })) : null;
 	}
-	if (first === "settings" || first === "refresh") return null;
+	if (first === "settings" || first === "refresh" || first === "update") return null;
 	const options = (first === "doctor" ? [...Object.keys(REQUIREMENTS), "refresh"] : ["refresh"]).filter((option) =>
 		option.startsWith(second),
 	);
@@ -72,7 +80,7 @@ function completions(prefix: string): Array<{ value: string; label: string }> |
 }
 
 /** Which bytefly surface the arguments select. */
-type PanelMode = "screen" | "doctor";
+type PanelMode = "screen" | "doctor" | "update";
 
 /** `/bytefly [doctor] [settings] [extension] [refresh]`, parsed. */
 interface PanelArgs {
@@ -85,12 +93,15 @@ interface PanelArgs {
 	refresh: boolean;
 }
 
-/** Parse `/bytefly [doctor] [settings] [extension] [refresh]`; extra tokens are ignored. */
+/** Parse `/bytefly [doctor] [settings] [update] [extension] [refresh]`; extra tokens are ignored. */
 function parseArgs(args: string): PanelArgs {
 	const parts = args.trim().split(/\s+/).filter(Boolean);
 	const refresh = parts.includes("refresh");
 	const rest = parts.filter((part) => part !== "refresh");
 	if (rest[0] === "doctor") return { mode: "doctor", section: "extensions", name: rest[1], refresh };
+	// `update` is already a refresh of the published version, so a stray `refresh`
+	// beside it is accepted and ignored rather than refused.
+	if (rest[0] === "update") return { mode: "update", section: "extensions", refresh };
 	if (rest[0] === "settings") return { mode: "screen", section: "settings", name: rest[1], refresh };
 	return { mode: "screen", section: "extensions", name: rest[0], refresh };
 }
@@ -146,6 +157,16 @@ export function registerPanel(pi: ExtensionAPI, deps: PanelCommandDeps): void {
 		};
 		const settingsNotice = (message: string): void => surfaceNotice(message, "warning");
 
+		// `/bytefly update` answers one question and resolves nothing: no package
+		// discovery, no doctor probe, no screen. It is the one path a version check
+		// takes on demand, so the request happens here and nowhere else.
+		if (mode === "update") {
+			const outcome = await deps.update.recheck();
+			const { text, severity } = updateOutcomeText(outcome, pkg.version);
+			ctx.ui.notify(text, severity);
+			return;
+		}
+
 		// Settings outside `tui` prints its grouped listing without resolving
 		// packages or probing the doctor.
 		if (section === "settings" && ctx.mode !== "tui") {

package/extensions/bytefly/panel/settings.ts

@@ -6,15 +6,16 @@
  * views, cycling, validation, and grouping — so the screen and the runtime share
  * one definition and the tests need no host.
  *
- * The catalogue is deliberately curated: one proven row family at a time. It
- * covers scalars (a boolean checkbox, an enum cycle, a short string with its own
- * rule), both scopes, both write paths, and — with `price.currency.decimals` —
- * one nested key. Arrays, nested tariffs, and credentials are still JSON edits.
+ * The catalogue covers every scalar preference: booleans, enums, short strings,
+ * and — with `doctor.timeoutMs` — a number. Each row states its own rule, so a
+ * value the screen accepts is a value the loader keeps. Arrays (`doctor.skip`),
+ * the `rates` table, and `price.peak` stay JSON edits: a list, a table, and a
+ * nested object are not one row.
  */
 
 import { configSection, configValueAt } from "../../../lib/config.ts";
 import { GLYPHS } from "../../../lib/tui/glyphs.ts";
-import { DEFAULT_CHROME_CONFIG, normalizeChromeConfig } from "../chrome.ts";
+import { DEFAULT_CHROME_CONFIG, isRailGlyph, normalizeChromeConfig } from "../chrome.ts";
 import { DEFAULT_CONFIG as DEFAULT_DOCTOR_CONFIG, normalizeConfig as normalizeDoctorConfig } from "../doctor/config.ts";
 import {
 	CURRENCY_DEFAULTS,
@@ -136,14 +137,6 @@ const ON_OFF: readonly SettingOption[] = [
 	{ value: "true", label: "On" },
 ];
 
-/** Rail glyphs offered in the curated picker; every one is one column. */
-const RAIL_OPTIONS: readonly SettingOption[] = [
-	{ value: GLYPHS.divider, label: GLYPHS.divider },
-	{ value: "│", label: "│" },
-	{ value: "┃", label: "┃" },
-	{ value: "▏", label: "▏" },
-];
-
 /** The notify section's delivery methods, labeled by the surface each reaches. */
 const METHOD_OPTIONS: readonly SettingOption[] = [
 	{ value: "auto", label: "Auto" },
@@ -160,6 +153,33 @@ const DECIMALS_OPTIONS: readonly SettingOption[] = [0, 1, 2, 3, 4].map((value) =
 	label: String(value),
 }));
 
+/**
+ * A text rule for a whole number inside an inclusive range.
+ *
+ * The bounds are the loader's own (`doctor.timeoutMs` is clamped to 100-30000),
+ * so an accepted value is never silently clamped on the next read. `maxLength`
+ * only stops a runaway buffer; `validate` is the rule.
+ */
+function integerRule(min: number, max: number): TextRule {
+	return {
+		maxLength: String(max).length + 2,
+		validate(raw) {
+			const text = raw.trim();
+			if (!/^\d+$/.test(text)) return `Use a whole number, ${min} to ${max}.`;
+			const value = Number(text);
+			if (value < min || value > max) return `Out of range: ${min} to ${max}.`;
+			return undefined;
+		},
+	};
+}
+
+/** The rail's rule: the loader drops anything that is not one column. */
+const RAIL_RULE: TextRule = {
+	maxLength: 4,
+	validate: (raw) =>
+		isRailGlyph(raw) ? undefined : "Use exactly one column: a single glyph, with no spaces or control characters.",
+};
+
 /** The v1 catalogue, in screen order. */
 export const SETTING_ROWS: readonly SettingDescriptor[] = [
 	{
@@ -185,6 +205,54 @@ export const SETTING_ROWS: readonly SettingDescriptor[] = [
 		options: ON_OFF,
 		config: { section: "notify", path: ["enabled"] },
 	},
+	{
+		id: "notify.turnFinished",
+		group: "notifications",
+		label: "Turn finished",
+		description: "Announce it when a full agent run settles.",
+		source: "bytefly",
+		kind: "boolean",
+		fallback: "true",
+		json: "boolean",
+		options: ON_OFF,
+		config: { section: "notify", path: ["turnFinished"] },
+	},
+	{
+		id: "notify.needsInput",
+		group: "notifications",
+		label: "Needs input",
+		description: "Announce it when the agent opens a prompt and waits for an answer.",
+		source: "bytefly",
+		kind: "boolean",
+		fallback: "true",
+		json: "boolean",
+		options: ON_OFF,
+		config: { section: "notify", path: ["needsInput"] },
+	},
+	{
+		id: "notify.jobFinished",
+		group: "notifications",
+		label: "Job finished",
+		description: "Announce it when a background job or watcher settles.",
+		source: "bytefly",
+		kind: "boolean",
+		fallback: "true",
+		json: "boolean",
+		options: ON_OFF,
+		config: { section: "notify", path: ["jobFinished"] },
+	},
+	{
+		id: "notify.matchFound",
+		group: "notifications",
+		label: "Watcher matched",
+		description: "Announce it when a `watch` whose `wake` is on matches while the agent is idle.",
+		source: "bytefly",
+		kind: "boolean",
+		fallback: "true",
+		json: "boolean",
+		options: ON_OFF,
+		config: { section: "notify", path: ["matchFound"] },
+	},
 	{
 		id: "notify.method",
 		group: "notifications",
@@ -223,6 +291,19 @@ export const SETTING_ROWS: readonly SettingDescriptor[] = [
 		options: ON_OFF,
 		config: { section: "doctor", path: ["proactive"] },
 	},
+	{
+		id: "doctor.timeoutMs",
+		group: "diagnostics",
+		label: "Probe timeout",
+		description: "How long one doctor probe may take, in milliseconds; 100 to 30000.",
+		source: "bytefly",
+		kind: "text",
+		fallback: String(DEFAULT_DOCTOR_CONFIG.timeoutMs),
+		json: "number",
+		options: [],
+		text: integerRule(100, 30_000),
+		config: { section: "doctor", path: ["timeoutMs"] },
+	},
 	{
 		id: "price.currency.code",
 		group: "pricing",
@@ -262,11 +343,12 @@ export const SETTING_ROWS: readonly SettingDescriptor[] = [
 		id: "chrome.rail",
 		group: "transcript",
 		label: "Rail glyph",
-		description: "The single-column glyph that leads a tool result or notice body.",
+		description: "The single-column glyph that leads a tool result or notice body, e.g. ╎ │ ┃ ▏.",
 		source: "bytefly",
-		kind: "enum",
+		kind: "text",
 		fallback: GLYPHS.divider,
-		options: RAIL_OPTIONS,
+		options: [],
+		text: RAIL_RULE,
 		config: { section: "chrome", path: ["rail"] },
 	},
 	{