dorfl 0.0.0 → 0.1.0

package/src/verify-workflow-template.ts

@@ -0,0 +1,159 @@
+/**
+ * The `install-ci` VERIFY-WORKFLOW capability (prd
+ * `land-time-reverify-and-parallel-merge-ceiling`, task
+ * `install-ci-tier1-branch-protection`; Story 11 — the Tier-1 GitHub ceiling).
+ * Emits a small `verify.yml` workflow whose ONLY job is `verify` and runs on
+ * `pull_request` (and `merge_group`, the Tier-2 forward seam). It produces the
+ * GitHub check named exactly {@link VERIFY_CHECK_CONTEXT}, which the
+ * branch-protection step ({@link installCIBranchProtectionStep}) names as the
+ * required-status check `context`. Co-locating the two strings — the EMITTED
+ * job/check name AND the REQUIRED context — in one constant pins the
+ * acceptance-criterion "context matches the workflow's job name" by construction
+ * (a single test diffs the two).
+ *
+ * The workflow is deliberately thin: it wires the same composite setup action
+ * the other capabilities use, then runs `dorfl verify` — the deterministic shell
+ * gate the repo declares in `.dorfl.json`. No agent, no provider secrets, no
+ * `gh` mutation; it is read-only with respect to `work/`.
+ *
+ * `merge_group` is present (with no extra wiring) so a follow-on Tier-2 task
+ * (GitHub Merge Queue) can flip the ruleset on without changing this workflow's
+ * trigger surface — the forward seam the spec's Applied Answers q3 names.
+ */
+
+import type {ResolvedCIConfig} from './install-ci-core.js';
+
+/**
+ * The required-status-check CONTEXT install-ci sets via branch protection AND the
+ * job/check name the emitted verify workflow produces. ONE source of truth so
+ * the two strings can never drift (the "context matches the workflow's job name"
+ * acceptance criterion is enforced by both reading this constant).
+ */
+export const VERIFY_CHECK_CONTEXT = 'verify';
+
+/** The capability id (the registry key + the emitted workflow file stem). */
+export const VERIFY_CAPABILITY_ID = 'verify';
+
+/** The wizard-facing label for the verify capability. */
+export const VERIFY_CAPABILITY_LABEL =
+	'Run the repo `verify` gate on every PR (the Tier-1 GitHub ceiling: produces the required-status check `verify` that branch protection requires)';
+
+/** The repo-relative path (under the output base) of the emitted workflow. */
+export const VERIFY_WORKFLOW_PATH = 'workflows/verify.yml';
+
+/**
+ * Generate the verify workflow YAML. Deterministic: the same config produces
+ * byte-identical output. The job is named exactly {@link VERIFY_CHECK_CONTEXT}
+ * so the GitHub check it produces matches the required-status `context` install-ci
+ * configures on `main` — by construction, not by hand-typed agreement.
+ */
+export function generateVerifyWorkflow(_config: ResolvedCIConfig): string {
+	return `\
+# dorfl — the VERIFY workflow (Tier-1 GitHub ceiling; prd
+# land-time-reverify-and-parallel-merge-ceiling, task
+# install-ci-tier1-branch-protection). EMITTED by \`dorfl install-ci\`; the
+# human commits it. DO NOT hand-edit a copy — re-run install-ci to upgrade.
+#
+# This workflow exists SOLELY to produce a GitHub check named \`${VERIFY_CHECK_CONTEXT}\`
+# on every pull request, which install-ci's branch-protection step requires
+# (\`required_status_checks.strict: true\` + a required \`${VERIFY_CHECK_CONTEXT}\` context)
+# so a PR cannot be merged stale. The merge button is disabled until \`${VERIFY_CHECK_CONTEXT}\`
+# reports success on the rebased PR head — closing the PR-merge-time drift window
+# story 7 names.
+#
+# \`merge_group\` is listed so a follow-on Tier-2 task (GitHub Merge Queue) can
+# enable speculative-rebase merging by flipping the ruleset, WITHOUT changing
+# this workflow's trigger surface (the Applied Answer q3 forward seam).
+#
+# CONTEXT NAMING — the job is named EXACTLY \`${VERIFY_CHECK_CONTEXT}\`. install-ci
+# names the same string as the required-context, so they cannot drift. If you
+# rename the job here you MUST re-run install-ci (or the protection's required
+# context will not match this workflow and every PR will block forever).
+#
+# SAFETY (US #9): the running job requests NO \`workflows\` permission and runs
+# only \`dorfl verify\` (a deterministic shell gate; \`pnpm format:check && pnpm
+# build && pnpm test\` for the dorfl repo). It cannot edit \`.github/workflows/**\`
+# or mutate \`work/\`.
+
+name: ${VERIFY_CHECK_CONTEXT}
+
+on:
+  pull_request:
+  # Tier-2 forward seam: a follow-on task enables GitHub Merge Queue and the
+  # same job re-runs on the speculative-rebase merge-group head, no template edit.
+  merge_group:
+
+# Serialise overlapping verify runs on the same ref (the latest commit wins —
+# stale runs are cancelled, since \`verify\` is a pure pass/fail gate).
+concurrency:
+  group: ${VERIFY_CHECK_CONTEXT}-\${{ github.ref }}
+  cancel-in-progress: true
+
+# NO \`workflows\` permission (US #9). \`contents: read\` is all the gate needs.
+permissions:
+  contents: read
+
+jobs:
+  # The job name IS the GitHub check context — it must equal VERIFY_CHECK_CONTEXT
+  # (\`${VERIFY_CHECK_CONTEXT}\`) or install-ci's branch protection will require a
+  # context this workflow does not produce.
+  ${VERIFY_CHECK_CONTEXT}:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: ./.github/actions/dorfl-setup
+      - name: run the repo verify gate
+        run: dorfl verify
+`;
+}
+
+/** A single structural problem found in the generated verify workflow. */
+export interface VerifyWorkflowProblem {
+	id: string;
+	message: string;
+}
+
+/** Result of {@link validateVerifyWorkflow}. */
+export interface VerifyWorkflowValidation {
+	ok: boolean;
+	problems: VerifyWorkflowProblem[];
+}
+
+/**
+ * Structurally validate the verify workflow against the task's acceptance
+ * criteria (job name = required context, runs on `pull_request`, ships the
+ * `merge_group` seam, no `workflows:` permission).
+ */
+export function validateVerifyWorkflow(text: string): VerifyWorkflowValidation {
+	const problems: VerifyWorkflowProblem[] = [];
+	const require = (id: string, present: boolean, message: string): void => {
+		if (!present) problems.push({id, message});
+	};
+	const operative = text
+		.split('\n')
+		.filter((line) => !/^\s*#/.test(line))
+		.join('\n');
+
+	require('job-named-verify-context', new RegExp(
+		`^\\s{2}${VERIFY_CHECK_CONTEXT}:\\s*$`,
+		'm',
+	).test(
+		operative,
+	), `the workflow must declare a job named exactly \`${VERIFY_CHECK_CONTEXT}\` ` +
+		'(its name IS the GitHub check context install-ci requires).');
+	require('trigger-pull-request', /\bon:\s*[\s\S]*?\bpull_request\s*:/.test(
+		operative,
+	), 'must trigger on `pull_request` (the check must run on every PR).');
+	require('trigger-merge-group-seam', /\bmerge_group\s*:/.test(
+		operative,
+	), 'must list `merge_group` as a trigger (the Tier-2 GitHub Merge Queue forward seam).');
+	require('no-workflows-permission', !/\bworkflows\s*:\s*write\b/.test(
+		operative,
+	), 'must request NO `workflows` permission (US #9).');
+	require('runs-dorfl-verify', /dorfl verify\b/.test(
+		operative,
+	), 'the job must run `dorfl verify` (the deterministic shell gate the repo declares).');
+	return {ok: problems.length === 0, problems};
+}

package/src/verify.ts

@@ -0,0 +1,123 @@
+import {spawn} from 'node:child_process';
+
+/**
+ * The per-repo acceptance gate, run as `dorfl verify`. It is a
+ * deterministic shell gate — a declared, per-repo command (or ordered list of
+ * commands) — NOT prose interpreted by a model. There is no LLM in this loop:
+ * the gate is known by reading config, and it either passes (exit 0) or it does
+ * not. This same mechanism is consumed by the human `complete` command (where it
+ * is a default-on, `--skip-verify`-able safety-net) and by the autonomous
+ * `run-once`/`watch` (where it is the authoritative, non-skippable trust
+ * boundary). `verify` itself just runs the gate; callers decide authority.
+ *
+ * It is read-only with respect to `work/`: it runs the declared check and never
+ * moves or commits anything.
+ */
+
+/**
+ * The per-repo gate, as declared in config. A single shell command, or an
+ * ordered list of commands run in sequence (each must pass for the gate to
+ * pass). `undefined` (unset) ⇒ {@link DEFAULT_VERIFY_COMMAND} is used.
+ */
+export type VerifyConfig = string | string[];
+
+/**
+ * The sensible default when no `verify` is configured: build, then test, then
+ * check formatting across the workspace. Deterministic, auditable, no model.
+ */
+export const DEFAULT_VERIFY_COMMAND =
+	'pnpm -r build && pnpm -r test && pnpm -r format:check';
+
+/**
+ * Resolve the declared gate into an ordered, non-empty list of shell commands.
+ * Unset ⇒ the default. A string ⇒ a single command. A list ⇒ the list, with
+ * blank/whitespace-only entries dropped (and the default substituted if that
+ * leaves nothing). Each command is run in sequence; all must pass.
+ */
+export function resolveVerifyCommands(
+	verify: VerifyConfig | undefined,
+): string[] {
+	if (verify === undefined) {
+		return [DEFAULT_VERIFY_COMMAND];
+	}
+	const list = Array.isArray(verify) ? verify : [verify];
+	const commands = list.filter((command) => command.trim() !== '');
+	return commands.length > 0 ? commands : [DEFAULT_VERIFY_COMMAND];
+}
+
+export interface RunVerifyOptions {
+	/** The repo to run the gate in (its working directory). */
+	cwd: string;
+	/** The declared gate (string | list). Unset ⇒ the default command. */
+	verify?: VerifyConfig;
+	/** Environment for the gate's child processes. */
+	env?: NodeJS.ProcessEnv;
+	/** Sink for streamed stdout chunks. Defaults to `process.stdout.write`. */
+	onStdout?: (chunk: string) => void;
+	/** Sink for streamed stderr chunks. Defaults to `process.stderr.write`. */
+	onStderr?: (chunk: string) => void;
+}
+
+export interface RunVerifyResult {
+	/** The exit code of the gate: 0 iff every command passed. */
+	exitCode: number;
+	/** The ordered commands that were run (resolved from config). */
+	commands: string[];
+	/** Whether the gate passed (exitCode === 0). */
+	passed: boolean;
+}
+
+/**
+ * Run the resolved gate command(s) in `cwd`, streaming output, and resolve with
+ * the gate's status: exit 0 iff every command passed. Commands run in sequence;
+ * the first non-zero exit short-circuits the rest and becomes the result
+ * (mirroring `&&` semantics). Each command is run through `bash -c` so that
+ * shell operators in the declared gate (`&&`, pipes, etc.) behave as written.
+ */
+export async function runVerify(
+	options: RunVerifyOptions,
+): Promise<RunVerifyResult> {
+	const commands = resolveVerifyCommands(options.verify);
+	const onStdout =
+		options.onStdout ?? ((chunk: string) => process.stdout.write(chunk));
+	const onStderr =
+		options.onStderr ?? ((chunk: string) => process.stderr.write(chunk));
+
+	for (const command of commands) {
+		const exitCode = await runOne(command, options.cwd, options.env, {
+			onStdout,
+			onStderr,
+		});
+		if (exitCode !== 0) {
+			return {exitCode, commands, passed: false};
+		}
+	}
+	return {exitCode: 0, commands, passed: true};
+}
+
+/** Spawn one command via `bash -c`, streaming its output, resolving its code. */
+function runOne(
+	command: string,
+	cwd: string,
+	env: NodeJS.ProcessEnv | undefined,
+	sinks: {onStdout: (chunk: string) => void; onStderr: (chunk: string) => void},
+): Promise<number> {
+	return new Promise((resolvePromise, reject) => {
+		const child = spawn('bash', ['-c', command], {
+			cwd,
+			env: env ?? process.env,
+		});
+		child.stdout.on('data', (chunk: Buffer) => {
+			sinks.onStdout(chunk.toString('utf8'));
+		});
+		child.stderr.on('data', (chunk: Buffer) => {
+			sinks.onStderr(chunk.toString('utf8'));
+		});
+		child.on('error', (err) =>
+			reject(new Error(`failed to spawn gate command: ${err.message}`)),
+		);
+		child.on('close', (code) => {
+			resolvePromise(code ?? -1);
+		});
+	});
+}

package/src/watch-session.ts

@@ -0,0 +1,397 @@
+import {open, type FileHandle} from 'node:fs/promises';
+
+/**
+ * The **`do --watch` observer** (tasks `do-watch` + `do-watch-session-log-format`)
+ * — a READ-ONLY concurrent tail of the pi session `.jsonl` event log, restoring
+ * for `do` the live agent-conversation view `ar-run.sh --watch` gave.
+ *
+ * `ar-run.sh --watch` piped `pi -p --mode json | jq` to surface the high-signal
+ * events; `do` runs the agent CAPTURED through the harness seam, so that live
+ * view was lost. The pi adapter writes a session `.jsonl` at the KNOWN file path
+ * the caller generated (`--session <path>`, task `session-path-pi-default`) —
+ * but that is pi's SESSION-PERSISTENCE log, a DIFFERENT format from the
+ * `--mode json` STREAM `ar-run.sh` piped. The tailer is pointed at that EXACT
+ * path (no newest-by-mtime dir guessing), so the stale-sibling race is gone.
+ *
+ * A session-log record is `{"type":"message", "message":{role, content[]}}` (or a
+ * `session`/`model_change`/`thinking_level_change` preamble record). The earlier
+ * classifier matched the STREAM vocabulary (`tool_start`/`message_end`/`agent_end`),
+ * none of which occur in the session log — so every line fell through to skip and
+ * `do --watch` was silently a no-op. This module tails the growing session log and
+ * surfaces the same high-signal level `ar-run.sh --watch` gave, read off the
+ * SESSION-LOG shape:
+ *
+ *   - an `assistant` `message` → its `content[]` `text` parts, then `▶ <name>`
+ *     (cyan) per `content[]` `toolCall` part;
+ *   - `✓ agent finished` (green) on PROCESS EXIT — the session log has no
+ *     `agent_end` event, so the tailer emits it once on `stop()`;
+ *   - everything else (`session`/`model_change`/user messages/tool results/…) →
+ *     skipped.
+ *
+ * The classifier mirrors pi-remote's `session-pool.ts` reference parser (`type` →
+ * `role` → `content[]` block walk over `thinking`/`text`/`toolCall`, incl.
+ * `tc.name||tc.toolName` and content-as-string). The JSONL is parsed in TS (NO
+ * `jq` — that bash dependency is part of what `do` replaces). It is a PURE
+ * OBSERVER: it only READS the log; it never changes the run's outcome, gate,
+ * integration, git, or exit code. Colour is honoured ONLY on a TTY / when
+ * `NO_COLOR` is unset (the same rule as `output.ts`), threaded in by the caller
+ * as a boolean.
+ */
+
+// The same conventional ANSI codes `ar-run.sh`'s jq filter emitted (cyan tool
+// marker, green finished marker, reset). Colour is applied ONLY when the caller
+// passes `color: true` (its TTY/NO_COLOR decision); plain otherwise.
+const CYAN = '\u001b[36m';
+const GREEN = '\u001b[32m';
+const RESET = '\u001b[0m';
+
+/** Wrap `text` in `code` + reset when `color`, else return it unchanged. */
+function paint(text: string, color: boolean, code: string): string {
+	return color ? `${code}${text}${RESET}` : text;
+}
+
+/**
+ * A structural view of the pi SESSION-LOG records we classify. It mirrors the
+ * `@earendil-works/pi-coding-agent` `SessionEntry` / `SessionMessageEntry`
+ * shapes (`type:"message"` with a nested `message.role` + `message.content`) but
+ * is declared locally so the observer needs no runtime dependency on that
+ * package's (heavy) type tree — dorfl does not otherwise depend on it.
+ * The content blocks are read defensively (like pi-remote's reference parser,
+ * which casts them via `as any`): a content part may be a `text`, a `thinking`,
+ * or a `toolCall` (whose name is `name` OR `toolName`), or the whole content may
+ * be a plain string.
+ */
+interface SessionLogRecord {
+	type?: unknown;
+	message?: {
+		role?: unknown;
+		content?: unknown;
+	};
+}
+
+/** The green `✓ agent finished` line, emitted on PROCESS EXIT (not a log event). */
+export function finishedLine(color: boolean): string {
+	return paint('✓ agent finished', color, GREEN);
+}
+
+/**
+ * A one-line VISUAL BOUNDARY banner the caller prints between two tailed agent
+ * streams (e.g. the build stream and the Gate-2 review stream — task
+ * `watch-review-session`), so a watching human knows the first stream ended and
+ * the next began. Reuses this module's colour rule (cyan, the same marker hue as
+ * the `▶ <tool>` lines) so it reads as part of the same live view. Pure: returns
+ * the string; the caller routes it to the watch sink.
+ */
+export function boundaryLine(label: string, color: boolean): string {
+	return paint(`▶ ${label}`, color, CYAN);
+}
+
+/**
+ * Parse ONE pi SESSION-LOG `.jsonl` line and return the high-signal lines to
+ * surface — or `[]` to SKIP it. This is the pure, unit-testable classifier,
+ * mirroring pi-remote's `session-pool.ts` block walk:
+ *
+ *   - a `{type:"message", message:{role:"assistant", content}}` record → for each
+ *     `content[]` part: a `text` part yields its text (parts concatenated into
+ *     ONE line, like the old `jq` `.content[]` select); a `toolCall` part yields
+ *     `▶ <name>` (cyan; `name` OR `toolName`, defaulting to `tool`); a `thinking`
+ *     part (and anything else) is skipped. A plain-string `content` yields one
+ *     text line.
+ *   - everything else (`session`/`model_change`/`thinking_level_change`, user
+ *     messages, tool results, blank/malformed lines) → `[]` (skipped).
+ *
+ * "Finished" is NOT a record here — the session log has no `agent_end`; the
+ * tailer emits {@link finishedLine} on process exit instead.
+ *
+ * Malformed JSON is skipped (not thrown): a partially-written trailing line in a
+ * growing log must not crash the observer.
+ */
+export function formatWatchEvent(line: string, color: boolean): string[] {
+	const trimmed = line.trim();
+	if (trimmed === '') {
+		return [];
+	}
+	let event: unknown;
+	try {
+		event = JSON.parse(trimmed);
+	} catch {
+		// A half-written trailing line in a growing log — skip, never throw.
+		return [];
+	}
+	if (typeof event !== 'object' || event === null) {
+		return [];
+	}
+	const record = event as SessionLogRecord;
+	if (record.type !== 'message') {
+		return [];
+	}
+	const message = record.message;
+	if (!message || message.role !== 'assistant') {
+		// Skip user turns, tool results, and any non-assistant message.
+		return [];
+	}
+	return assistantLines(message.content, color);
+}
+
+/**
+ * Walk an assistant `message.content` into the lines to surface, mirroring
+ * pi-remote's `session-pool.ts` reference parser. The `text` parts are
+ * concatenated into a SINGLE leading line (so a multi-part assistant turn reads
+ * as one sentence, as `ar-run.sh --watch` showed it); each `toolCall` part adds a
+ * `▶ <name>` line after it. A plain-string content yields the single text line.
+ * `thinking` parts and any other block type are skipped.
+ */
+function assistantLines(content: unknown, color: boolean): string[] {
+	if (typeof content === 'string') {
+		return content === '' ? [] : [content];
+	}
+	if (!Array.isArray(content)) {
+		return [];
+	}
+	const lines: string[] = [];
+	const text = assistantContentText(content);
+	for (const part of content) {
+		if (typeof part !== 'object' || part === null) {
+			continue;
+		}
+		const p = part as Record<string, unknown>;
+		if (p.type === 'toolCall') {
+			const name =
+				(typeof p.name === 'string' && p.name !== '' && p.name) ||
+				(typeof p.toolName === 'string' && p.toolName !== '' && p.toolName) ||
+				'tool';
+			lines.push(paint(`▶ ${name}`, color, CYAN));
+		}
+		// `text` is collected by assistantContentText; `thinking` and any other
+		// block type are skipped.
+	}
+	return text === '' ? lines : [text, ...lines];
+}
+
+/**
+ * Concatenate the `text` parts of ONE assistant `message.content` (the answer
+ * text, with tool/thinking blocks dropped) — the single source of truth for
+ * "what did the assistant SAY" shared by the {@link assistantLines} watch view
+ * and the {@link lastAssistantText} output reader (task `harness-agent-output`).
+ * A plain-string content is itself the text. Returns `''` when there is no text.
+ */
+function assistantContentText(content: unknown): string {
+	if (typeof content === 'string') {
+		return content;
+	}
+	if (!Array.isArray(content)) {
+		return '';
+	}
+	const textParts: string[] = [];
+	for (const part of content) {
+		if (typeof part !== 'object' || part === null) {
+			continue;
+		}
+		const p = part as Record<string, unknown>;
+		if (p.type === 'text' && typeof p.text === 'string') {
+			textParts.push(p.text);
+		}
+	}
+	return textParts.join('');
+}
+
+/**
+ * Extract the **last assistant message's text** from a pi session `.jsonl`
+ * (task `harness-agent-output`) — the agent's final ANSWER, surfaced through
+ * the harness seam as `LaunchResult.output`. It REUSES this module's session-log
+ * shape walk (one parser, not two): it scans the `{type:"message",
+ * message:{role:"assistant", content[]}}` records, takes the LAST one carrying
+ * non-empty `text`, and returns its concatenated text.
+ *
+ * Returns `undefined` when the log has no assistant text at all — an absent log,
+ * a malformed/short log, or a run whose only assistant turn was tool-calls (no
+ * `text` part). A tool-only assistant turn is NOT a final answer, so a LATER
+ * text turn (if any) wins; with no text turn anywhere the result is `undefined`.
+ *
+ * Malformed/blank lines are skipped (never thrown): a partially-written trailing
+ * line in a just-closed log must not crash the reader.
+ */
+export function lastAssistantText(jsonl: string): string | undefined {
+	let last: string | undefined;
+	for (const line of jsonl.split('\n')) {
+		const trimmed = line.trim();
+		if (trimmed === '') {
+			continue;
+		}
+		let event: unknown;
+		try {
+			event = JSON.parse(trimmed);
+		} catch {
+			continue; // a half-written / malformed line — skip, never throw.
+		}
+		if (typeof event !== 'object' || event === null) {
+			continue;
+		}
+		const record = event as SessionLogRecord;
+		if (record.type !== 'message') {
+			continue;
+		}
+		const message = record.message;
+		if (!message || message.role !== 'assistant') {
+			continue;
+		}
+		const text = assistantContentText(message.content);
+		if (text !== '') {
+			last = text; // a later text turn supersedes an earlier one.
+		}
+	}
+	return last;
+}
+
+export interface SessionTailerOptions {
+	/**
+	 * The EXACT pi session `.jsonl` file path to tail. The caller generated this
+	 * BEFORE pi launched (`--session <path>`, task `session-path-pi-default`) and
+	 * passed the SAME path to the adapter, so the tailer reads the run's own log
+	 * — no newest-by-mtime dir guessing, no stale-sibling race. The file does NOT
+	 * yet exist when the tailer starts (pi creates it asynchronously after spawn);
+	 * the tailer polls until it appears (ENOENT is tolerated as "not yet").
+	 */
+	sessionFile: string;
+	/** Emit ANSI colour (the caller's TTY/`NO_COLOR` decision). */
+	color: boolean;
+	/** Where formatted high-signal lines are written (defaults to stderr). */
+	sink?: (line: string) => void;
+	/** How often (ms) to poll for new bytes / the log's appearance. */
+	pollIntervalMs?: number;
+}
+
+const DEFAULT_POLL_INTERVAL_MS = 100;
+
+/**
+ * A concurrent, READ-ONLY tail of the pi session `.jsonl`. It polls the KNOWN
+ * session-file path (which the pi adapter creates only once pi starts) until it
+ * appears, then reads newly-appended bytes, splits them into complete lines, and
+ * surfaces each via {@link formatWatchEvent}. A partial trailing line is
+ * buffered until its newline arrives, so an event split across two reads is
+ * never mis-parsed.
+ *
+ * It is a pure observer: nothing it does feeds back into the run. `start()`
+ * begins polling; `stop()` performs one final drain (to catch events written
+ * just before the agent exited), emits the `✓ agent finished` line ONCE (the
+ * session log has no `agent_end` — process exit IS the finish signal), and
+ * releases the file handle. Created and driven by `do --watch` ALONGSIDE the
+ * (async) agent launch; `stop()` runs when that launch returns (i.e. the agent
+ * process exited).
+ */
+export class SessionTailer {
+	private readonly sessionFile: string;
+	private readonly color: boolean;
+	private readonly sink: (line: string) => void;
+	private readonly pollIntervalMs: number;
+
+	private handle: FileHandle | undefined;
+	private offset = 0;
+	private pending = '';
+	private timer: NodeJS.Timeout | undefined;
+	private polling = false;
+	private stopped = false;
+	private finishedEmitted = false;
+
+	constructor(options: SessionTailerOptions) {
+		this.sessionFile = options.sessionFile;
+		this.color = options.color;
+		this.sink = options.sink ?? ((line) => process.stderr.write(`${line}\n`));
+		this.pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+	}
+
+	/** Begin polling for the known session file and tailing its new bytes. */
+	start(): void {
+		if (this.timer !== undefined || this.stopped) {
+			return;
+		}
+		this.timer = setInterval(() => {
+			void this.poll();
+		}, this.pollIntervalMs);
+		// `unref` so an orphaned timer never keeps the process alive past the run.
+		this.timer.unref?.();
+	}
+
+	/**
+	 * Stop tailing: one final drain (events written right before the agent exited
+	 * must still be surfaced), emit the `✓ agent finished` line ONCE (process exit
+	 * is the finish signal — the session log carries no `agent_end`), then release
+	 * the handle. Idempotent: a second `stop()` re-emits nothing.
+	 */
+	async stop(): Promise<void> {
+		const wasStopped = this.stopped;
+		this.stopped = true;
+		if (this.timer !== undefined) {
+			clearInterval(this.timer);
+			this.timer = undefined;
+		}
+		if (!wasStopped) {
+			await this.drain();
+		}
+		if (this.handle !== undefined) {
+			await this.handle.close();
+			this.handle = undefined;
+		}
+		if (!this.finishedEmitted) {
+			this.finishedEmitted = true;
+			this.sink(finishedLine(this.color));
+		}
+	}
+
+	/** One poll tick: ensure the handle is open, then drain new bytes. */
+	private async poll(): Promise<void> {
+		if (this.polling) {
+			return; // a slow read must not overlap the next tick.
+		}
+		this.polling = true;
+		try {
+			await this.drain();
+		} catch {
+			// A transient read error (the log being rotated/created) — try next tick.
+		} finally {
+			this.polling = false;
+		}
+	}
+
+	/** Open the log if not yet open, read appended bytes, surface whole lines. */
+	private async drain(): Promise<void> {
+		if (this.handle === undefined) {
+			// Open the KNOWN path. pi creates it ASYNCHRONOUSLY after spawn, so until
+			// it exists `open` throws ENOENT — treat that as "not yet" and retry next
+			// tick (NEVER open once at start(), which would race the file into being).
+			try {
+				this.handle = await open(this.sessionFile, 'r');
+			} catch (err) {
+				if ((err as NodeJS.ErrnoException).code === 'ENOENT') {
+					return; // file not written yet — wait for it.
+				}
+				throw err; // a real error — bubble to poll's try/catch (next-tick retry).
+			}
+		}
+		const stats = await this.handle.stat();
+		if (stats.size <= this.offset) {
+			return; // no new bytes.
+		}
+		const length = stats.size - this.offset;
+		const buffer = Buffer.alloc(length);
+		const {bytesRead} = await this.handle.read(buffer, 0, length, this.offset);
+		this.offset += bytesRead;
+		this.pending += buffer.toString('utf8', 0, bytesRead);
+		this.flushLines();
+	}
+
+	/** Split the buffer on newlines, surfacing each COMPLETE line; keep the rest. */
+	private flushLines(): void {
+		let newlineIndex = this.pending.indexOf('\n');
+		while (newlineIndex !== -1) {
+			const line = this.pending.slice(0, newlineIndex);
+			this.pending = this.pending.slice(newlineIndex + 1);
+			// A single record may surface MULTIPLE lines (assistant text + each of
+			// its tool starts), or none (skipped record types).
+			for (const formatted of formatWatchEvent(line, this.color)) {
+				this.sink(formatted);
+			}
+			newlineIndex = this.pending.indexOf('\n');
+		}
+	}
+}