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

package/README.md

@@ -51,7 +51,7 @@ Requires a working [Pi](https://pi.dev) installation.
 ```bash
 pi install npm:@gavin-hu/my-pi-agent                       # install from npm
 pi install git:github.com/gavin-hu/my-pi-agent             # install from git
-pi install git:github.com/gavin-hu/my-pi-agent@v0.13.0     # pin a release
+pi install git:github.com/gavin-hu/my-pi-agent@v0.13.1     # pin a release
 pi install ./ -l                                           # project-local (.pi/settings.json)
 pi -e .                                                    # try it for one run
 ```

package/README.zh-CN.md

@@ -47,7 +47,7 @@ Pi 提供一个精简而锐利的内核。这个包是在其之上的一层，
 ```bash
 pi install npm:@gavin-hu/my-pi-agent                       # 从 npm 安装
 pi install git:github.com/gavin-hu/my-pi-agent             # 从 git 安装
-pi install git:github.com/gavin-hu/my-pi-agent@v0.13.0     # 固定到某个版本
+pi install git:github.com/gavin-hu/my-pi-agent@v0.13.1     # 固定到某个版本
 pi install ./ -l                                           # 仅项目本地（.pi/settings.json）
 pi -e .                                                    # 试运行一次
 ```

package/extensions/bytefly/README.md

@@ -126,14 +126,26 @@ shows as `¥<0.01` rather than `¥0.00`.
 
 DeepSeek needs no config file at all: the bar prices it from the published yuan
 rates and peak tariff built into [`footer/price/config.ts`](./footer/price/config.ts).
-A `bytefly.json` can switch to the published dollar table, add models of your own,
-or replace a built-in entry:
+Those tables record the day they were last checked against the published tariff,
+and `doctor` reports how old that is, so a re-pricing shows up as a warning instead
+of a quietly wrong total. A `bytefly.json` can switch to the published dollar table,
+add models of your own, or replace a built-in entry:
 
 ```
 ~/repo/project                                                          ⎇ main
 ▰▰▰▰▰▰▱▱▱▱ 62%/200k · ¥2.50 · ↑42k ↓8.0k · R96k CH 87%             opus-4.5 · high
 ```
 
+**Session budget.** `price.budget` puts a threshold under that total, in the same
+currency: when the session's cost reaches it, one `bytefly · Session budget
+reached` notice names what was spent against the budget, and one OS notification
+follows when notify is enabled. It is an alert, not a limit — no turn is blocked or
+aborted — and it fires once per session, on the turn where the crossing becomes
+final (the run settling), because a warning per turn after that is noise. `0`, the
+default, turns it off. The check reads the total the footer already priced, and
+the footer exists only in `tui` sessions, so a print or JSON run has no budget
+alert; the footer's own numbers are visible in every interactive session.
+
 **User message.** Every user message opens with a two-row `You` nameplate —
 the label over a rule that spans the width — above the message:
 
@@ -585,11 +597,11 @@ installs or fetches a package.
   without leaving the session.
 
 **Settings.** The second section uses the same frame and the same `Tab` scope
-switch, with its own cursor. It lists fifteen preferences in six groups:
+switch, with its own cursor. It lists sixteen preferences in six groups:
 
 ```
 bytefly ──────────────────────────────────────────────────────────────
-  Extensions · Settings                           Global · 15 settings
+  Extensions · Settings                           Global · 16 settings
 
   Startup (1)
 ❯ ◻ Bytefly startup TUI                                            Off
@@ -604,9 +616,10 @@ bytefly ────────────────────────
   Diagnostics (2)
   ◼ Proactive health check                                          On
     Probe timeout                                                 2000
-  Pricing (2)
+  Pricing (3)
     Currency                                                    CNY (¥)
     Cost decimals                                                    2
+    Session budget                                                   0
   Transcript (2)
     Rail glyph                                                       ╎
     Output padding                                                   1
@@ -633,6 +646,7 @@ bytefly ────────────────────────
 | Diagnostics | Probe timeout | `doctor.timeoutMs` | Number, 100–30000 ms |
 | Pricing | Currency | `price.currency.code` | CNY, USD |
 | Pricing | Cost decimals | `price.currency.decimals` | 0, 1, 2, 3, 4 |
+| Pricing | Session budget | `price.budget` | Number, `0` = off |
 | Transcript | Rail glyph | `chrome.rail` | Text, exactly one column |
 | Transcript | Output padding | Pi `settings.json` | 0, 1 |
 | Terminal | Hardware cursor | Pi `settings.json` | Off, On |
@@ -657,7 +671,7 @@ with `true` or `false`.
 
 App rows are **Global only**: Pi's setters for them write the personal
 `settings.json`, and only resource paths have public project setters. Project
-scope therefore lists the twelve `bytefly.json` rows and a
+scope therefore lists the thirteen `bytefly.json` rows and a
 `App settings are Global only.` note rather than promising a write that cannot
 happen. A `bytefly.json` row writes one leaf in the selected scope (a depth-1
 key, or a nested one such as `price.currency.decimals`) through a per-key
@@ -667,7 +681,7 @@ malformed document is refused with a notice instead of overwritten.
 The non-`tui` form prints the headline, the groups, and `Label: Value` rows:
 
 ```
-bytefly: Settings · Global · 15 settings
+bytefly: Settings · Global · 16 settings
 
 Startup (1)
   Bytefly startup TUI: Off
@@ -691,6 +705,12 @@ means reduced capability — an optional package that is absent, a config file
 that fails to parse, a login that has not happened. Doctor never changes
 anything and never installs anything.
 
+It also reports what has **aged**: the built-in DeepSeek rate tables carry the day
+they were last checked against the published tariff (`PRICE_VERIFIED_AT` in
+`footer/price/config.ts`), and the report says how old that is — `ok` inside the
+90-day window, `degraded` beyond it with the source URL to re-check. A tariff change
+therefore becomes a visible warning instead of a quietly wrong cost total.
+
 `web-access` publishes what it resolved at `session_start`, so the report names
 the search provider and why it won (an explicit choice, the `auto` rule, or the
 keyless default), and — when the provider takes a key and no literal `apiKey` is

package/extensions/bytefly/doctor/runtime.ts

@@ -10,6 +10,7 @@
 
 import { CONFIG_DIR_NAME, getAgentDir, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import type { WebSearchProviderEvent } from "../../../lib/events.ts";
+import { PRICE_VERIFIED_AT } from "../footer/price/config.ts";
 import { readJsonResult } from "../../../lib/config.ts";
 import { isExtensionEnabled } from "../../../lib/env.ts";
 import {
@@ -96,6 +97,7 @@ export function createDoctorRuntime(
 		searchProvider: () => searchProvider,
 		reach: probeReach,
 		refresh,
+		priceVerifiedAt: () => PRICE_VERIFIED_AT,
 		...deps.seams,
 	});
 

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

@@ -17,7 +17,7 @@ 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";
 
 /**
@@ -28,7 +28,20 @@ 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, delegation: DelegationLedger) {
+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();
@@ -36,7 +49,9 @@ export function createSnapshotReader(config: ByteflyConfig, delegation: Delegati
 	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 ?? ""}:${delegation.version()}`;
@@ -56,6 +71,7 @@ export function createSnapshotReader(config: ByteflyConfig, delegation: Delegati
 				percent: usageInfo?.percent ?? null,
 			};
 			key = nextKey;
+			last = usage;
 		}
 
 		const model = current
@@ -76,5 +92,7 @@ export function createSnapshotReader(config: ByteflyConfig, delegation: Delegati
 			providerCount: footerData.getAvailableProviderCount(),
 			delegation: delegationTotals,
 		};
-	};
+	}) as SnapshotReader;
+	reader.peek = () => last;
+	return reader;
 }

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

@@ -12,22 +12,35 @@
 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 { 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, delegation);
+		budget = { limit: config.budget, read };
 
 		ctx.ui.setFooter((tui, _theme, footerData) =>
 			createFooter(
@@ -41,12 +54,30 @@ export function registerFooter(pi: ExtensionAPI): void {
 	};
 
 	pi.on("session_start", (_event, ctx) => {
-		// A new session in this process starts from zero: the ledger is not branch state.
+		// 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/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,7 +75,6 @@ export default function bytefly(pi: ExtensionAPI, deps: ByteflyDeps = {}): void
 	registerTurnSeparator(pi, pad);
 	registerWorkingTimer(pi);
 	const doctor = registerDoctor(pi, deps.doctor);
-	registerNotify(pi, deps.notify);
 	// 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() });

package/extensions/bytefly/notify/register.ts

@@ -55,8 +55,14 @@ function isWatchMatch(value: unknown): value is WatchMatchEvent {
 	);
 }
 
+/** 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 = {}): void {
+export function registerNotify(pi: ExtensionAPI, deps: NotifyDeps = {}): NotifyHandle {
 	const seams = deps.seams ?? defaultSeams();
 	let config: NotifyConfig = DEFAULT_NOTIFY_CONFIG;
 	let busy = false;
@@ -106,4 +112,12 @@ export function registerNotify(pi: ExtensionAPI, deps: NotifyDeps = {}): void {
 		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/panel/settings.ts

@@ -173,6 +173,24 @@ function integerRule(min: number, max: number): TextRule {
 	};
 }
 
+/**
+ * A text rule for a money amount inside an inclusive range: a whole number or a
+ * decimal with up to four places, matching the loader's clamp for `price.budget`.
+ * `0` is a legitimate value (the guardrail is off), so it is not rejected.
+ */
+function amountRule(min: number, max: number): TextRule {
+	return {
+		maxLength: 16,
+		validate(raw) {
+			const text = raw.trim();
+			if (!/^\d+(?:\.\d{1,4})?$/.test(text)) return `Use an amount like 5 or 2.50, ${min} to ${max}.`;
+			const value = Number(text);
+			if (!Number.isFinite(value) || 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,
@@ -339,6 +357,19 @@ export const SETTING_ROWS: readonly SettingDescriptor[] = [
 		options: DECIMALS_OPTIONS,
 		config: { section: "price", path: ["currency", "decimals"] },
 	},
+	{
+		id: "price.budget",
+		group: "pricing",
+		label: "Session budget",
+		description: "Warn once when the session's cost reaches this amount; 0 is off. It never stops a turn.",
+		source: "bytefly",
+		kind: "text",
+		fallback: "0",
+		json: "number",
+		options: [],
+		text: amountRule(0, 10_000_000),
+		config: { section: "price", path: ["budget"] },
+	},
 	{
 		id: "chrome.rail",
 		group: "transcript",

package/extensions/job/format.ts

@@ -13,8 +13,8 @@
  */
 
 import type { Theme } from "@earendil-works/pi-coding-agent";
-import { truncateToWidth } from "@earendil-works/pi-tui";
 import { formatDuration } from "../../lib/format.ts";
+import { clip, LABEL_WIDTH, labelLine } from "../../lib/tui/columns.ts";
 import { GLYPHS, SEPARATORS } from "../../lib/tui/glyphs.ts";
 import { paint, type TuiRole } from "../../lib/tui/tokens.ts";
 import type { JobRecord, JobStatus } from "./types.ts";
@@ -22,9 +22,6 @@ import type { JobRecord, JobStatus } from "./types.ts";
 /** Longest sanitized log line kept for display; longer lines are clipped. */
 const MAX_LOG_LINE = 200;
 
-/** Longest label shown in the transcript or `/jobs` screen. */
-const MAX_DISPLAY_LABEL = 48;
-
 /** ESC-introduced sequences: OSC, CSI, and single-character escapes. */
 const OSC = /\u001b\][^\u0007\u001b]*(?:\u0007|\u001b\\)/g;
 const CSI = /\u001b\[[0-?]*[ -/]*[@-~]/g;
@@ -111,7 +108,7 @@ function statusWord(job: JobRecord): string {
 
 /** A label clipped to one safe display line. */
 export function clipLabel(text: string): string {
-	return truncateToWidth(sanitizeLogLine(text), MAX_DISPLAY_LABEL, "…");
+	return labelLine(text, sanitizeLogLine);
 }
 
 /** A job's label (falling back to its command) clipped to one safe display line. */
@@ -180,7 +177,7 @@ export function formatCallText(action: string, args: Record<string, unknown>, ar
 		case "start": {
 			const command = typeof args.command === "string" ? sanitizeLogLine(args.command.trim()) : "";
 			if (!command) return argsComplete ? "start" : "start …";
-			const preview = truncateToWidth(command, MAX_DISPLAY_LABEL, "…");
+			const preview = clip(command, LABEL_WIDTH);
 			return `start → ${preview}`;
 		}
 		case "kill":
@@ -188,7 +185,7 @@ export function formatCallText(action: string, args: Record<string, unknown>, ar
 		case "send": {
 			if (!target) return "send";
 			const input = typeof args.input === "string" ? sanitizeLogLine(args.input) : "";
-			const preview = input ? truncateToWidth(input, MAX_DISPLAY_LABEL, "…") : "";
+			const preview = input ? clip(input, LABEL_WIDTH) : "";
 			const parts = [preview, args.eof === true ? "EOF" : ""].filter(Boolean).join(" + ");
 			return parts ? `send ${target} → ${parts}` : `send ${target}`;
 		}

package/extensions/todo/nudge.ts

@@ -86,7 +86,11 @@ export function shouldNudge({ mutations, writes, touched, nudged, todos }: Nudge
 	return todos.length === 0 && !touched && writes > 0 && mutations >= EMPTY_LIST_MUTATIONS;
 }
 
-/** Marker on the injected reminder, so it is recognizable and filterable. */
+/**
+ * Marker on the injected reminder, so it is recognizable and filterable.
+ *
+ * allow:todo the marker is text the model reads, not a to-do for a human.
+ */
 export const TODO_NUDGE_MARKER = "[TODO SYNC]";
 
 /**

package/extensions/watch/README.md

@@ -33,8 +33,9 @@ How the `watch` call and its result look in the transcript — the call line as
   match is announced on `my-pi-agent/watch-match`, which bytefly's
   [notify](../bytefly/README.md#notifications) capability turns into a desktop
   notification when `notify.enabled` and `notify.matchFound` are on.
-- Watchers are session-only: `shutdown` flushes a partial line, kills every
-  command's process tree, and clears the chips.
+- Watchers are session-only: `shutdown` flushes a partial line, sends SIGTERM to
+  every command's process tree (escalating to SIGKILL after a short grace), and
+  clears the chips.
 
 ## Tool
 
@@ -42,7 +43,7 @@ How the `watch` call and its result look in the transcript — the call line as
 |---|---|
 | `name` | `watch` |
 | `action` | `add` \| `list` \| `status` \| `matches` \| `logs` \| `stop` \| `clear` |
-| `path` | File to tail (`add`); exactly one of `path`/`command`. |
+| `path` | Regular file to tail (`add`); exactly one of `path`/`command`. |
 | `command` | Shell command whose output to tail (`add`). |
 | `cwd` | Working directory for a command source; defaults to the effective cwd. |
 | `pattern` | Regular expression a line must match (`add`, required). |
@@ -131,7 +132,7 @@ value is clamped; a missing or malformed document is ignored.
 
 | Key | Default | Meaning |
 |---|---|---|
-| `enabled` | `true` | Track watchers at all. |
+| `enabled` | `true` | Allow `add`; `false` refuses to start a watcher. |
 | `showStatus` | `true` | Show the two status chips. |
 | `wakeOnMatch` | `false` | Default for a new watcher's `wake`; a per-watcher `wake` overrides it. |
 | `maxWatchers` | `20` | Live watchers before `add` is refused. |
@@ -160,6 +161,8 @@ other.
 
 - A file watcher polls, so a new line can take up to `pollMs` to surface; it does
   not use `fs.watch`.
+- `add` requires a path that exists and is a regular file; a directory, FIFO, or
+  a file created after the call is refused.
 - A watcher holds live state in memory and is stopped on shutdown; a detached or
   resumed session starts with no watchers.
 - `matches` and `logs` keep bounded histories (`maxMatches`/`maxLogLines`), so
@@ -200,7 +203,10 @@ UTF-8 sequence split across a read boundary is never mangled. State is
 session-only by design: a watcher is a live process or file position, not
 transcript state, so it cannot be faithfully rebuilt from a `/tree` fork. Match
 delivery mirrors `job` — reported at the next turn, with `wake` triggering one
-turn — so a match is never dropped when the wake window is busy.
+turn — so a match is never dropped when the wake window is busy. Stopping a
+command sends SIGTERM to its process group and escalates to SIGKILL after a 2 s
+grace; shutdown waits the same grace, so a command that ignores SIGTERM cannot
+outlive the session.
 
 ## Files
 

package/extensions/watch/commands.ts

@@ -14,7 +14,7 @@ import type { WatchRuntime } from "./runtime.ts";
 import { WatchListComponent } from "./tui.ts";
 
 /** How often the open screen re-reads live state. */
-const POLL_MS = 500;
+const REFRESH_MS = 500;
 
 const SUBCOMMANDS = [
 	{ value: "list", label: "list" },
@@ -125,12 +125,13 @@ export function registerCommands(pi: ExtensionAPI, runtime: WatchRuntime): void
 							() => tui.terminal?.rows,
 						);
 
+						// The runtime's own clock owns file polling; this only refreshes
+						// what the screen shows, so opening it cannot change the poll cadence.
 						timer = setInterval(() => {
-							runtime.tick();
 							const open = component.currentLineId();
 							if (open) component.refreshLines(open);
 							tui.requestRender();
-						}, POLL_MS);
+						}, REFRESH_MS);
 						timer.unref?.();
 
 						return component;

package/extensions/watch/config.ts

@@ -9,7 +9,7 @@
 import { clampInteger, loadConfigSection } from "../../lib/config.ts";
 
 export interface WatchConfig {
-	/** Track watchers at all. Default: true. */
+	/** Allow starting watchers; false refuses `add`. Default: true. */
 	enabled: boolean;
 	/** Show the status chips while watchers run or a match is unreported. */
 	showStatus: boolean;

package/extensions/watch/format.ts

@@ -10,15 +10,12 @@
  */
 
 import type { Theme } from "@earendil-works/pi-coding-agent";
-import { truncateToWidth } from "@earendil-works/pi-tui";
 import { sanitizeLine } from "../../lib/format.ts";
+import { clip, labelLine } from "../../lib/tui/columns.ts";
 import { GLYPHS, SEPARATORS } from "../../lib/tui/glyphs.ts";
 import { paint, type TuiRole } from "../../lib/tui/tokens.ts";
 import type { PendingMatch, WatchRecord, WatchStatus } from "./types.ts";
 
-/** Longest label shown in the transcript or `/watch` screen. */
-const MAX_DISPLAY_LABEL = 48;
-
 /** Longest sanitized watched line kept for display; longer lines are clipped. */
 const MAX_WATCH_LINE = 200;
 
@@ -50,7 +47,7 @@ export function compileRegex(pattern: string, caseSensitive: boolean): RegExp {
 
 /** A label clipped to one safe display line. */
 export function clipLabel(text: string): string {
-	return truncateToWidth(sanitizeWatchLine(text), MAX_DISPLAY_LABEL, "…");
+	return labelLine(text, sanitizeWatchLine);
 }
 
 /** What a watcher reads: a path or a command, clipped for display. */
@@ -177,9 +174,9 @@ export function formatCallText(action: string, args: Record<string, unknown>, ar
 			const command = typeof args.command === "string" ? args.command.trim() : "";
 			const source = path ? path : command ? `$ ${command}` : "";
 			if (!source) return argsComplete ? "add" : "add …";
-			const preview = truncateToWidth(sanitizeLine(source), MAX_DISPLAY_LABEL, "…");
+			const preview = labelLine(source);
 			const pattern = typeof args.pattern === "string" ? args.pattern.trim() : "";
-			return pattern ? `add ${preview} /${truncateToWidth(sanitizeLine(pattern), 24, "…")}/` : `add ${preview}`;
+			return pattern ? `add ${preview} /${clip(sanitizeLine(pattern), 24)}/` : `add ${preview}`;
 		}
 		case "status":
 		case "matches":

package/extensions/watch/runtime.ts

@@ -22,6 +22,8 @@ import type { PendingMatch, WatchMatch, WatchRecord, WatchSource } from "./types
 const MAX_CHUNK = 1024 * 1024;
 /** A line without a newline is flushed once it grows past this. */
 const MAX_LINE_BYTES = 1024 * 1024;
+/** Grace period before a stopped command is escalated to SIGKILL. */
+const KILL_GRACE_MS = 2000;
 
 /** Internal watcher state: the public record plus non-serializable fields. */
 interface Internal {
@@ -50,6 +52,7 @@ interface Internal {
 	rawLines: string[];
 	matches: WatchMatch[];
 	child?: SpawnedProcess;
+	killTimer?: ReturnType<typeof setTimeout>;
 	notified: boolean;
 	seq: number;
 }
@@ -95,6 +98,8 @@ export interface WatchRuntimeOptions {
 	config?: WatchConfig;
 	/** When false, never create a real interval; tests call `tick()` directly. */
 	autoClock?: boolean;
+	/** Grace before SIGTERM escalates to SIGKILL; default {@link KILL_GRACE_MS}. */
+	killGraceMs?: number;
 }
 
 export function createWatchRuntime(options: WatchRuntimeOptions = {}): WatchRuntime {
@@ -103,6 +108,7 @@ export function createWatchRuntime(options: WatchRuntimeOptions = {}): WatchRunt
 	const now = options.now ?? (() => Date.now());
 	const fixedConfig = options.config;
 	const autoClock = options.autoClock ?? true;
+	const killGraceMs = options.killGraceMs ?? KILL_GRACE_MS;
 
 	let config: WatchConfig = fixedConfig ?? DEFAULT_CONFIG;
 	const watches = new Map<string, Internal>();
@@ -243,15 +249,60 @@ export function createWatchRuntime(options: WatchRuntimeOptions = {}): WatchRunt
 		emit(w, rest, time);
 	};
 
-	const killChild = (w: Internal): void => {
+	const clearKillTimer = (w: Internal): void => {
+		if (w.killTimer) {
+			clearTimeout(w.killTimer);
+			w.killTimer = undefined;
+		}
+	};
+
+	const killChild = (w: Internal, signal: "SIGTERM" | "SIGKILL"): void => {
 		const pid = w.pid;
 		try {
-			if (pid !== undefined) killTree(pid, "SIGTERM");
-			else w.child?.kill("SIGTERM");
+			if (pid !== undefined) killTree(pid, signal, signal === "SIGKILL");
+			else w.child?.kill(signal);
 		} catch {
 			// Best-effort: the child may already be gone.
 		}
-		w.child = undefined;
+	};
+
+	/** SIGTERM a command, escalating to SIGKILL when it has not closed in time. */
+	const terminateChild = (w: Internal): void => {
+		clearKillTimer(w);
+		killChild(w, "SIGTERM");
+		if (w.pid === undefined && !w.child) return;
+		w.killTimer = setTimeout(() => {
+			w.killTimer = undefined;
+			if (w.child) killChild(w, "SIGKILL");
+		}, killGraceMs);
+		w.killTimer.unref?.();
+	};
+
+	/** Resolve when every command has closed, or after `ms`, whichever comes first. */
+	const waitForChildren = (watches: Internal[], ms: number): Promise<void> => {
+		const alive = watches.filter((w) => w.child !== undefined);
+		if (alive.length === 0) return Promise.resolve();
+		return new Promise((resolve) => {
+			let remaining = alive.length;
+			let timer: ReturnType<typeof setTimeout> | undefined;
+			const settle = (): void => {
+				if (--remaining > 0) return;
+				if (timer !== undefined) clearTimeout(timer);
+				resolve();
+			};
+			for (const w of alive) {
+				let done = false;
+				const once = (): void => {
+					if (done) return;
+					done = true;
+					settle();
+				};
+				w.child?.on("close", once);
+				w.child?.on("error", once);
+			}
+			timer = setTimeout(resolve, ms);
+			timer.unref?.();
+		});
 	};
 
 	const pollFile = (w: Internal, time: number): void => {
@@ -278,6 +329,9 @@ export function createWatchRuntime(options: WatchRuntimeOptions = {}): WatchRunt
 			const read = readSync(fd, buffer, 0, length, w.offset);
 			w.offset += read;
 			consume(w, buffer.subarray(0, read), time);
+		} catch {
+			// The path can vanish or change type between stat and read (rotation, a
+			// replacement); skip this tick and pick it up next time.
 		} finally {
 			if (fd !== undefined) {
 				try {
@@ -305,22 +359,24 @@ export function createWatchRuntime(options: WatchRuntimeOptions = {}): WatchRunt
 		child.stdout?.on("data", onData);
 		child.stderr?.on("data", onData);
 		child.on("close", (code, signal) => {
+			clearKillTimer(w);
+			w.child = undefined;
 			if (w.status !== "running") return;
 			flushPending(w, now());
 			w.status = "exited";
 			w.exitCode = code;
 			w.signal = signal;
 			w.endedAt = now();
-			w.child = undefined;
 			ui.paint();
 			if (runningCount() === 0) stopClock();
 		});
 		child.on("error", (error) => {
+			clearKillTimer(w);
+			w.child = undefined;
 			if (w.status !== "running") return;
 			w.status = "error";
 			w.error = error.message;
 			w.endedAt = now();
-			w.child = undefined;
 			ui.paint();
 			if (runningCount() === 0) stopClock();
 		});
@@ -337,6 +393,7 @@ export function createWatchRuntime(options: WatchRuntimeOptions = {}): WatchRunt
 	};
 
 	const add = (opts: AddWatchOptions, ctx: ExtensionContext): WatchRecord => {
+		if (!config.enabled) throw new Error("watch is disabled.");
 		if (watches.size >= config.maxWatchers) {
 			throw new Error(`at most ${config.maxWatchers} watchers; stop one first.`);
 		}
@@ -349,11 +406,13 @@ export function createWatchRuntime(options: WatchRuntimeOptions = {}): WatchRunt
 					cwd: opts.cwd ? (isAbsolute(opts.cwd) ? opts.cwd : resolve(base, opts.cwd)) : base,
 				};
 		if (source.kind === "file") {
+			let info: ReturnType<typeof statSync>;
 			try {
-				statSync(source.path ?? "");
+				info = statSync(source.path ?? "");
 			} catch {
 				throw new Error(`file not found: ${source.path}`);
 			}
+			if (!info.isFile()) throw new Error(`not a regular file: ${source.path}`);
 		}
 		const caseSensitive = opts.caseSensitive ?? false;
 		const regex = compileRegex(opts.pattern, caseSensitive);
@@ -423,7 +482,7 @@ export function createWatchRuntime(options: WatchRuntimeOptions = {}): WatchRunt
 		const w = watches.get(id);
 		if (!w || w.status !== "running") return false;
 		flushPending(w, now());
-		killChild(w);
+		terminateChild(w);
 		w.status = "stopped";
 		w.endedAt = now();
 		ui.paint();
@@ -473,7 +532,13 @@ export function createWatchRuntime(options: WatchRuntimeOptions = {}): WatchRunt
 	const load = (ctx: ExtensionContext): void => {
 		disposed = false;
 		stopClock();
-		for (const w of watches.values()) if (w.status === "running") killChild(w);
+		for (const w of watches.values()) {
+			if (w.status !== "running") continue;
+			w.status = "stopped";
+			clearKillTimer(w);
+			killChild(w, "SIGKILL");
+			w.child = undefined;
+		}
 		watches.clear();
 		counter = 0;
 		config = fixedConfig ?? loadConfig(ctx.cwd);
@@ -484,12 +549,18 @@ export function createWatchRuntime(options: WatchRuntimeOptions = {}): WatchRunt
 	const shutdown = async (): Promise<void> => {
 		disposed = true;
 		stopClock();
-		for (const w of watches.values()) {
-			if (w.status !== "running") continue;
+		const running = [...watches.values()].filter((w) => w.status === "running");
+		for (const w of running) {
 			flushPending(w, now());
-			killChild(w);
 			w.status = "stopped";
 			w.endedAt = now();
+			clearKillTimer(w);
+			killChild(w, "SIGTERM");
+		}
+		await waitForChildren(running, killGraceMs);
+		for (const w of running) {
+			clearKillTimer(w);
+			if (w.child) killChild(w, "SIGKILL");
 		}
 		watches.clear();
 		ui.detach();

package/extensions/worktree/README.md

@@ -122,9 +122,15 @@ exclude the name here to load alongside it. It is read when the extension
 loads, from the process working directory; reload after changing it. `/worktree`
 and `list_worktrees` list any overridden tool that is not re-rooted.
 
-Add the worktree directory to `.gitignore`:
+`.gitignore` must cover the managed directory, or worktrees show up as untracked
+files in the main checkout. `enter_worktree` offers once per session to append
+`.pi/worktrees/`, and skips the offer when `git check-ignore` already reports the
+directory as ignored, so a wider rule is enough and no literal line is needed:
 
 ```
+# either, when the rest of `.pi/` is disposable
+.pi/
+# or, when other `.pi/` state must stay tracked
 .pi/worktrees/
 ```
 

package/extensions/worktree/enter.ts

@@ -17,6 +17,7 @@ import {
 	currentBranch,
 	fetchPrRef,
 	hasCommits,
+	isIgnored,
 	lockWorktree,
 	mergeBase,
 	parsePrReference,
@@ -54,12 +55,19 @@ function generateName(): string {
 }
 
 /** Offer once per session to ignore the managed worktree directory. */
-async function maybeIgnoreWorktreeDir(ctx: ExtensionContext, root: string, config: WorktreeConfig): Promise<void> {
+async function maybeIgnoreWorktreeDir(
+	pi: ExtensionAPI,
+	ctx: ExtensionContext,
+	root: string,
+	config: WorktreeConfig,
+): Promise<void> {
 	if (isGitignoreOffered()) return;
 	if (!ctx.hasUI) return;
 	markGitignoreOffered();
 
 	const entry = `${config.dir.replace(/\/+$/, "")}/`;
+	if (await isIgnored(pi, root, entry)) return;
+
 	const gitignorePath = join(root, ".gitignore");
 	let content = "";
 	try {
@@ -67,7 +75,6 @@ async function maybeIgnoreWorktreeDir(ctx: ExtensionContext, root: string, confi
 	} catch {
 		return;
 	}
-	if (content.split(/\r?\n/).some((line) => line.trim() === entry || line.trim() === config.dir)) return;
 
 	const confirmed = await ctx.ui.confirm(
 		"Add the worktree directory to .gitignore?",
@@ -225,7 +232,7 @@ export async function enterWorktree(
 	let copiedIncludes: string[] = [];
 	if (!existed) {
 		copiedIncludes = await copyIncludes(pi, root, target, includePatterns(root, config.include), config.dir);
-		await maybeIgnoreWorktreeDir(ctx, root, config);
+		await maybeIgnoreWorktreeDir(pi, ctx, root, config);
 	}
 
 	const state: WorktreeState = {

package/extensions/worktree/exit.ts

@@ -7,12 +7,14 @@ import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-a
 import { loadConfig } from "./config.ts";
 import { WorktreeCancelledError } from "./errors.ts";
 import {
+	commitsAheadOf,
 	currentBranch,
 	defaultBranch,
 	deleteBranch,
 	inspectWork,
 	isBranchMerged,
 	lockWorktree,
+	refExists,
 	unlockWorktree,
 	worktreeRemove,
 } from "./git.ts";
@@ -32,17 +34,35 @@ export interface ExitOptions {
  * A failed lookup degrades to the facts already in hand: an exit that succeeded
  * must not fail because the default branch could not be read.
  */
-async function describeHandoff(pi: ExtensionAPI, state: WorktreeState, ahead: number): Promise<Handoff> {
-	if (!state.branch) return { branch: null, base: null, ahead, merged: false };
+async function describeHandoff(pi: ExtensionAPI, state: WorktreeState, recorded: number): Promise<Handoff> {
+	if (!state.branch) return { branch: null, base: null, ahead: recorded, merged: false };
 	try {
 		// `origin/HEAD` names the merge target when the repository has a remote; a
 		// local-only repository has none, and the main checkout's own branch is the
 		// branch a merge would actually land on.
 		const base = (await defaultBranch(pi, state.repoRoot)) ?? (await currentBranch(pi, state.repoRoot)) ?? null;
-		const merged = base ? await isBranchMerged(pi, state.repoRoot, state.branch, base) : false;
-		return { branch: state.branch, base, ahead, merged };
+		if (!base) return { branch: state.branch, base: null, ahead: recorded, merged: false };
+		// Count against the resolved base branch, not the commit recorded at entry:
+		// a worktree branch rebased onto a newer local branch would otherwise report
+		// every commit the base gained since, as its own.
+		// Every lookup runs in the main checkout: the handoff is read after the exit,
+		// when the worktree directory may already be gone, while the branch refs it
+		// describes outlive it.
+		const root = state.repoRoot;
+		const ref = (await refExists(pi, root, base))
+			? base
+			: (await refExists(pi, root, `origin/${base}`))
+				? `origin/${base}`
+				: null;
+		if (!ref) return { branch: state.branch, base: null, ahead: recorded, merged: false };
+		return {
+			branch: state.branch,
+			base,
+			ahead: await commitsAheadOf(pi, root, state.branch, ref),
+			merged: await isBranchMerged(pi, root, state.branch, ref),
+		};
 	} catch {
-		return { branch: state.branch, base: null, ahead, merged: false };
+		return { branch: state.branch, base: null, ahead: recorded, merged: false };
 	}
 }
 

package/extensions/worktree/git.ts

@@ -191,6 +191,25 @@ export async function worktreeExists(pi: ExtensionAPI, dir: string): Promise<boo
 }
 
 /** Whether a local branch exists. */
+/**
+ * Count of commits on `branch` that `base` does not contain.
+ *
+ * Takes the branch by name rather than reading `HEAD`, because a handoff is read
+ * after the worktree may already be gone while its branch refs outlive it.
+ */
+export async function commitsAheadOf(pi: ExtensionAPI, dir: string, branch: string, base: string): Promise<number> {
+	const result = await git(pi, ["rev-list", "--count", `${base}..${branch}`], dir);
+	if (result.code !== 0) return 0;
+	const count = Number.parseInt(result.stdout.trim(), 10);
+	return Number.isFinite(count) ? count : 0;
+}
+
+/** Whether `ref` resolves here: a branch, a remote-tracking ref, or a tag. */
+export async function refExists(pi: ExtensionAPI, dir: string, ref: string): Promise<boolean> {
+	const result = await git(pi, ["rev-parse", "--verify", "--quiet", ref], dir);
+	return result.code === 0 && result.stdout.trim() !== "";
+}
+
 export async function branchExists(pi: ExtensionAPI, repoRoot: string, branch: string): Promise<boolean> {
 	const result = await git(pi, ["show-ref", "--verify", "--quiet", `refs/heads/${branch}`], repoRoot);
 	return result.code === 0;
@@ -240,6 +259,15 @@ export async function deleteBranch(
 	return { ok: false, error: outcome.error || `Could not delete branch ${branch}` };
 }
 
+/**
+ * Whether git ignores `path` in `dir`. Asks git rather than matching ignore
+ * text, so a directory covered by a wider rule also counts as ignored.
+ */
+export async function isIgnored(pi: ExtensionAPI, dir: string, path: string): Promise<boolean> {
+	const result = await git(pi, ["check-ignore", "-q", "--", path], dir);
+	return result.code === 0;
+}
+
 /** Porcelain status lines for a working tree; empty when clean. */
 export async function statusEntries(pi: ExtensionAPI, dir: string): Promise<string[]> {
 	const result = await git(pi, ["status", "--porcelain"], dir);

package/extensions/worktree/index.ts

@@ -53,6 +53,7 @@ import {
 	noteUnverifiableCommand,
 	publishWorktree,
 	resetDiagnostics,
+	resetGitignoreOffer,
 	setActive,
 	setBaseCwd,
 	setInactiveOverrides,
@@ -91,6 +92,7 @@ export function registerWorktree(pi: ExtensionAPI, { entryPath, createBuiltin }:
 		setActive(null);
 		clearConfigCache();
 		resetDiagnostics();
+		resetGitignoreOffer();
 
 		// A child `pi` process (subagent) inherits an active worktree. Bind to
 		// it without creating, locking, or persisting anything; the parent owns

package/extensions/worktree/root-tools.ts

@@ -133,7 +133,7 @@ export function registerRootTools(pi: ExtensionAPI, host: RootToolHost, deps: Ro
 					signal,
 					onUpdate,
 					withCwd(ctx, root),
-				)) as AgentToolResult<any>;
+				)) as AgentToolResult<unknown>;
 			},
 		});
 	}

package/extensions/worktree/runtime.ts

@@ -70,6 +70,11 @@ export function markGitignoreOffered(): void {
 	gitignoreOffered = true;
 }
 
+/** Re-arm the offer for the next session; `session_start` owns the reset. */
+export function resetGitignoreOffer(): void {
+	gitignoreOffered = false;
+}
+
 /**
  * Count a bash command the guard let through without being able to verify it.
  * Session-scoped on purpose: it is the one gap a user cannot see in the

package/lib/README.md

@@ -4,8 +4,10 @@ Small modules imported by two or more extensions. Pi loads each extension with
 an **isolated module cache**, so these are *value-only* libraries: pure
 functions, constants, and classes. Never keep cross-extension state here — a
 module-level variable would have one copy per extension, not one shared copy.
-The single exception is the event-bus pattern in `rails.ts`, where the state
-lives in the caller's closure, not in this module.
+`test/structure.test.ts` fails a module-scope `let`, `var`, `Map`, `WeakMap`, or
+empty array, so this is a test and not a convention. The single exception is the
+event-bus pattern in `rails.ts`, where the state lives in the caller's closure,
+not in this module.
 
 This directory sits outside `extensions/` on purpose: nothing here is a
 loadable extension entrypoint, and every module is a contract shared *between*

package/lib/requirements.ts

@@ -111,6 +111,21 @@ export interface SafetyCheck {
 	hint: string;
 }
 
+/**
+ * A fact that ages: something checked by hand on a date, which is still worth
+ * trusting only for a while. The date arrives through a seam because `lib/` cannot
+ * import the extension that owns the record.
+ */
+export interface AgeCheck {
+	kind: "age";
+	/** What was verified, phrased for the report, e.g. `the built-in rate tables`. */
+	what: string;
+	/** Days after which the record counts as stale. */
+	maxAgeDays: number;
+	enables: string;
+	hint: string;
+}
+
 export type RequirementCheck =
 	| BinaryCheck
 	| ModuleCheck
@@ -118,7 +133,8 @@ export type RequirementCheck =
 	| InvocationCheck
 	| NotifyCheck
 	| ProviderCheck
-	| SafetyCheck;
+	| SafetyCheck
+	| AgeCheck;
 
 /** What an extension needs, split by how badly it needs it. */
 export interface ExtensionRequirements {
@@ -274,6 +290,13 @@ export const REQUIREMENTS: Readonly<Record<string, ExtensionRequirements>> = {
 	bytefly: {
 		configFiles: [SHARED_CONFIG_FILE],
 		optional: [
+			{
+				kind: "age",
+				what: "the built-in DeepSeek rate tables",
+				maxAgeDays: 90,
+				enables: "the footer's cost total tracks the published tariff",
+				hint: "re-check https://api-docs.deepseek.com/quick_start/pricing against `footer/price/config.ts`, then update `PRICE_VERIFIED_AT`.",
+			},
 			{
 				kind: "notify",
 				enables: "the configured notification delivery",
@@ -328,6 +351,10 @@ export interface ProbeSeams {
 	reach?: (url: string) => Promise<{ ok: boolean; error?: string }>;
 	/** True when the caller asked for an explicit refresh, which is when a probe may touch the network. */
 	refresh?: boolean;
+	/** The day a hand-checked record was verified, as `YYYY-MM-DD`, when the extension records one. */
+	priceVerifiedAt?: () => string | undefined;
+	/** The clock the age check reads; defaults to the process clock. */
+	now?: () => number;
 }
 
 /**
@@ -494,6 +521,56 @@ function safetyFindings(
 	return [{ extension, check: label, severity: "ok", detail: check.enables }];
 }
 
+/**
+ * Whole days between an ISO `YYYY-MM-DD` date and `now`, or undefined for a date
+ * that does not parse or does not exist on the calendar.
+ *
+ * A date up to a day in the future reads as zero days old: a record made in a
+ * timezone ahead of UTC is not a typo, and reporting it as missing would hide a
+ * fresh record. Anything further ahead is a typo, so it is not a date.
+ */
+export function ageInDays(date: string, now: number): number | undefined {
+	if (!/^\d{4}-\d{2}-\d{2}$/.test(date)) return undefined;
+	const stamp = Date.parse(`${date}T00:00:00Z`);
+	if (!Number.isFinite(stamp)) return undefined;
+	// `Date.parse` accepts 2026-02-31 by rolling it into March; reject the roll.
+	if (new Date(stamp).toISOString().slice(0, 10) !== date) return undefined;
+	const days = Math.floor((now - stamp) / 86_400_000);
+	if (days >= 0) return days;
+	// One day of skew is a timezone, not a mistake.
+	return days >= -1 ? 0 : undefined;
+}
+
+/** The findings for a fact that ages. */
+function ageFindings(extension: string, check: AgeCheck, failSeverity: FindingSeverity, seams: ProbeSeams): Finding[] {
+	const label = check.what;
+	const date = seams.priceVerifiedAt?.();
+	const age = date === undefined ? undefined : ageInDays(date, (seams.now ?? Date.now)());
+	if (date === undefined || age === undefined) {
+		return [
+			{
+				extension,
+				check: label,
+				severity: "info",
+				detail: `no verification date is recorded for ${label}`,
+			},
+		];
+	}
+	const days = `${age} day${age === 1 ? "" : "s"} ago`;
+	if (age <= check.maxAgeDays) {
+		return [{ extension, check: label, severity: "ok", detail: `${label} last checked ${days}` }];
+	}
+	return [
+		{
+			extension,
+			check: label,
+			severity: failSeverity,
+			detail: `${label} were last checked ${days}, beyond the ${check.maxAgeDays}-day window — ${check.enables}`,
+			hint: check.hint,
+		},
+	];
+}
+
 /** Run one check. `failSeverity` comes from which list the check sits in. */
 async function runCheck(
 	extension: string,
@@ -611,6 +688,8 @@ async function runCheck(
 			return providerFindings(extension, check, failSeverity, seams);
 		case "safety":
 			return safetyFindings(extension, check, failSeverity, seams);
+		case "age":
+			return ageFindings(extension, check, failSeverity, seams);
 	}
 }
 

package/lib/tui/columns.ts

@@ -10,6 +10,10 @@
  */
 
 import { sliceByColumn, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import { sanitizeLine } from "../format.ts";
+
+/** The columns a label gets before it stops reading as a label. */
+export const LABEL_WIDTH = 48;
 
 /** A usable origin: terminal arithmetic starts from one column, never zero. */
 function columns(width: number): number {
@@ -45,6 +49,19 @@ export function clipMiddle(text: string, width: number, ellipsis = "…"): strin
 	return clip(`${head}${ellipsis}${tail}`, w, ellipsis);
 }
 
+/**
+ * A single-line label clipped to {@link LABEL_WIDTH}.
+ *
+ * The sanitizer runs first, then the clip: cutting the raw text first would put
+ * a cut inside an escape sequence a sanitizer can no longer recognize, and a
+ * newline would be left to break the row in two. The default is
+ * {@link sanitizeLine}; an extension with its own log- or file-authored text
+ * passes that sanitizer instead.
+ */
+export function labelLine(text: string, sanitize: (text: string) => string = sanitizeLine): string {
+	return clip(sanitize(text), LABEL_WIDTH);
+}
+
 /** Pad `text` on the right to exactly `width` columns. Never truncates. */
 export function padTo(text: string, width: number): string {
 	const missing = columns(width) - visibleWidth(text);

package/lib/tui/tool.ts

@@ -136,7 +136,8 @@ export function moreHint(theme: Theme, hidden: number, noun = "lines"): string {
 
 /** The render context fields the elapsed timer needs. */
 export interface ToolRenderClock {
-	state: any;
+	/** Pi's per-call render state, opaque here: this module only ever casts it. */
+	state: unknown;
 	invalidate(): void;
 }
 
@@ -191,7 +192,10 @@ export function elapsedSuffix(theme: Theme, durationMs: number | undefined, minM
  * (the renderer's `isPartial` branch draws its own running line) and the host
  * replaces it with the final result.
  */
-export function startToolProgress(onUpdate: ((partial: any) => void) | undefined): void {
+export function startToolProgress(
+	// allow:any Pi's partial-result type is generic over each tool's details, so a shared helper cannot name it.
+	onUpdate: ((partial: any) => void) | undefined,
+): void {
 	onUpdate?.({ content: [], details: undefined });
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gavin-hu/my-pi-agent",
-  "version": "0.13.0",
+  "version": "0.13.1",
   "description": "Personal Pi customizations, packaged as a Pi package: worktree isolation and rewind snapshots, question, todo, goal, plan, subagent, job, watch, web-access, file-browse, file-open, document, memory, wechat, and bytefly.",
   "keywords": [
     "pi-package",