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

package/extensions/rewind/restore.ts

@@ -1,24 +1,31 @@
 /**
  * Rewind: restore the working tree and index to a snapshot without moving HEAD.
  *
- * `read-tree --reset -u` brings tracked files back to the snapshot (restoring
- * modifications and deletions and removing paths the snapshot never had). Files
- * created after the snapshot and never tracked are then deleted explicitly,
- * because `read-tree` leaves untracked files alone. HEAD, branches, and reflogs
- * are untouched.
+ * The whole-tree restore runs `read-tree --reset -u` against the snapshot, which
+ * brings tracked files back (restoring modifications and deletions and removing
+ * paths the snapshot never had). Files created after the snapshot and never
+ * tracked are then deleted explicitly, because `read-tree` leaves untracked files
+ * alone. HEAD, branches, and reflogs are untouched.
+ *
+ * A **partial** restore takes the same shape over a subset: `read-tree` accepts no
+ * pathspec, so the selected paths are checked out of the snapshot instead, and
+ * only the selected additions are deleted. Everything else is left exactly as it
+ * is, and the same temporary index is used, so the real index stays untouched
+ * either way.
  */
 
 import { lstatSync, rmSync } from "node:fs";
 import { resolve, sep } from "node:path";
 import {
-	addedPaths,
 	busyGitState,
-	changedCount,
 	diffStat,
+	nameStatus,
 	readTreeReset,
+	restorePaths,
 	treeFromWorkingTree,
 	type RunGit,
 } from "./git.ts";
+import { summarize, type ChangedPath } from "./paths.ts";
 import type { Snapshot, RestoreSummary } from "./types.ts";
 
 export interface RestoreDeps {
@@ -32,6 +39,8 @@ export interface RestoreInput {
 	indexFile: string;
 	/** Snapshot to restore. */
 	target: Snapshot;
+	/** Restore only these paths; omitted means the whole tree. */
+	paths?: readonly string[];
 }
 
 export interface RestorePlan {
@@ -41,6 +50,8 @@ export interface RestorePlan {
 	changed: number;
 	/** Paths created since the snapshot that the restore removes. */
 	removed: number;
+	/** Every changed path, with how the restore treats it. */
+	paths: ChangedPath[];
 }
 
 export type PlanResult = { ok: true; plan: RestorePlan } | { ok: false; reason: string };
@@ -51,26 +62,32 @@ export async function planRestore(deps: RestoreDeps, input: RestoreInput): Promi
 	if (busy) {
 		return { ok: false, reason: `a git ${busy} is in progress; finish or abort it before restoring.` };
 	}
-	const { cur, added, changed } = await previewRestore(deps, input);
-	const diff = await diffStat(deps.runGit, input.root, input.target.commit, cur);
-	return { ok: true, plan: { diff, changed, removed: added.length } };
+	const cur = await stagedTree(deps, input);
+	const paths = await changedPaths(deps, input, cur);
+	const diff = await diffStat(deps.runGit, input.root, input.target.commit, cur, selectionOf(paths));
+	return { ok: true, plan: { diff, ...summarize(paths), paths } };
+}
+
+/** The selection narrowed to paths the plan actually found, or undefined for all. */
+function selectionOf(paths: readonly ChangedPath[]): string[] | undefined {
+	return paths.length > 0 ? paths.map((entry) => entry.path) : undefined;
 }
 
 /**
- * Stage the working tree into the temporary index and compare it against the
- * snapshot. `cur` is the staged commit, `added` the paths created since the
- * snapshot, and `changed` the tracked files modified or deleted.
+ * Stage the working tree into the temporary index, so previews compare
+ * tree-to-tree: untracked files captured in the snapshot are not mistaken for
+ * deletions against the real index.
  */
-async function previewRestore(
-	deps: RestoreDeps,
-	input: RestoreInput,
-): Promise<{ cur: string; added: string[]; changed: number }> {
-	// Compare tree-to-tree, so untracked files captured in the snapshot are not
-	// mistaken for deletions against the real index.
-	const cur = await treeFromWorkingTree(deps.runGit, input.root, input.indexFile, input.target.includeUntracked);
-	const added = await addedPaths(deps.runGit, input.root, input.target.commit, cur);
-	const changed = await changedCount(deps.runGit, input.root, input.target.commit, cur, "MD");
-	return { cur, added, changed };
+async function stagedTree(deps: RestoreDeps, input: RestoreInput): Promise<string> {
+	return treeFromWorkingTree(deps.runGit, input.root, input.indexFile, input.target.includeUntracked);
+}
+
+/** Every changed path, narrowed to the caller's selection when one is given. */
+async function changedPaths(deps: RestoreDeps, input: RestoreInput, cur: string): Promise<ChangedPath[]> {
+	const all = await nameStatus(deps.runGit, input.root, input.target.commit, cur);
+	if (!input.paths) return all;
+	const selected = new Set(input.paths);
+	return all.filter((entry) => selected.has(entry.path));
 }
 
 /** Delete a path under `root`, refusing to escape it or remove a directory. */
@@ -85,12 +102,36 @@ function deleteFile(root: string, relative: string): void {
 	}
 }
 
-/** Apply the restore. Recomputes the removal set immediately before mutating. */
+/**
+ * Apply the restore. Recomputes the changed set immediately before mutating, so a
+ * file edited while the confirmation was open is still handled correctly.
+ */
 export async function applyRestore(deps: RestoreDeps, input: RestoreInput): Promise<RestoreSummary> {
-	const { added, changed } = await previewRestore(deps, input);
+	const cur = await stagedTree(deps, input);
+	const paths = await changedPaths(deps, input, cur);
+	const { changed, removed } = summarize(paths);
+	const rewritten = paths.filter((entry) => entry.change !== "added").map((entry) => entry.path);
+	const created = paths.filter((entry) => entry.change === "added").map((entry) => entry.path);
+
+	if (input.paths) {
+		await restorePaths(deps.runGit, input.root, input.target.commit, input.indexFile, rewritten);
+	} else {
+		// The whole tree in one call: this also removes files the snapshot lacks,
+		// which a pathspec checkout of every changed path would not.
+		await readTreeReset(deps.runGit, input.root, input.target.commit, input.indexFile);
+	}
+	for (const path of created) deleteFile(input.root, path);
 
-	await readTreeReset(deps.runGit, input.root, input.target.commit, input.indexFile);
-	for (const path of added) deleteFile(input.root, path);
+	// A subset notice says "2 of 5 files", so it needs the whole diff's size; the
+	// all-path query is already in hand when nothing was narrowed.
+	const of = input.paths ? (await nameStatus(deps.runGit, input.root, input.target.commit, cur)).length : paths.length;
 
-	return { id: input.target.id, commit: input.target.commit, root: input.root, changed, removed: added.length };
+	return {
+		id: input.target.id,
+		commit: input.target.commit,
+		root: input.root,
+		changed,
+		removed,
+		...(input.paths ? { of } : {}),
+	};
 }

package/extensions/rewind/rewind.ts

@@ -9,7 +9,11 @@
  */
 
 import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { withRailsSuppressed } from "../../lib/rails.ts";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { formatChangeSummary, formatRestoreText, previewDiffText } from "./format.ts";
+import { PathPickerComponent } from "./path-picker.ts";
+import type { ChangedPath } from "./paths.ts";
 import type { RewindRuntime } from "./runtime.ts";
 import { rewindScopes, type RewindPoint, type RewindScope } from "./timeline.ts";
 
@@ -47,19 +51,67 @@ async function chooseScope(
 }
 
 /** Build the combined confirm body, including the diff preview when code moves. */
-function confirmBody(scope: RewindScope, changeSummary: string | undefined, diff: string | undefined): string {
+function confirmBody(
+	scope: RewindScope,
+	changeSummary: string | undefined,
+	diff: string | undefined,
+	subset?: { selected: number; total: number },
+): string {
 	const lines = [scopeDescription(scope)];
+	if (subset) lines.push(`Restoring ${subset.selected} of ${subset.total} changed files.`);
 	if (changeSummary) lines.push(`${changeSummary} since the snapshot. HEAD is untouched.`);
 	if (diff) lines.push("", previewDiffText(diff));
 	if (scope !== "code") lines.push("", "This prompt returns to the editor so you can edit and resubmit.");
 	return lines.join("\n");
 }
 
+/** What the path step decided: the whole tree, a chosen subset, or nothing. */
+export type PathChoice = { kind: "all" } | { kind: "some"; paths: string[] } | { kind: "cancel" };
+
+/** The two answers the path step offers before the checklist opens. */
+const ALL_LABEL = (count: number): string => `Everything (${count} file${count === 1 ? "" : "s"})`;
+const SOME_LABEL = "Choose paths…";
+
+/**
+ * Ask which paths to restore. The checklist needs a list only a TUI can mount, so
+ * every other mode keeps the whole-tree restore rather than inventing a typed
+ * syntax with its own parser and preview.
+ */
+export async function choosePaths(
+	pi: ExtensionAPI,
+	ctx: ExtensionCommandContext,
+	paths: readonly ChangedPath[],
+): Promise<PathChoice> {
+	if (ctx.mode !== "tui" || paths.length === 0) return { kind: "all" };
+
+	const choice = await ctx.ui.select("Restore what?", [ALL_LABEL(paths.length), SOME_LABEL]);
+	if (choice === undefined) return { kind: "cancel" };
+	if (choice !== SOME_LABEL) return { kind: "all" };
+
+	const selected = await withRailsSuppressed(pi, () =>
+		ctx.ui.custom<string[] | undefined>(
+			(tui, theme, _keybindings, done) =>
+				new PathPickerComponent({
+					paths,
+					theme,
+					onClose: (subset) => done(subset),
+					requestRender: () => tui.requestRender(),
+					viewportRows: () => tui.terminal?.rows,
+				}),
+		),
+	);
+	if (!selected) return { kind: "cancel" };
+	// An empty checklist is a choice, not a cancel: it restores no files and still
+	// moves the conversation, which is what the confirm describes.
+	return { kind: "some", paths: selected };
+}
+
 /**
  * Rewind to `point` with the chosen scope. Interactive only: callers guard on
  * `ctx.hasUI`. Returns true when something was applied.
  */
 export async function rewindTo(
+	pi: ExtensionAPI,
 	runtime: RewindRuntime,
 	ctx: ExtensionCommandContext,
 	root: string | undefined,
@@ -81,6 +133,9 @@ export async function rewindTo(
 	}
 
 	let plan;
+	/** The subset to restore, when the path step narrowed the plan. */
+	let selection: string[] | undefined;
+	let total = 0;
 	if (snapshot && root) {
 		const result = await runtime.plan(root, snapshot);
 		if (!result.ok) {
@@ -88,12 +143,34 @@ export async function rewindTo(
 			return false;
 		}
 		plan = result.plan;
+		total = plan.paths.length;
+		if (plan.paths.length > 0) {
+			const choice = await choosePaths(pi, ctx, plan.paths);
+			if (choice.kind === "cancel") {
+				ctx.ui.notify("Rewind cancelled.", "info");
+				return false;
+			}
+			if (choice.kind === "some") {
+				selection = choice.paths;
+				const narrowed = await runtime.plan(root, snapshot, selection);
+				if (!narrowed.ok) {
+					ctx.ui.notify(narrowed.reason, "warning");
+					return false;
+				}
+				plan = narrowed.plan;
+			}
+		}
 	}
 
 	const label = point.summary || point.prompt || "this prompt";
 	const approved = await ctx.ui.confirm(
 		`Rewind to "${label}"?`,
-		confirmBody(scope, plan ? formatChangeSummary(plan.changed, plan.removed) : undefined, plan?.diff),
+		confirmBody(
+			scope,
+			plan ? formatChangeSummary(plan.changed, plan.removed) : undefined,
+			plan?.diff,
+			selection ? { selected: plan?.paths.length ?? 0, total } : undefined,
+		),
 	);
 	if (!approved) {
 		ctx.ui.notify("Rewind cancelled.", "info");
@@ -103,7 +180,7 @@ export async function rewindTo(
 	const notes: string[] = [];
 	if (snapshot && root) {
 		try {
-			const restored = await runtime.restore(ctx, root, snapshot, runtime.configFor(root));
+			const restored = await runtime.restore(ctx, root, snapshot, runtime.configFor(root), selection);
 			await runtime.setStatus(ctx);
 			notes.push(formatRestoreText(restored));
 		} catch (error) {

package/extensions/rewind/runtime.ts

@@ -33,8 +33,15 @@ export interface RewindRuntime {
 	/** Create and store a snapshot of the current working tree. */
 	snapshot(ctx: ExtensionContext, options: SnapshotOptions): Promise<Snapshot>;
 	list(root: string): Promise<Snapshot[]>;
-	plan(root: string, target: Snapshot): Promise<PlanResult>;
-	restore(ctx: ExtensionContext, root: string, target: Snapshot, config: RewindConfig): Promise<RestoreSummary>;
+	/** Preview a restore; `paths` narrows it to a subset of the changed paths. */
+	plan(root: string, target: Snapshot, paths?: readonly string[]): Promise<PlanResult>;
+	restore(
+		ctx: ExtensionContext,
+		root: string,
+		target: Snapshot,
+		config: RewindConfig,
+		paths?: readonly string[],
+	): Promise<RestoreSummary>;
 	/** Repaint the `↺ N` chip from the prompt count on the active branch (`/rewind` list size). */
 	setStatus(ctx: ExtensionContext): Promise<void>;
 	clearStatus(ctx: ExtensionContext): void;
@@ -110,10 +117,10 @@ export function createRuntime(pi: ExtensionAPI): RewindRuntime {
 	const list = (root: string): Promise<Snapshot[]> =>
 		listSnapshots(runGit, root, configFor(root).refNamespace, { root });
 
-	const plan = (root: string, target: Snapshot): Promise<PlanResult> =>
+	const plan = (root: string, target: Snapshot, paths?: readonly string[]): Promise<PlanResult> =>
 		queue.enqueue(async () => {
 			if (!belongsToRoot(target, root)) return { ok: false, reason: foreignRootReason(target, root) };
-			return planRestore({ runGit }, { root, indexFile: await indexStore.pathFor(root), target });
+			return planRestore({ runGit }, { root, indexFile: await indexStore.pathFor(root), target, paths });
 		});
 
 	const restore = (
@@ -121,11 +128,12 @@ export function createRuntime(pi: ExtensionAPI): RewindRuntime {
 		root: string,
 		target: Snapshot,
 		config: RewindConfig,
+		paths?: readonly string[],
 	): Promise<RestoreSummary> =>
 		queue.enqueue(async () => {
 			if (!belongsToRoot(target, root)) throw new Error(foreignRootReason(target, root));
 			const indexFile = await indexStore.pathFor(root);
-			const input: RestoreInput = { root, indexFile, target };
+			const input: RestoreInput = { root, indexFile, target, paths };
 			let safety: string | undefined;
 			if (config.safetySnapshot) {
 				const before = await createSnapshot(

package/extensions/rewind/snapshot-run.ts

@@ -15,8 +15,11 @@ import { createSnapshotPolicy, type SnapshotPolicy } from "./policy.ts";
 import type { RewindRuntime } from "./runtime.ts";
 
 export interface SnapshotRun {
-	/** Start a run for `prompt`: reset run state and resolve the snapshot decision. */
-	beginRun(prompt: string, ctx: ExtensionContext): Promise<void>;
+	/**
+	 * Start a run for `prompt` — `undefined` when a custom message started it: reset
+	 * run state and resolve the snapshot decision.
+	 */
+	beginRun(prompt: string | undefined, ctx: ExtensionContext): Promise<void>;
 	/** Take the run's single snapshot before the first mutating call, at most once. */
 	onToolCall(toolName: string, ctx: ExtensionContext): Promise<void>;
 	/** Drop run-scoped state (on session shutdown). */

package/extensions/rewind/types.ts

@@ -53,6 +53,8 @@ export interface RestoreSummary {
 	changed: number;
 	/** Files deleted because they were created after the snapshot. */
 	removed: number;
+	/** Paths the whole diff touched, present only when a subset was restored. */
+	of?: number;
 	/** Id of the pre-restore safety snapshot, when one was taken. */
 	safety?: string;
 }

package/extensions/subagent/README.md

@@ -236,7 +236,13 @@ step's `Output`.
   they are not written to the parent session.
 - **No cost attribution to the parent session.** A subagent's tokens and cost are
   captured in the tool result and shown in the transcript, but they belong to a
-  separate process and are not added to the dispatching session's totals.
+  separate process and are not added to the dispatching session's totals. Instead,
+  each finished run publishes `my-pi-agent/subagent-finished`
+  (`SubagentFinishedEvent` in `lib/events.ts`) and bytefly's footer shows the
+  session's child runs as their own `↳` roll-up, priced separately from the
+  session total (the last 500 runs). The roll-up is per process: a resumed session
+  starts from zero, and a run that never produced an assistant message publishes
+  nothing.
 
 ## Pi integration
 

package/extensions/subagent/accounting.ts

@@ -0,0 +1,34 @@
+/**
+ * The accounting event a finished child run publishes.
+ *
+ * `subagent` runs each child in its own `pi` process, so the dispatcher's own
+ * usage totals never include what the child spent. The event carries the child's
+ * pricing inputs (provider, model, token counts, Pi's recorded dollar cost, finish
+ * time) rather than a total, so the consumer can price them with the same rate
+ * table and currency it uses for the session — and re-price them after a currency
+ * change.
+ *
+ * A run with no assistant message spent nothing observable (an unknown agent, a
+ * spawn failure), so it publishes nothing at all.
+ */
+
+import type { SubagentFinishedEvent } from "../../lib/events.ts";
+import type { SingleResult } from "./types.ts";
+
+/** The event for one finished run, or `null` when it produced no usage. */
+export function finishedEvent(result: SingleResult): SubagentFinishedEvent | null {
+	const { usage } = result;
+	if (usage.turns === 0) return null;
+	return {
+		agent: result.agent,
+		provider: result.provider ?? null,
+		model: result.model ?? null,
+		input: usage.input,
+		output: usage.output,
+		cacheRead: usage.cacheRead,
+		cacheWrite: usage.cacheWrite,
+		recordedCost: usage.cost,
+		at: result.finishedAt ?? null,
+		exitCode: result.exitCode,
+	};
+}

package/extensions/subagent/index.ts

@@ -27,6 +27,8 @@ import {
 } from "./agents.ts";
 import { runChainMode, runParallelMode, runSingleMode, type ModeContext } from "./orchestrate.ts";
 import { renderSubagentCall, renderSubagentResult } from "./render.ts";
+import { SUBAGENT_FINISHED_CHANNEL } from "../../lib/events.ts";
+import { finishedEvent } from "./accounting.ts";
 import { runSingleAgent, type RunOptions } from "./run.ts";
 import { SubagentParams, resolveMode, type SubagentArgs } from "./schema.ts";
 import type { DispatchDefaults, SingleResult, SubagentDetails } from "./types.ts";
@@ -65,7 +67,27 @@ function requestedAgentNames(args: SubagentArgs): string[] {
 
 export default function subagent(pi: ExtensionAPI, deps: SubagentDeps = {}): void {
 	if (!isExtensionEnabled("subagent")) return;
-	const run = deps.run ?? runSingleAgent;
+	const runner = deps.run ?? runSingleAgent;
+
+	/**
+	 * Account for each finished child, then hand the result on unchanged.
+	 *
+	 * Every mode (`single`, `parallel` per task, `chain` per step) calls this once
+	 * per child, so one wrapper reports each run exactly once. The emit is guarded:
+	 * a bus listener that throws must not fail a delegation that already ran.
+	 */
+	const run = async (options: RunOptions): Promise<SingleResult> => {
+		const result = await runner(options);
+		const event = finishedEvent(result);
+		if (event) {
+			try {
+				pi.events.emit(SUBAGENT_FINISHED_CHANNEL, event);
+			} catch {
+				// Accounting is best-effort; the run's own result is what matters.
+			}
+		}
+		return result;
+	};
 
 	pi.registerTool({
 		name: TOOL_NAME,

package/extensions/subagent/stream.ts

@@ -47,6 +47,7 @@ export function applyEvent(result: SingleResult, event: unknown): boolean {
 
 		if (message.role === "assistant") {
 			const assistant = message as Message & {
+				provider?: string;
 				model?: string;
 				stopReason?: string;
 				errorMessage?: string;
@@ -69,6 +70,7 @@ export function applyEvent(result: SingleResult, event: unknown): boolean {
 				result.usage.cost += usage.cost?.total ?? 0;
 				result.usage.contextTokens = usage.totalTokens ?? result.usage.contextTokens;
 			}
+			if (!result.provider && assistant.provider) result.provider = assistant.provider;
 			if (!result.model && assistant.model) result.model = assistant.model;
 			if (assistant.stopReason) result.stopReason = assistant.stopReason;
 			if (assistant.errorMessage) result.errorMessage = assistant.errorMessage;

package/extensions/subagent/types.ts

@@ -37,6 +37,8 @@ export interface SingleResult {
 	messages: Message[];
 	stderr: string;
 	usage: UsageStats;
+	/** Provider and model the child reported; published for the accounting event. */
+	provider?: string;
 	model?: string;
 	stopReason?: string;
 	errorMessage?: string;

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

@@ -29,9 +29,13 @@ How the `watch` call and its result look in the transcript — the call line as
 - Shows a `⊚ N` running-watcher chip and a `! N` unreported-match chip, raises a
   `ctx.ui.notify` alert once per unreported burst, and offers a `/watch` screen.
 - Reports pending matches to the model at the start of the next turn, or wakes a
-  turn for a watcher added with `wake: true`.
-- Watchers are session-only: `shutdown` flushes a partial line, kills every
-  command's process tree, and clears the chips.
+  turn for a watcher added with `wake: true`. A wake also leaves the terminal: the
+  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, sends SIGTERM to
+  every command's process tree (escalating to SIGKILL after a short grace), and
+  clears the chips.
 
 ## Tool
 
@@ -39,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). |
@@ -128,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. |
@@ -157,17 +161,21 @@ 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
   older lines are dropped.
 - Matching is per line; a pattern cannot span a newline.
+- Only a **wake** match raises an OS notification, and only when bytefly's
+  `notify.enabled` and `notify.matchFound` are on. A match collected while the
+  agent was busy is reported at the next turn without a notification, and `watch`
+  itself never sends one — it announces the match and bytefly owns delivery.
 
 ## Non-goals
 
 - Persisting or reattaching watchers across sessions.
-- Notifying through bytefly's OS-notification capability (the `job` extension
-  owns that channel; `watch` alerts in-session with `ctx.ui.notify`).
 - Multiline or stateful matching, log rotation hooks, and per-watcher poll
   intervals.
 
@@ -195,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/index.ts

@@ -12,6 +12,7 @@
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { isExtensionEnabled } from "../../lib/env.ts";
+import { WATCH_MATCH_CHANNEL, type WatchMatchEvent } from "../../lib/events.ts";
 import { sanitizeLine } from "../../lib/format.ts";
 import { noticeMessage, type NoticeMessage, pruneStaleNotices } from "../../lib/notice.ts";
 import { STATUS_KEYS } from "../../lib/tui/glyphs.ts";
@@ -80,6 +81,24 @@ export default function watch(pi: ExtensionAPI, deps: WatchDeps = {}): void {
 			waking = true;
 		} catch {
 			// Waking is best-effort; the next turn still reports the matches.
+			return;
+		}
+		// A wake means the user is away from the terminal, so the alert also leaves
+		// the process. bytefly's notify capability owns delivery; this publishes the
+		// fact and never learns how it is sent. The newest match is the one an alert
+		// is about, while the count covers the whole cycle.
+		const newest = pending[pending.length - 1];
+		if (!newest) return;
+		try {
+			const event: WatchMatchEvent = {
+				count: pending.length,
+				watcherId: newest.watcherId,
+				label: newest.label,
+				line: newest.line,
+			};
+			pi.events.emit(WATCH_MATCH_CHANNEL, event);
+		} catch {
+			// A throwing listener must not cost the wake that already happened.
 		}
 	};