pi-do-always 0.8.0 → 0.10.0

package/extensions/pi-do-always/index.ts

@@ -34,58 +34,102 @@
  */
 
 import { execFileSync } from "node:child_process";
-import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
-import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { appendFileSync, existsSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { join, relative } from "node:path";
+import type { ExtensionAPI, ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
 import { CONFIG_DIR_NAME, getAgentDir } from "@earendil-works/pi-coding-agent";
 import {
 	type KeyId,
 	type TuiMouseEvent,
 	type TuiMouseEventResult,
+	Container,
+	Text,
 	getKeybindings,
+	matchesKey,
 	truncateToWidth,
-	visibleWidth,
 	wrapTextWithAnsi,
 } from "@earendil-works/pi-tui";
 import {
+	CHAIN_MAX,
 	DEFAULT_SHORTCUT,
 	DEFAULT_TASKS,
+	assistantText,
+	buildTableRows,
+	chainAdd,
+	chainClear,
+	chainRemove,
+	chainRunLabel,
+	chainUndo,
+	evaluateGuards,
+	evaluateWhen,
+	formatChainSequence,
 	formatList,
 	groupTasksByCategory,
 	isValidKeyId,
 	mergeTasks,
 	parseConfig,
+	parseStatusPorcelain,
 	orderTasksByCategory,
+	reportAbandonedFooter,
+	reportFooter,
+	reportHeader,
+	reportStepSection,
+	reportWorthKeeping,
 	renderPrompt,
-	evaluateGuards,
-	evaluateWhen,
+	resolveReportPath,
 	resolveShortcut,
 	resolveTask,
 	shouldAutoRun,
+	toPromptContext,
+	validateChain,
 	type DoAlwaysTask,
-	type PromptContext,
-	type TaskGroup,
+	type TaskContext,
+	type TableRow,
 } from "./tasks";
 
+/**
+ * What the selector resolved to: a single task (the classic pick), a chain to
+ * run, or a cancel.
+ */
+type SelectorResult =
+	| { kind: "single"; task: DoAlwaysTask }
+	| { kind: "chain"; names: string[] }
+	| { kind: "cancel" };
+
+/**
+ * Selector cursor: a cell in the task table (TASK or ORDER column) or the
+ * pinned Run row.
+ */
+type Cursor = { kind: "cell"; row: number; col: "task" | "order" } | { kind: "run" };
+
 /**
  * Load tasks and the selector shortcut from config files.
- * Project-local tasks override global tasks with the same name; new ones are appended.
- * Falls back to DEFAULT_TASKS when nothing is defined.
+ * Project-local tasks override global tasks with the same name (or are
+ * appended, per the `merge` field); new ones are appended. Falls back to
+ * DEFAULT_TASKS when nothing is defined.
+ *
+ * Validation problems (malformed JSON, invalid tasks/shortcut/merge/when/
+ * guards) are reported through `onError` — callers must wire it up, since
+ * the default is a silent no-op.
  */
-function loadConfig(cwd: string): {
+function loadConfig(
+	cwd: string,
+	onError: (message: string) => void = () => {},
+): {
 	tasks: DoAlwaysTask[];
 	shortcut: string | null;
-	merge: "append" | "override";
+	/** Whether chain runs write a Markdown report file (default true). */
+	report: boolean;
 } {
 	const globalPath = join(getAgentDir(), "do-always.json");
 	const projectPath = join(cwd, CONFIG_DIR_NAME, "do-always.json");
 
 	const global = existsSync(globalPath)
-		? parseConfig(readFileSync(globalPath, "utf-8"), globalPath)
-		: { tasks: [], shortcut: undefined, merge: undefined };
+		? parseConfig(readFileSync(globalPath, "utf-8"), globalPath, onError)
+		: { tasks: [], shortcut: undefined, merge: undefined, report: undefined };
 	const project = existsSync(projectPath)
-		? parseConfig(readFileSync(projectPath, "utf-8"), projectPath)
-		: { tasks: [], shortcut: undefined, merge: undefined };
+		? parseConfig(readFileSync(projectPath, "utf-8"), projectPath, onError)
+		: { tasks: [], shortcut: undefined, merge: undefined, report: undefined };
 
 	// The project file's merge mode wins; otherwise the global value; otherwise
 	// override (the historical behavior), so existing configs are unaffected.
@@ -96,7 +140,9 @@ function loadConfig(cwd: string): {
 		// `/do-always <n>`, and `list` all share one consistent order.
 		tasks: orderTasksByCategory(mergeTasks(global.tasks, project.tasks, DEFAULT_TASKS, mode)),
 		shortcut: resolveShortcut(global.shortcut, project.shortcut),
-		merge: mode,
+		// The project file's value wins; otherwise the global value; otherwise
+		// reports are on.
+		report: project.report ?? global.report ?? true,
 	};
 }
 
@@ -120,67 +166,96 @@ function git(cwd: string, args: string[]): string | undefined {
 	}
 }
 
-/** Max number of file paths listed in `files_changed` (the count stays exact). */
-const MAX_FILES_LISTED = 20;
+/**
+ * Cache that deduplicates `buildContext` calls for the same cwd within a
+ * single user action (chain run, /do-always invocation, session_start).
+ * The cache is created fresh for each action entry point.
+ */
+function createContextCache(): {
+	get(cwd: string): TaskContext;
+} {
+	let cached: { cwd: string; ctx: TaskContext } | null = null;
+	return {
+		get(cwd: string): TaskContext {
+			if (cached && cached.cwd === cwd) return cached.ctx;
+			cached = { cwd, ctx: buildContext(cwd) };
+			return cached.ctx;
+		},
+	};
+}
 
 /**
- * Build the prompt context for `renderPrompt`. Always contains every
- * PROMPT_CONTEXT_KEYS entry: git facts fall back to neutral values when
- * unavailable (non-git dir, no git, empty repo) so default prompts read
- * cleanly in any directory.
+ * Build the structured context for the current directory. Git facts fall back
+ * to neutral values when unavailable (non-git dir, no git, empty repo) so
+ * default prompts read cleanly in any directory.
+ *
+ * Batches the 9 individual git calls into 5:
+ *  1. rev-parse --abbrev-ref HEAD --is-inside-work-tree → branch + isGitRepo
+ *  2. log -1 --format="%H %s" → commit hash + subject
+ *  3. config --get-regexp "^user.name$|^remote.origin.url$" → user + remote
+ *  4. status --porcelain → stagedFiles + unstagedFiles (parsed from porcelain)
+ *  5. diff --shortstat → diffStat
  */
-function buildContext(cwd: string): PromptContext {
-	const branch = git(cwd, ["rev-parse", "--abbrev-ref", "HEAD"]) ?? "unknown";
-	const lastCommit = git(cwd, ["log", "-1", "--format=%s"]) ?? "unknown";
-	const user = git(cwd, ["config", "user.name"]) ?? "unknown";
-
-	// repo = bare name of the git remote (owner/repo.git -> repo), falling back
-	// to the basename of cwd so monorepo work stays disambiguated everywhere.
-	const remoteUrl = git(cwd, ["config", "--get", "remote.origin.url"]);
+function buildContext(cwd: string): TaskContext {
+	// 1. Branch + isGitRepo in one call.
+	//    rev-parse --abbrev-ref HEAD --is-inside-work-tree outputs two lines:
+	//      <branch-name>
+	//      true|false
+	//    Fails (exit != 0) when not in a work tree.
+	const revParse = git(cwd, ["rev-parse", "--abbrev-ref", "HEAD", "--is-inside-work-tree"]);
+	const lines = revParse ? revParse.split("\n") : [];
+	const branch = lines[0] ?? "unknown";
+	const isGitRepo = lines[1] === "true";
+
+	// 2. Commit subject (hash is unused but cheap to fetch alongside).
+	const commitLine = isGitRepo ? git(cwd, ["log", "-1", "--format=%H %s"]) : undefined;
+	const lastCommit = commitLine ? commitLine.split(" ", 2).pop() ?? "unknown" : "unknown";
+
+	// 3. User + remote in one config call.
+	const user = isGitRepo ? git(cwd, ["config", "--get-regexp", "^user\\.name$"]) : undefined;
+	const remoteUrl = isGitRepo ? git(cwd, ["config", "--get-regexp", "^remote\\.origin\\.url$"]) : undefined;
 	const repo = remoteUrl
 		? (remoteUrl.replace(/\.git$/, "").split("/").pop() ?? "unknown")
 		: cwd.split(/[\\/]/).filter(Boolean).pop() ?? "unknown";
 
-	const files: string[] = [];
-	const status = git(cwd, ["status", "--porcelain"]);
-	if (status) {
-		for (const line of status.split("\n")) {
-			// Porcelain v1 lines are "XY <path>" (X = index, Y = worktree).
-			if (line.length < 4) continue;
-			const path = line.slice(3);
-			if (path && !files.includes(path)) files.push(path);
+	// 4. status --porcelain gives staged + unstaged in one call.
+	//    Lines starting with a space are unstaged; others are staged/untracked.
+	const porcelain = isGitRepo ? git(cwd, ["status", "--porcelain"]) : "";
+	const stagedFiles: string[] = [];
+	const unstagedFiles: string[] = [];
+	const fileSet = new Set<string>();
+	if (porcelain) {
+		for (const line of porcelain.split("\n")) {
+			if (line.length < 2) continue;
+			const file = line.slice(2);
+			if (fileSet.has(file)) continue; // deduplicate
+			fileSet.add(file);
+			if (line[0] === " ") {
+				unstagedFiles.push(file);
+			} else {
+				stagedFiles.push(file);
+			}
 		}
-		files.sort();
-	}
-	let listed: string;
-	if (files.length === 0) {
-		listed = "none";
-	} else if (files.length > MAX_FILES_LISTED) {
-		listed = [...files.slice(0, MAX_FILES_LISTED), `… (+${files.length - MAX_FILES_LISTED} more)`].join(", ");
-	} else {
-		listed = files.join(", ");
 	}
 
+	// 5. diff --shortstat.
+	const diffStat = isGitRepo ? git(cwd, ["diff", "--shortstat"]) : undefined;
+
 	return {
 		cwd,
 		date: new Date().toLocaleDateString("en-CA"), // local YYYY-MM-DD
 		branch,
-		last_commit: lastCommit,
-		files_changed: listed,
-		files_changed_count: String(files.length),
-		user,
-		diff_stat: git(cwd, ["diff", "--shortstat"]) ?? "none",
+		lastCommit,
+		files: parseStatusPorcelain(porcelain ?? ""),
+		user: user ?? "unknown",
+		diffStat: diffStat ?? "none",
 		repo,
-		staged_files: git(cwd, ["diff", "--cached", "--name-only"]) ?? "none",
-		unstaged_files: git(cwd, ["diff", "--name-only"]) ?? "none",
+		stagedFiles,
+		unstagedFiles,
+		isGitRepo,
 	};
 }
 
-/** Find the group (among `groups`) that contains a task. */
-function findGroupOf(task: DoAlwaysTask, groups: TaskGroup[]): TaskGroup | undefined {
-	return groups.find((g) => g.items.includes(task));
-}
-
 /** True for a single printable ASCII character (used for filter typing). */
 function isPrintable(data: string): boolean {
 	return data.length === 1 && data >= " " && data <= "~";
@@ -191,28 +266,450 @@ const PREVIEW_DELAY_MS = 2000;
 /** Max lines of the prompt shown in the selector preview. */
 const PREVIEW_MAX_LINES = 3;
 
+/** Outcome of one chain step's run (see sendAndWait). */
+type ChainStepOutcome = "completed" | "aborted" | "error" | "failed-to-start";
+
+/**
+ * Status of one chain step for the below-prompt status widget: pending
+ * (not reached yet), running (its turn is in flight), waiting (fill-first:
+ * step 1 is in the editor, waiting for the user's Enter), completed, or one
+ * of the stop outcomes (failed-to-start/aborted/error/skipped-by-guards).
+ */
+type ChainStepStatus =
+	| "pending"
+	| "running"
+	| "waiting"
+	| "completed"
+	| "failed-to-start"
+	| "aborted"
+	| "error"
+	| "skipped";
+
+interface ChainStepView {
+	name: string;
+	status: ChainStepStatus;
+}
+
 export default function doAlwaysExtension(pi: ExtensionAPI) {
 	let tasks: DoAlwaysTask[] = [];
 	let loadedCwd = ""; // cwd the cached `tasks` were loaded for
+	// The visible (when-filtered) list for the last context we built, so
+	// argument completions number tasks the same way the selector and
+	// `/do-always <n>` do. When stale (or absent), completions fall back to
+	// the full list rather than guessing.
+	let visibleCache: { cwd: string; visible: DoAlwaysTask[] } | null = null;
+
+	// Chain control: `pi.sendUserMessage` is fire-and-forget (returns void),
+	// so the chain runner sequences steps on session events:
+	//   agent_start   — the run actually began. A send that fails before the
+	//                   run starts (no API key, compaction collision) never
+	//                   emits agent events and its error is swallowed by the
+	//                   runtime; the grace timer in sendAndWait turns that
+	//                   into "failed-to-start".
+	//   agent_end     — carries the run's messages; the last assistant
+	//                   message's stopReason gives completed/aborted/error.
+	//   agent_settled — the session is fully idle (the busy flag is cleared
+	//                   before this fires), so the next step can be sent
+	//                   safely; auto-retry, compaction, and queued
+	//                   continuations have all had their chance.
+	let chainWaiter: {
+		started: boolean;
+		outcome: "completed" | "aborted" | "error" | null;
+		timer: NodeJS.Timeout | null;
+		resolve: (outcome: ChainStepOutcome) => void;
+		/** Which chain step (0-based) this waiter belongs to — for the report. */
+		stepIndex: number;
+	} | null = null;
+
+	function settleChainWaiter(outcome: ChainStepOutcome) {
+		if (!chainWaiter) return;
+		const waiter = chainWaiter;
+		chainWaiter = null;
+		if (waiter.timer) clearTimeout(waiter.timer);
+		waiter.resolve(outcome);
+	}
+
+	// Below-prompt status widget while a chain is running: the chain's tasks
+	// with per-step status and a (n/N) progress marker. Shown in TUI mode
+	// only; cleared when the chain completes, kept (as a trace) when it stops
+	// early, and reset on session start.
+	let chainStatus: { steps: ChainStepView[]; note?: string } | null = null;
+	const CHAIN_WIDGET_KEY = "do-always-chain";
+	// The most recent command context, so event handlers (which carry no
+	// context of their own) can still refresh the widget.
+	let lastCtx: ExtensionContext | null = null;
+	// True while a chain's runner is in flight (from start to its final
+	// outcome). A second chain started while one is running would interleave
+	// their event waiters (the old chain's sendAndWait would resolve on the
+	// new chain's step), so starting one is refused until the first ends.
+	let chainActive = false;
+	// Whether chain runs write a Markdown report file (config `report`,
+	// default true). Refreshed whenever the config is (re)loaded.
+	let reportEnabled = true;
+	// The in-flight chain's report file: its path (absolute + relative for
+	// display), when the current step's run actually started (agent_start;
+	// null until then and for failed-to-start steps), whether the footer has
+	// been appended, the index of the last step section written (dedupes
+	// retried runs), and whether any step section carried result text (the
+	// file is worth keeping).
+	let chainReport: {
+		path: string;
+		display: string;
+		stepStartedAt: Date | null;
+		/** True once the summary (or abandoned) footer has been appended. */
+		footerWritten: boolean;
+		/** Index of the last step whose section was appended (-1 = none). */
+		lastStepSection: number;
+		/** True once a step section with result text was appended. */
+		hasContent: boolean;
+		/** In-memory section data for inline display (populated in agent_end). */
+		sections: Array<{ name: string; outcome: string; text: string }>;
+	} | null = null;
+
+	/** Status marker glyph (all one column wide) with its color. */
+	function stepMarker(status: ChainStepStatus, theme: Theme): string {
+		switch (status) {
+			case "completed":
+				return theme.fg("success", "✓");
+			case "running":
+				return theme.fg("accent", theme.bold("▶"));
+			case "waiting":
+				return theme.fg("warning", "▶");
+			case "aborted":
+				return theme.fg("warning", "⊘");
+			case "error":
+			case "failed-to-start":
+				return theme.fg("error", "✗");
+			case "skipped":
+				return theme.fg("muted", "–");
+			default:
+				return theme.fg("dim", "○");
+		}
+	}
+
+	/** Replace the chain status and refresh the widget. */
+	function showChainStatus(ctx: ExtensionContext, steps: ChainStepView[], note?: string): void {
+		chainStatus = { steps, note };
+		updateChainWidget(ctx);
+	}
+
+	/** Update one step's status (and optionally the note) and refresh. */
+	function setChainStep(ctx: ExtensionContext, index: number, status: ChainStepStatus, note?: string): void {
+		if (!chainStatus) return;
+		const s = chainStatus.steps[index];
+		if (s) s.status = status;
+		if (note !== undefined) chainStatus.note = note;
+		updateChainWidget(ctx);
+	}
+
+	/**
+	 * Mark the chain as stopped at `index` with `status`, keeping the widget
+	 * visible as a trace of where it stopped.
+	 */
+	function markChainStopped(ctx: ExtensionContext, index: number, status: ChainStepStatus, detail?: string): void {
+		const name = chainStatus?.steps[index]?.name;
+		setChainStep(
+			ctx,
+			index,
+			status,
+			`stopped at step ${index + 1}${name ? ` (${name})` : ""}${detail ? `: ${detail}` : ""}`,
+		);
+	}
+
+	/**
+	 * Finish the report file: append the summary footer. Called on every
+	 * terminal path (complete, stopped, skipped); a no-op when no report was
+	 * created (disabled or write failure). A run that produced nothing worth
+	 * keeping (no completed step, no result text) leaves no file behind — see
+	 * `reportWorthKeeping`. When the chain completed fully (all steps done),
+	 * removes the status widget so nothing lingers below the prompt; otherwise
+	 * keeps it as a trace with the report path in the note.
+	 */
+	function finishReport(ctx: ExtensionContext): void {
+		if (!chainReport || !chainStatus) return;
+		const statuses = chainStatus.steps.map((s) => s.status);
+		// Nothing worth keeping — remove the (mostly) empty file so a quick
+		// same-minute retry doesn't get a -N sibling next to it.
+		if (!reportWorthKeeping(statuses, chainReport.hasContent)) {
+			closeAbandonedReport(statuses);
+			chainReport = null;
+			return;
+		}
+		try {
+			appendFileSync(chainReport.path, reportFooter(statuses, new Date()));
+			chainReport.footerWritten = true;
+		} catch (err) {
+			ctx.ui.notify(`do-always: could not update the report file: ${err}`, "warning");
+		}
+		const prev = chainStatus.note ? `${chainStatus.note} • ` : "";
+		chainStatus.note = `${prev}📄 ${chainReport.display}`;
+		// Chain fully done → show inline report above editor, then clear the
+		// trace widget. Chain stopped early → keep the trace widget.
+		const allDone = statuses.every((s) => s === "completed");
+		if (allDone) {
+			showInlineReport();
+			clearChainWidget(ctx);
+		} else {
+			updateChainWidget(ctx);
+		}
+	}
+
+	/**
+	 * Send the full chain report as a markdown message in the chat when a chain
+	 * completes. Built from in-memory section data (no file read needed).
+	 * Auto-cleared on the next agent_start / session_start.
+	 */
+	function showInlineReport(): void {
+		if (!chainReport || !chainStatus || chainReport.sections.length === 0) return;
+		// Reconstruct the full markdown report from in-memory sections.
+		const lines: string[] = [];
+		lines.push(`# do-always chain report — ${new Date().toISOString().slice(0, 10)}`);
+		lines.push("");
+		lines.push(`- Project: ${chainReport.display}`);
+		lines.push(`- Steps: ${chainStatus.steps.map((s) => s.name).join(" → ")}`);
+		lines.push("");
+		for (const sec of chainReport.sections) {
+			const section = reportStepSection(
+				0, // index not meaningful for display
+				sec.name,
+				sec.outcome,
+				new Date(), // approximate start
+				new Date(), // approximate end
+				sec.text,
+			);
+			lines.push(section);
+			lines.push("");
+		}
+		// Footer.
+		const statuses = chainStatus.steps.map((s) => s.status);
+		lines.push(reportFooter(statuses, new Date()));
+
+		// Send as a markdown message in the chat (renders as markdown, not plain text).
+		pi.sendMessage({
+			customType: "do-always-report",
+			content: lines.join("\n"),
+			display: true,
+			details: chainReport.display,
+		});
+	}
+
+	/**
+	 * Close an in-flight report that never reached a terminal path (e.g.,
+	 * the session ended mid-chain): delete the file when the run produced
+	 * nothing worth keeping, otherwise append an "abandoned" footer so it
+	 * does not stay header-only on disk.
+	 */
+	function closeAbandonedReport(statuses: string[]): void {
+		if (!chainReport || chainReport.footerWritten) return;
+		if (!reportWorthKeeping(statuses, chainReport.hasContent)) {
+			// Nothing worth keeping — remove the (mostly) empty file.
+			try {
+				unlinkSync(chainReport.path);
+			} catch {
+				// Best effort — the file stays on disk.
+			}
+			return;
+		}
+		try {
+			appendFileSync(chainReport.path, reportAbandonedFooter(statuses, new Date()));
+		} catch {
+			// Best effort — the report file stays as-is on disk.
+		}
+	}
+
+	/**
+	 * Remove the widget and forget the status (and any in-flight report).
+	 * When the report never reached a terminal path (e.g., the session
+	 * ended mid-chain), it is closed by `closeAbandonedReport`.
+	 */
+	function clearChainWidget(ctx: ExtensionContext): void {
+		if (!chainStatus) return;
+		const statuses = chainStatus.steps.map((s) => s.status);
+		chainStatus = null;
+		closeAbandonedReport(statuses);
+		chainReport = null;
+		if (ctx.mode === "tui") ctx.ui.setWidget(CHAIN_WIDGET_KEY, undefined);
+	}
+
+	/**
+	 * Render the status widget from `chainStatus` (TUI only): the chain's
+	 * steps with per-step markers, a (n/N) progress line, and the note,
+	 * below the editor. Refreshed on every step change; removed by
+	 * `clearChainWidget` when the chain completes or a new prompt starts.
+	 */
+	function updateChainWidget(ctx: ExtensionContext): void {
+		if (ctx.mode !== "tui" || !chainStatus) return;
+		const { steps, note } = chainStatus;
+
+		// Chain status widget: stays below the editor.
+		ctx.ui.setWidget(
+			CHAIN_WIDGET_KEY,
+			(tui, theme) => {
+				const lines: string[] = [];
+				// (n/N): the step the chain is currently at (N when it is done).
+				let at = 0;
+				steps.forEach((s, i) => {
+					if (s.status !== "pending") at = i + 1;
+				});
+				lines.push(theme.fg("accent", theme.bold(`⛓ do-always (${at}/${steps.length})`)));
+				for (const s of steps) {
+					lines.push(`  ${stepMarker(s.status, theme)} ${s.name}`);
+				}
+				if (note) lines.push(theme.fg("muted", truncateToWidth(`  ${note}`, tui.terminal.columns - 2, "…")));
+				const container = new Container();
+				for (const line of lines) container.addChild(new Text(line, 1, 0));
+				return container;
+			},
+			{ placement: "belowEditor" },
+		);
+	}
+
+	pi.on("agent_start", () => {
+		if (chainWaiter) chainWaiter.started = true;
+		// The run actually began — time the step for the report.
+		if (chainReport) chainReport.stepStartedAt = new Date();
+		// Fill-first: step 1 left the editor and is running — update the
+		// widget (and drop the "press Enter" note) as soon as the run starts.
+		if (lastCtx && chainStatus?.steps[0]?.status === "waiting") {
+			setChainStep(lastCtx, 0, "running", "");
+		}
+		// User entered a new prompt and the old chain is no longer active —
+		// clear the trace widget so nothing lingers below the prompt.
+		if (!chainActive && chainStatus && lastCtx) {
+			clearChainWidget(lastCtx);
+		}
+	});
+	pi.on("agent_end", (event) => {
+		if (!chainWaiter) return;
+		const lastAssistant = [...event.messages].reverse().find((m) => m.role === "assistant");
+		if (lastAssistant) {
+			const stopReason = lastAssistant.stopReason;
+			const outcome = stopReason === "aborted" ? "aborted" : stopReason === "error" ? "error" : "completed";
+			chainWaiter.outcome = outcome;
+			// Append this step's result to the report while the transcript is
+			// fresh (the step's final assistant message is its result).
+			if (chainReport && chainStatus) {
+				const idx = chainWaiter.stepIndex;
+				// A retried/continued run emits a second agent_end for the
+				// same step before agent_settled — mark the repeat so the
+				// report shows both attempts without a duplicate heading.
+				const isRetry = chainReport.lastStepSection === idx;
+				const name = chainStatus.steps[idx]?.name ?? `step ${idx + 1}`;
+				const text = assistantText(lastAssistant.content);
+				const section = reportStepSection(
+					idx,
+					isRetry ? `${name} (retry)` : name,
+					outcome,
+					chainReport.stepStartedAt,
+					new Date(),
+					text,
+				);
+				try {
+					appendFileSync(chainReport.path, section);
+					chainReport.lastStepSection = idx;
+					if (text.trim() !== "") chainReport.hasContent = true;
+					// Keep in-memory section data for inline display.
+					chainReport.sections.push({ name, outcome, text });
+				} catch (err) {
+					lastCtx?.ui.notify(`do-always: could not update the report file: ${err}`, "warning");
+				}
+				chainReport.stepStartedAt = null;
+			}
+		}
+	});
+	pi.on("agent_settled", () => {
+		if (!chainWaiter) return;
+		settleChainWaiter(chainWaiter.started ? (chainWaiter.outcome ?? "completed") : "failed-to-start");
+	});
+
+	/**
+	 * Arm the chain waiter and resolve when the next run has fully settled
+	 * (agent_settled), reporting that run's outcome. With `graceMs`, resolves
+	 * "failed-to-start" if no agent_start arrives in time — a send that
+	 * throws before the run begins emits no agent events and its error is
+	 * swallowed by the runtime. `stepIndex` tags the waiter so the report
+	 * knows which chain step the run belongs to.
+	 */
+	function armWaiter(graceMs?: number, stepIndex = 0): Promise<ChainStepOutcome> {
+		return new Promise((resolve) => {
+			const timer = graceMs
+				? setTimeout(() => {
+						if (chainWaiter && !chainWaiter.started) settleChainWaiter("failed-to-start");
+					}, graceMs)
+				: null;
+			chainWaiter = { started: false, outcome: null, timer, resolve, stepIndex };
+		});
+	}
+
+	/**
+	 * Send a prompt and resolve when the run it starts has fully settled,
+	 * reporting the run's outcome (see armWaiter).
+	 */
+	function sendAndWait(prompt: string, graceMs = 10_000, stepIndex = 0): Promise<ChainStepOutcome> {
+		const done = armWaiter(graceMs, stepIndex);
+		pi.sendUserMessage(prompt);
+		return done;
+	}
+
+	/** Filter tasks by their `when` condition and refresh the completion cache. */
+	function refreshVisible(cwd: string, context: TaskContext): DoAlwaysTask[] {
+		const visible = tasks.filter((t) => evaluateWhen(t, context));
+		visibleCache = { cwd, visible };
+		return visible;
+	}
+
+	/**
+	 * Register the selector shortcut from a resolved config value (null
+	 * disables it). Called from session_start so it reads the session's cwd,
+	 * not the process cwd; re-registering the same key is idempotent.
+	 */
+	function registerShortcut(shortcut: string | null, onError: (message: string) => void): void {
+		if (shortcut === null) return;
+		const shortcutKey = isValidKeyId(shortcut) ? shortcut : DEFAULT_SHORTCUT;
+		if (shortcutKey !== shortcut) {
+			onError(`do-always: invalid shortcut "${shortcut}" in do-always.json — using ${DEFAULT_SHORTCUT}`);
+		}
+		pi.registerShortcut(shortcutKey as KeyId, {
+			description: "do-always: pick a common task",
+			handler: async (ctx) => {
+				await runDoAlways("", ctx);
+			},
+		});
+	}
 
-	pi.on("session_start", async (_event, ctx) => {
+	pi.on("session_start", (_event, ctx) => {
+		lastCtx = ctx;
+		// Surface config validation problems (the README promises warnings);
+		// in non-TUI modes there is no UI, so fall back to the console.
+		const onError = (m: string) => {
+			if (ctx.mode === "tui") ctx.ui.notify(m, "warning");
+			else console.warn(m);
+		};
+		// A failed chain's status widget is a trace of the previous session;
+		// start each session clean.
+		clearChainWidget(ctx);
 		loadedCwd = ctx.cwd;
-		tasks = loadConfig(ctx.cwd).tasks;
+		const config = loadConfig(ctx.cwd, onError);
+		tasks = config.tasks;
+		reportEnabled = config.report;
+		refreshVisible(ctx.cwd, buildContext(ctx.cwd));
+		registerShortcut(config.shortcut, onError);
 	});
 
 	/** Put the task prompt into the editor (TUI) or send it as a user message (other modes). */
-	async function fillPrompt(task: DoAlwaysTask, ctx: ExtensionContext): Promise<void> {
-		// Render the prompt with the current context (branch, changed files, …)
-		// so the injected text matches this directory at this moment.
-		const context = buildContext(ctx.cwd);
+	async function fillPrompt(task: DoAlwaysTask, ctx: ExtensionContext, context: TaskContext): Promise<void> {
 		const blocked = evaluateGuards(task, context);
 		if (blocked) {
 			ctx.ui.notify(`do-always: ${blocked}`, "info");
 			return;
 		}
-		const prompt = renderPrompt(task.prompt, context);
+		// Render with the same context the selector/preview used, so what the
+		// user saw is exactly what gets injected.
+		const prompt = renderPrompt(task.prompt, toPromptContext(context));
 		if (shouldAutoRun(task)) {
-			await pi.sendUserMessage(prompt);
+			// Fire-and-forget: sendUserMessage returns void; the run proceeds
+			// independently (see the chain control notes for why).
+			pi.sendUserMessage(prompt);
 			ctx.ui.notify(`do-always: auto-ran "${task.name}"`, "info");
 			return;
 		}
@@ -220,23 +717,192 @@ export default function doAlwaysExtension(pi: ExtensionAPI) {
 			ctx.ui.setEditorText(prompt);
 			ctx.ui.notify(`do-always: prompt for "${task.name}" filled — press Enter to run`, "info");
 		} else {
-			await pi.sendUserMessage(prompt);
+			pi.sendUserMessage(prompt);
+		}
+	}
+
+	/**
+	 * Run a chain: each step is sent as its own turn, awaited in order, so the
+	 * steps run strictly one after another. Aborting (or erroring) a step
+	 * stops the chain.
+	 *
+	 * Step 1 follows the task's autoRun semantics: ⚡ tasks (and non-TUI modes)
+	 * are sent immediately; fill tasks put step 1 in the editor and wait for
+	 * its run to settle before starting the remaining steps.
+	 */
+	async function runChain(
+		names: string[],
+		ctx: ExtensionContext,
+		cache: ReturnType<typeof createContextCache>,
+	): Promise<void> {
+		if (chainActive) {
+			ctx.ui.notify("do-always: a chain is already running — wait for it to finish (or abort the current step with Esc)", "info");
+			return;
+		}
+		const steps = names
+			.map((n) => tasks.find((t) => t.name === n))
+			.filter((t): t is DoAlwaysTask => t !== undefined);
+		if (steps.length === 0) {
+			ctx.ui.notify("do-always: nothing to run", "info");
+			return;
+		}
+		// Fail fast: report the first blocked step before sending anything.
+		const blocked = validateChain(tasks, { items: names, history: [] }, cache.get(ctx.cwd));
+		if (blocked) {
+			ctx.ui.notify(`do-always: chain blocked at step ${blocked.step} (${blocked.task.name}): ${blocked.message}`, "warning");
+			return;
+		}
+		chainActive = true;
+		// Report file: one per run, in the project root, appended as each step
+		// finishes (see the report section in tasks.ts). A write failure is not
+		// fatal — the chain still runs, just without a report.
+		if (reportEnabled) {
+			const now = new Date();
+			const path = resolveReportPath(ctx.cwd, now);
+			try {
+				writeFileSync(path, reportHeader(ctx.cwd, steps.map((t) => t.name), now));
+				chainReport = {
+					path,
+					display: relative(ctx.cwd, path),
+					stepStartedAt: null,
+					footerWritten: false,
+					lastStepSection: -1,
+					hasContent: false,
+					sections: [],
+				};
+			} catch (err) {
+				ctx.ui.notify(`do-always: could not create the report file: ${err}`, "warning");
+				chainReport = null;
+			}
+		}
+		const first = steps[0];
+		if (shouldAutoRun(first) || ctx.mode !== "tui") {
+			try {
+				showChainStatus(
+					ctx,
+					steps.map((t, i) => ({ name: t.name, status: i === 0 ? "running" : "pending" })),
+				);
+				await runChainSteps(steps, ctx, 0, cache);
+			} finally {
+				chainActive = false;
+			}
+			return;
+		}
+		// Fill-first: put step 1 in the editor; the remaining steps start once
+		// step 1's run has settled successfully. No grace timer — the user
+		// takes as long as they need to press Enter. (If the user runs an
+		// unrelated prompt instead, the chain continues after it, as the
+		// notification says.)
+		showChainStatus(
+			ctx,
+			steps.map((t, i) => ({ name: t.name, status: i === 0 ? "waiting" : "pending" })),
+			"step 1 is in the editor — press Enter to start",
+		);
+		ctx.ui.setEditorText(renderPrompt(first.prompt, toPromptContext(cache.get(ctx.cwd))));
+		ctx.ui.notify(
+			`do-always: step 1 of ${steps.length} in the editor — press Enter to run; steps 2–${steps.length} follow automatically`,
+			"info",
+		);
+		void armWaiter(undefined, 0).then(async (outcome) => {
+			try {
+				if (outcome !== "completed") {
+					markChainStopped(ctx, 0, outcome);
+					finishReport(ctx);
+					ctx.ui.notify(`do-always: step 1 — ${outcome}; chain stopped`, "error");
+					return;
+				}
+				setChainStep(ctx, 0, "completed");
+				await runChainSteps(steps, ctx, 1, cache);
+			} finally {
+				chainActive = false;
+			}
+		});
+	}
+
+	/**
+	 * Send chain steps `startAt..end` sequentially. Each step gets a fresh
+	 * context (so its guards see the tree as it is now) and is awaited until
+	 * its run has fully settled; an aborted/errored step (or a send that
+	 * failed to start) stops the chain.
+	 */
+	async function runChainSteps(
+		steps: DoAlwaysTask[],
+		ctx: ExtensionContext,
+		startAt: number,
+		cache: ReturnType<typeof createContextCache>,
+	): Promise<void> {
+		for (let i = startAt; i < steps.length; i++) {
+			const step = steps[i];
+			const context = cache.get(ctx.cwd);
+			const blocked = evaluateGuards(step, context);
+			if (blocked) {
+				markChainStopped(ctx, i, "skipped", blocked);
+				finishReport(ctx);
+				ctx.ui.notify(`do-always: chain stopped at step ${i + 1} (${step.name}): ${blocked}`, "warning");
+				return;
+			}
+			const prompt = renderPrompt(step.prompt, toPromptContext(context));
+			const label = `do-always: step ${i + 1}/${steps.length} — ${step.name}`;
+			setChainStep(ctx, i, "running");
+			ctx.ui.notify(`${label} — starting`, "info");
+			const outcome = await sendAndWait(prompt, 10_000, i);
+			if (outcome === "completed") {
+				setChainStep(ctx, i, "completed");
+				continue;
+			}
+			markChainStopped(ctx, i, outcome);
+			finishReport(ctx);
+			if (outcome === "failed-to-start") {
+				ctx.ui.notify(`${label} — failed to start (check model/API key); chain stopped`, "error");
+			} else if (outcome === "aborted") {
+				ctx.ui.notify(`${label} — aborted; chain stopped`, "error");
+			} else {
+				ctx.ui.notify(`${label} — run errored; chain stopped`, "error");
+			}
+			return;
+		}
+		// Complete: the report file holds the full results of every step;
+		// finishReport clears the status widget so nothing lingers below
+		// the prompt. Capture the display path first — finishReport clears
+		// `chainReport` when the chain is fully done.
+		const reportDisplay = chainReport?.display;
+		if (chainReport) {
+			finishReport(ctx);
+			ctx.ui.notify(`do-always: chain complete (${steps.length} steps) — report: ${reportDisplay}`, "info");
+		} else {
+			clearChainWidget(ctx);
+			ctx.ui.notify(`do-always: chain complete (${steps.length} steps)`, "info");
 		}
 	}
 
 	/**
-	 * Numbered selector with categorized sections. Press 1-9 to pick by global
-	 * number, type to filter, or navigate with arrows + Enter, Esc to cancel.
+	 * Task table with an ORDER column (the chain) and a pinned Run row:
+	 *
+	 *   #  TASK                  DESCRIPTION              ORDER
+	 *   1  ⚡ Review changes      Review the current       ►[1]
+	 *   2  Build                 Build the project          ·
+	 *   ─────────────────────────────────────────────────────
+	 *   Run the chain (1)
+	 *
+	 * The TASK column is primary: Enter runs just the task under the cursor
+	 * (the classic pick). The ORDER column is the optional chain: Enter
+	 * toggles the task's membership, and the pinned Run row runs the whole
+	 * chain. ←/→ switch columns, 1-9 still runs a task immediately (closing
+	 * the selector, discarding the chain). The context is built once per command
+	 * run (never inside the render loop — no process spawning per frame) and
+	 * shared with `fillPrompt`.
 	 */
-	async function showSelector(ctx: ExtensionContext): Promise<void> {
-		// Build the context once per selector session (never inside the render
-		// loop — no process spawning per frame). fillPrompt re-renders at
-		// selection time, so a few seconds of drift is acceptable.
-		const context = buildContext(ctx.cwd);
+	async function showSelector(
+		ctx: ExtensionContext,
+		context: TaskContext,
+		cache: ReturnType<typeof createContextCache>,
+	): Promise<void> {
 		// Filter by the `when` condition once per session, so hidden tasks never
 		// appear, are never numbered, and can't be picked.
 		const visibleTasks = tasks.filter((t) => evaluateWhen(t, context));
-		const selected = await ctx.ui.custom<number | null>((tui, theme, _kb, done) => {
+		// String view for prompt rendering (derived once, used by the preview).
+		const strings = toPromptContext(context);
+		const result = await ctx.ui.custom<SelectorResult>((tui, theme, _kb, done) => {
 			let settled = false;
 			let previewVisible = false;
 			let previewTimer: ReturnType<typeof setTimeout> | null = null;
@@ -248,16 +914,28 @@ export default function doAlwaysExtension(pi: ExtensionAPI) {
 				}
 			}
 
-			// `finish` receives the chosen task (or null) and translates it to the
-			// full index `tasks[selected]` expects. Reference-based, so it stays
-			// correct while a text filter is active (itemRows is then a subset of
-			// visibleTasks and positional indices would point at the wrong task).
-			const finish = (task: DoAlwaysTask | null) => {
+			// Finish the selector with a result. Reference-based (task object /
+			// chain names), so it stays correct while a text filter is active
+			// (itemRows is then a subset of visibleTasks and positional indices
+			// would point at the wrong task).
+			function finishSingle(task: DoAlwaysTask) {
 				if (settled) return;
 				settled = true;
 				clearPreviewTimer();
-				done(task ? tasks.indexOf(task) : null);
-			};
+				done({ kind: "single", task });
+			}
+			function finishChain(names: string[]) {
+				if (settled) return;
+				settled = true;
+				clearPreviewTimer();
+				done({ kind: "chain", names });
+			}
+			function finishCancel() {
+				if (settled) return;
+				settled = true;
+				clearPreviewTimer();
+				done({ kind: "cancel" });
+			}
 
 			// The prompt preview appears only after the selection has been stable
 			// for PREVIEW_DELAY_MS; any change hides it and restarts the delay.
@@ -279,7 +957,9 @@ export default function doAlwaysExtension(pi: ExtensionAPI) {
 			const kb = getKeybindings();
 			const maxVisible = 12;
 			let filter = "";
-			let selectedIndex = 0;
+			let chain = chainClear();
+			let cursor: Cursor = { kind: "cell", row: 0, col: "task" };
+			let lastCellRow = 0;
 			let mousePressedIndex: number | null = null;
 
 			// Arm the preview timer for the initial selection.
@@ -295,93 +975,196 @@ export default function doAlwaysExtension(pi: ExtensionAPI) {
 				);
 			};
 
-			// Recompute the visible (filtered, grouped) rows on every render so
-			// filter typing updates the list live.
+			// Recompute the visible (filtered) table rows on every render so
+			// filter typing and chain edits update the table live.
 			function getVisible() {
-				const visibleGroups = groups
-					.map((g) => ({ name: g.name, items: g.items.filter(matchesFilter) }))
-					.filter((g) => g.items.length > 0);
-				const rows: Array<
-					| { kind: "header"; name: string }
-					| { kind: "item"; task: DoAlwaysTask; group: string }
-				> = [];
-				for (const g of visibleGroups) {
-					rows.push({ kind: "header", name: g.name });
-					for (const t of g.items) rows.push({ kind: "item", task: t, group: g.name });
+				const filteredGroups = groups.map((g) => ({ name: g.name, items: g.items.filter(matchesFilter) }));
+				const tableRows = buildTableRows(filteredGroups, chain);
+				const bodyRows: TableRow[] = [];
+				const itemRows: { task: DoAlwaysTask; globalIndex: number; order?: number }[] = [];
+				// O(n) index map so indexOf → O(1) lookup.
+				const taskToGlobalIndex = new Map(visibleTasks.map((t, i) => [t, i]));
+				for (const r of tableRows) {
+					if (r.kind === "run") continue; // pinned row, rendered separately
+					bodyRows.push(r);
+					if (r.kind === "task" && r.task) {
+						itemRows.push({ task: r.task, globalIndex: taskToGlobalIndex.get(r.task) ?? -1, order: r.order });
+					}
 				}
-				const itemRows = rows.filter((r): r is (typeof rows)[number] & { kind: "item" } => r.kind === "item");
-				// Clamp selection to the visible item count.
-				selectedIndex = Math.max(0, Math.min(selectedIndex, Math.max(0, itemRows.length - 1)));
-				// Visible item window with scrolling.
-				const winStart = Math.max(0, Math.min(selectedIndex - Math.floor(maxVisible / 2), Math.max(0, itemRows.length - maxVisible)));
-				const visibleItemKeys = new Set(itemRows.slice(winStart, winStart + maxVisible).map((r) => r.task));
-				const visibleHeaderNames = new Set([...visibleItemKeys].map((t) => findGroupOf(t, visibleGroups)?.name ?? ""));
-				return { rows, itemRows, visibleItemKeys, visibleHeaderNames };
+				// Scroll window over the filtered items.
+				const anchor = cursor.kind === "cell" ? cursor.row : lastCellRow;
+				const winStart =
+					itemRows.length > maxVisible
+						? Math.max(0, Math.min(anchor + 1 - maxVisible, itemRows.length - maxVisible))
+						: 0;
+				// Headers whose group has at least one item in the window.
+				const inWindow = new Set(itemRows.slice(winStart, winStart + maxVisible).map((r) => r.task));
+				const visibleHeaderNames = new Set(
+					filteredGroups.filter((g) => g.items.some((t) => inWindow.has(t))).map((g) => g.name),
+				);
+				return { bodyRows, itemRows, winStart, visibleHeaderNames };
 			}
 
-			const labelCol = 26;
-
-			function renderLabel(task: DoAlwaysTask, globalIndex: number, isSelected: boolean, width: number): string {
-				const prefix = isSelected ? "▸ " : "  ";
-				const marker = shouldAutoRun(task) ? "⚡ " : "";
-				const label = `${prefix}${globalIndex + 1}. ${marker}${task.name}`;
-				if (!task.description) {
-					const line = truncateToWidth(label, Math.max(1, width - 2), "");
-					return isSelected ? theme.fg("accent", theme.bold(line)) : line;
-				}
-				// Width-aware two-column layout; fall back to label-only when the
-				// terminal is too narrow to fit a description column.
-				const effCol = Math.max(1, Math.min(labelCol, width - 8));
-				const nameOnly = truncateToWidth(label, effCol, "");
-				const pad = " ".repeat(Math.max(1, effCol - visibleWidth(nameOnly)));
-				const remaining = width - visibleWidth(nameOnly) - pad.length - 2;
-				if (remaining < 10) {
-					const line = truncateToWidth(label, Math.max(1, width - 2), "");
-					return isSelected ? theme.fg("accent", theme.bold(line)) : line;
+			// Keep the cursor valid after the rows or the chain change. (The
+			// ORDER cell of a non-chained row is a valid cursor position: it is
+			// the "add" state.)
+			function clampCursor() {
+				const { itemRows } = getVisible();
+				if (itemRows.length === 0) {
+					cursor = { kind: "cell", row: 0, col: "task" };
+					return;
 				}
-				const desc = truncateToWidth(task.description, remaining, "");
-				if (isSelected) {
-					return theme.fg("accent", theme.bold(`${nameOnly}${pad}${desc}`));
+				if (cursor.kind === "cell" && cursor.row >= itemRows.length) {
+					cursor = { kind: "cell", row: itemRows.length - 1, col: "task" };
 				}
-				return `${nameOnly}${pad}${theme.fg("muted", desc)}`;
 			}
 
-			// Build the full selector output for a width, plus a map from line
-			// index to task for the item rows (used by mouse handling).
-			function buildRender(width: number) {
-				const { rows, itemRows, visibleItemKeys, visibleHeaderNames } = getVisible();
+			// --- Table geometry ---------------------------------------------------
+			// Three tiers by width:
+			//   >= 76:   # TASK DESCRIPTION ORDER
+			//   58-75:   # TASK ORDER
+			//   < 58:    # TASK   (chain shown on its own line below the list)
+			const ORDER_COL_W = 5;
+			const TASK_COL_W = 24;
+			type Tier = "full" | "compact" | "narrow";
+			function tierFor(width: number): Tier {
+				if (width >= 76) return "full";
+				if (width >= 58) return "compact";
+				return "narrow";
+			}
+			// Column geometry: [2] # [3]  [taskCol]  [descCol]  [ORDER_COL_W] [1]
+			function tableGeometry(width: number) {
+				const tier = tierFor(width);
+				const taskCol = tier === "full" ? TASK_COL_W : Math.max(10, width - 2 - 3 - 2 - 2 - ORDER_COL_W - 1);
+				const descCol = tier === "full" ? Math.max(8, width - 2 - 3 - 2 - TASK_COL_W - 2 - 2 - ORDER_COL_W - 1) : 0;
+				// The ORDER cell is the last ORDER_COL_W characters of the line
+				// (the line is width-2 chars wide), so it starts at width-2-W.
+				const orderColX = tier === "narrow" ? null : width - 2 - ORDER_COL_W;
+				return { tier, taskCol, descCol, orderColX };
+			}
+
+			// Cached last buildTable result (avoids double-work on mouse hit-test).
+			// Invalidated whenever chain/filter changes (handledInput calls
+			// requestRender, which re-renders before any subsequent mouse event).
+			let lastTable: ReturnType<typeof buildTable> | null = null;
+
+			// Build the full selector output for a width, plus the line map for
+			// mouse handling (itemLine: line -> task, runLine: the Run row,
+			// orderColX: where the ORDER cell starts, or null in the narrow tier).
+			function buildTable(width: number) {
+				const { bodyRows, itemRows, winStart, visibleHeaderNames } = getVisible();
+				const { tier, taskCol, descCol, orderColX } = tableGeometry(width);
 				const lines: string[] = [];
 				const itemLine = new Map<number, DoAlwaysTask>();
-				lines.push(theme.fg("accent", theme.bold("  do-always — pick a task")));
-				lines.push("");
+				let runLine = -1;
+				// Cursor marker: a large triangle in the accent color. The row
+				// background alone can be invisible (some themes map selectedBg
+				// to the terminal's default background), so the marker carries
+				// the cursor.
+				const cursorMark = theme.fg("accent", "►");
+
+				// Header.
+				lines.push(
+					theme.fg(
+						"muted",
+						truncateToWidth(
+							// The 6-char prefix ("   #  ") lines the header up with
+							// the body rows (2-digit number + 2 spaces).
+							tier === "full"
+								? `   #  ${"TASK".padEnd(taskCol)}  ${"DESCRIPTION".padEnd(descCol)}  ${"ORDER".padEnd(ORDER_COL_W)}`
+								: tier === "compact"
+									? `   #  ${"TASK".padEnd(taskCol)}  ${"ORDER".padEnd(ORDER_COL_W)}`
+									: "   #  TASK",
+							width - 2,
+							"",
+						),
+					),
+				);
+
 				if (itemRows.length === 0) {
 					lines.push(theme.fg("warning", "  No matching tasks"));
 				} else {
-					for (const row of rows) {
+					let itemShown = 0;
+					// O(n) index map so findIndex → O(1) lookup.
+					const idxMap = new Map(itemRows.map((x, i) => [x.task, i]));
+					for (const row of bodyRows) {
 						if (row.kind === "header") {
-							if (!visibleHeaderNames.has(row.name)) continue;
-							lines.push(theme.fg("accent", theme.bold(`  ${row.name.toUpperCase()}`)));
+							if (!visibleHeaderNames.has(row.name ?? "")) continue;
+							if (itemShown >= maxVisible) break;
+							lines.push(
+								theme.fg("accent", theme.bold(truncateToWidth(`  ${(row.name ?? "").toUpperCase()}`, width - 2, ""))),
+							);
 							continue;
 						}
-						if (!visibleItemKeys.has(row.task)) continue;
-						const globalIndex = visibleTasks.indexOf(row.task);
-						const isSelected = row.task === itemRows[selectedIndex].task;
-						lines.push(renderLabel(row.task, globalIndex, isSelected, width));
-						itemLine.set(lines.length - 1, row.task);
+						if (!row.task) continue;
+						const idx = idxMap.get(row.task);
+						if (idx === undefined || idx < winStart || idx >= winStart + maxVisible) continue;
+						itemShown++;
+						const task = row.task;
+						const auto = shouldAutoRun(task);
+						const focused = cursor.kind === "cell" && cursor.row === idx;
+						// Cursor markers: ► in the left gutter = TASK column, ► in the
+						// ORDER cell = ORDER column. The row background is applied too,
+						// but some themes map selectedBg to a color that is nearly
+						// indistinguishable from the terminal background, so the
+						// character marker is the reliable indicator.
+						const inTaskCol =
+							cursor.kind === "cell" && cursor.row === idx && cursor.col === "task";
+						const inOrderCol =
+							cursor.kind === "cell" && cursor.row === idx && cursor.col === "order";
+						const num = inTaskCol
+							? `${cursorMark} ${String(itemRows[idx].globalIndex + 1).padStart(2)}`
+							: `  ${String(itemRows[idx].globalIndex + 1).padStart(2)}`;
+						// ⚡ is 2 columns wide, so "⚡ " takes 3 — reserve it so
+						// auto-run rows align with the others (ORDER cell is
+						// hit-tested at a fixed x).
+						const name = truncateToWidth(task.name, taskCol - (auto ? 3 : 0), "…", true);
+						const taskCell = (auto ? "⚡ " : "") + name;
+						// Every ORDER cell is exactly ORDER_COL_W wide so the column
+						// stays aligned (and mouse hit-testing stays exact).
+						const orderCell =
+							row.order !== undefined
+								? inOrderCol
+									? truncateToWidth(`${cursorMark}[${row.order}]`, ORDER_COL_W, "", true)
+									: ` [${row.order}] `
+								: inOrderCol
+									? `${cursorMark}  · `
+									: "  ·  ";
+						let line: string;
+						if (tier === "full") {
+							const desc = truncateToWidth(task.description ?? "", descCol, "…", true);
+							line = `${num}  ${taskCell}  ${desc}  ${orderCell}`;
+						} else if (tier === "compact") {
+							line = `${num}  ${taskCell}  ${orderCell}`;
+						} else {
+							line = truncateToWidth(`${num}  ${taskCell}`, width - 2, "…");
+						}
+						// Full-row background + bold where the theme makes it visible;
+						// the ► gutter/cell marker carries the cursor either way.
+						if (focused) line = theme.bg("selectedBg", theme.bold(line));
+						lines.push(line);
+						itemLine.set(lines.length - 1, task);
 					}
 					if (itemRows.length > maxVisible) {
-						const hint = `  (${selectedIndex + 1}/${itemRows.length})`;
-						lines.push(theme.fg("dim", truncateToWidth(hint, width - 2, "")));
+						const anchor = cursor.kind === "cell" ? cursor.row : lastCellRow;
+						lines.push(theme.fg("dim", truncateToWidth(`  (${anchor + 1}/${itemRows.length})`, width - 2, "")));
+					}
+					// Narrow tier: the chain gets its own line instead of a column.
+					if (tier === "narrow" && chain.items.length > 0) {
+						lines.push(
+							theme.fg("dim", truncateToWidth(`  chain: ${formatChainSequence(visibleTasks, chain)}`, width - 2, "…")),
+						);
 					}
 				}
-				// Prompt preview: revealed after the selection has been stable for
-				// PREVIEW_DELAY_MS, showing exactly what will be injected.
-				if (previewVisible) {
-					const sel = itemRows[selectedIndex];
+
+				// Prompt preview: revealed after the cursor has been stable on a
+				// task row for PREVIEW_DELAY_MS, showing exactly what will be
+				// injected.
+				if (previewVisible && cursor.kind === "cell" && cursor.col === "task") {
+					const sel = itemRows[cursor.row];
 					if (sel) {
 						const wrapWidth = Math.max(10, width - 4);
-						// Show the rendered prompt — exactly what will be injected.
-						const wrapped = wrapTextWithAnsi(renderPrompt(sel.task.prompt, context), wrapWidth);
+						const wrapped = wrapTextWithAnsi(renderPrompt(sel.task.prompt, strings), wrapWidth);
 						const shown = wrapped.slice(0, PREVIEW_MAX_LINES);
 						const truncated = wrapped.length > PREVIEW_MAX_LINES;
 						lines.push("");
@@ -393,60 +1176,192 @@ export default function doAlwaysExtension(pi: ExtensionAPI) {
 						});
 					}
 				}
+
+				// Pinned Run row (always visible, outside the scroll window).
 				lines.push("");
-				const anyAutoRun = itemRows.some((r) => shouldAutoRun(r.task));
-				const footer = anyAutoRun
-					? "  1-9 pick by number  •  type to filter  •  ↑↓ navigate  •  enter select  •  esc cancel  •  ⚡ auto-runs"
-					: "  1-9 pick by number  •  type to filter  •  ↑↓ navigate  •  enter select  •  esc cancel";
+				lines.push(theme.fg("dim", "  " + "─".repeat(Math.max(1, width - 4))));
+				const runLabel = chainRunLabel(chain.items.length);
+				runLine = lines.length;
+				// No play glyph in the label: the ► cursor marker is the only
+				// ">" and it appears only while the row is selected (like task rows).
+				if (cursor.kind === "run") {
+					lines.push(theme.bg("selectedBg", theme.bold(`${cursorMark} ${runLabel}`)));
+				} else if (chain.items.length === 0) {
+					lines.push(theme.fg("dim", `  ${runLabel}`));
+				} else {
+					lines.push(theme.fg("accent", `  ${runLabel}`));
+				}
+
+				// Context-sensitive footer.
+				let footer: string;
+				if (cursor.kind === "run") {
+					footer =
+						chain.items.length > 0
+							? `  ⏎ run: ${formatChainSequence(visibleTasks, chain)}`
+							: "  ⏎ run the chain (chain is empty)";
+				} else if (cursor.col === "order") {
+					const inChain = chain.items.includes(itemRows[cursor.row]?.task.name ?? "");
+					footer = inChain ? "  ← tasks  •  ⏎ remove  •  esc" : "  ← tasks  •  ⏎ add  •  esc";
+				} else {
+					footer = "  1-9 run now  •  ⏎ select  •  → order  •  ⌫ undo  •  esc";
+				}
+				if (chain.items.length > 0 && cursor.kind !== "run") footer += "  •  ctrl+u clear";
 				lines.push(theme.fg("dim", truncateToWidth(footer, width - 2, "")));
-				return { lines, itemLine, itemRows };
+
+				return { lines, itemLine, runLine, orderColX };
 			}
 
 			return {
 				render(width: number) {
-					return buildRender(width).lines;
+					lastTable = buildTable(width);
+					return lastTable!.lines;
 				},
 				invalidate() {},
 				handleInput(data: string) {
-					// Direct pick by number (1-9) — only when not filtering, and within
-					// the visible set, so digits pick a visible task by its number.
+					// Direct pick by number (1-9) — runs the task immediately (the
+					// classic fast path), closing the selector and discarding the
+					// chain. Only when not filtering, and within the visible set,
+					// so digits pick a visible task by its number.
 					if (!filter && /^[1-9]$/.test(data) && Number(data) <= visibleTasks.length) {
-						finish(visibleTasks[Number(data) - 1]);
+						finishSingle(visibleTasks[Number(data) - 1]);
 						return;
 					}
-					// Filter typing.
+					// Filter typing (Backspace edits the filter; with an empty
+					// filter it undoes the last chain add).
 					if (kb.matches(data, "tui.editor.deleteCharBackward")) {
-						filter = filter.slice(0, -1);
-						selectedIndex = 0;
+						if (filter.length > 0) {
+							filter = filter.slice(0, -1);
+							clampCursor();
+						} else {
+							const { state, removed } = chainUndo(chain);
+							if (removed) {
+								chain = state;
+								clampCursor();
+							}
+						}
 						resetPreview();
 						tui.requestRender();
 						return;
 					}
 					if (isPrintable(data)) {
 						filter += data;
-						selectedIndex = 0;
+						clampCursor();
 						resetPreview();
 						tui.requestRender();
 						return;
 					}
-					// Navigation / confirmation.
 					const { itemRows } = getVisible();
+					if (itemRows.length === 0) {
+						// Nothing to navigate; only Esc is useful here.
+						if (kb.matches(data, "tui.select.cancel")) finishCancel();
+						return;
+					}
+					// Column switching.
+					if (matchesKey(data, "left")) {
+						if (cursor.kind === "run") {
+							cursor = { kind: "cell", row: itemRows.length - 1, col: "task" };
+						} else if (cursor.col === "order") {
+							cursor = { kind: "cell", row: cursor.row, col: "task" };
+						}
+						lastCellRow = cursor.kind === "cell" ? cursor.row : lastCellRow;
+						resetPreview();
+						tui.requestRender();
+						return;
+					}
+					if (matchesKey(data, "right")) {
+						if (cursor.kind === "cell" && cursor.col === "task") {
+							// Same row: the ORDER cell shows whether this task is
+							// in the chain, and Enter toggles it.
+							cursor = { kind: "cell", row: cursor.row, col: "order" };
+						}
+						// (→ in the ORDER column and on the Run row is a no-op:
+						// the cursor is already at the right/bottom edge.)
+						lastCellRow = cursor.kind === "cell" ? cursor.row : lastCellRow;
+						resetPreview();
+						tui.requestRender();
+						return;
+					}
+					// Row navigation: the cursor moves in both columns (wrap at
+					// the edges); the Run row is reached from the last task row.
 					if (kb.matches(data, "tui.select.up")) {
-						selectedIndex = selectedIndex === 0 ? itemRows.length - 1 : selectedIndex - 1;
+						if (cursor.kind === "run") {
+							cursor = { kind: "cell", row: itemRows.length - 1, col: "task" };
+						} else {
+							cursor = {
+								kind: "cell",
+								row: cursor.row === 0 ? itemRows.length - 1 : cursor.row - 1,
+								col: cursor.col,
+							};
+						}
+						lastCellRow = cursor.kind === "cell" ? cursor.row : lastCellRow;
 						resetPreview();
 						tui.requestRender();
+						return;
 					}
-					else if (kb.matches(data, "tui.select.down")) {
-						selectedIndex = selectedIndex === itemRows.length - 1 ? 0 : selectedIndex + 1;
+					if (kb.matches(data, "tui.select.down")) {
+						if (cursor.kind === "run") {
+							cursor = { kind: "cell", row: 0, col: "task" };
+						} else if (cursor.row === itemRows.length - 1) {
+							// The pinned Run row sits below the last task row.
+							cursor = { kind: "run" };
+							lastCellRow = itemRows.length - 1;
+						} else {
+							cursor = {
+								kind: "cell",
+								row: cursor.row + 1,
+								col: cursor.col,
+							};
+						}
+						lastCellRow = cursor.kind === "cell" ? cursor.row : lastCellRow;
 						resetPreview();
 						tui.requestRender();
+						return;
 					}
-					else if (kb.matches(data, "tui.select.confirm")) {
-						const chosen = itemRows[selectedIndex];
-						if (chosen) finish(chosen.task);
+					// Confirm: context-dependent.
+					if (kb.matches(data, "tui.select.confirm")) {
+						if (cursor.kind === "run") {
+							if (chain.items.length === 0) {
+								ctx.ui.notify("do-always: chain is empty — add a task first", "info");
+							} else {
+								finishChain([...chain.items]);
+							}
+							return;
+						}
+						const row = itemRows[cursor.row];
+						if (!row) return;
+						if (cursor.col === "task") {
+							// The classic pick: run just this task (fill or
+							// auto-run per its autoRun), discarding the chain.
+							finishSingle(row.task);
+							return;
+						}
+						// ORDER column: toggle this task's chain membership.
+						if (chain.items.includes(row.task.name)) {
+							chain = chainRemove(chain, row.task.name);
+						} else {
+							const { state, result } = chainAdd(chain, row.task.name);
+							chain = state;
+							if (result === "full") {
+								ctx.ui.notify(`do-always: chain is full (${CHAIN_MAX}) — remove a task first`, "error");
+							}
+						}
+						lastCellRow = cursor.kind === "cell" ? cursor.row : lastCellRow;
+						resetPreview();
+						tui.requestRender();
+						return;
+					}
+					// Clear the chain.
+					if (matchesKey(data, "ctrl+u")) {
+						if (chain.items.length > 0) {
+							chain = chainClear();
+							clampCursor();
+							resetPreview();
+							tui.requestRender();
+						}
+						return;
 					}
-					else if (kb.matches(data, "tui.select.cancel")) {
-						finish(null);
+					if (kb.matches(data, "tui.select.cancel")) {
+						finishCancel();
 					}
 				},
 				handleMouse(event: TuiMouseEvent): TuiMouseEventResult | undefined {
@@ -454,21 +1369,48 @@ export default function doAlwaysExtension(pi: ExtensionAPI) {
 						const { itemRows } = getVisible();
 						if (itemRows.length === 0) return undefined;
 						const delta = event.wheelDelta < 0 ? -1 : 1;
-						const prev = selectedIndex;
-						selectedIndex = Math.max(0, Math.min(itemRows.length - 1, selectedIndex + delta));
-						if (selectedIndex !== prev) resetPreview();
-						return { handled: true, render: selectedIndex !== prev };
+						const prev = cursor.kind === "cell" ? cursor.row : lastCellRow;
+						const next = Math.max(0, Math.min(itemRows.length - 1, prev + delta));
+						if (next === prev) return { handled: true };
+						cursor = { kind: "cell", row: next, col: "task" };
+						lastCellRow = next;
+						resetPreview();
+						return { handled: true, render: true };
 					}
 					if (event.button !== "left" || (event.type !== "press" && event.type !== "click")) return undefined;
-					const { itemLine, itemRows } = buildRender(event.width);
+					// Reuse the last render's table for hit-testing (avoids
+				// rebuilding the table twice per mouse event). The table is
+				// always fresh because handleInput calls requestRender before
+				// the next mouse event can arrive.
+				const { itemLine, runLine, orderColX } = lastTable ?? buildTable(event.width);
+					// Pinned Run row: press runs the chain.
+					if (runLine >= 0 && event.y === runLine) {
+						if (event.type === "press" && chain.items.length > 0) {
+							finishChain([...chain.items]);
+						}
+						return { handled: true };
+					}
 					const task = itemLine.get(event.y);
 					if (!task) return undefined;
+					const { itemRows } = getVisible();
 					const idx = itemRows.findIndex((r) => r.task === task);
 					if (idx < 0) return undefined;
+					// ORDER cell: press toggles chain membership.
+					if (orderColX !== null && event.x >= orderColX) {
+						if (event.type === "press") {
+							chain = chain.items.includes(task.name) ? chainRemove(chain, task.name) : chainAdd(chain, task.name).state;
+							clampCursor();
+							resetPreview();
+							return { handled: true, render: true };
+						}
+						return { handled: true }; // swallow the click after the press action
+					}
+					// Task area: press selects, click runs (the classic fast path).
 					if (event.type === "press") {
 						mousePressedIndex = idx;
-						if (selectedIndex !== idx) {
-							selectedIndex = idx;
+						if (cursor.kind !== "cell" || cursor.row !== idx) {
+							cursor = { kind: "cell", row: idx, col: "task" };
+							lastCellRow = idx;
 							resetPreview();
 						}
 						return { handled: true, focus: true, render: true };
@@ -476,24 +1418,33 @@ export default function doAlwaysExtension(pi: ExtensionAPI) {
 					const clicked = mousePressedIndex ?? idx;
 					mousePressedIndex = null;
 					const chosen = itemRows[clicked];
-					if (chosen) finish(chosen.task);
+					if (chosen) finishSingle(chosen.task);
 					return { handled: true };
 				},
 			};
 		});
 
-		if (selected === null || selected === undefined) return;
-		await fillPrompt(tasks[selected], ctx);
+		if (!result || result.kind === "cancel") return;
+		if (result.kind === "single") {
+			await fillPrompt(result.task, ctx, context);
+		} else {
+			await runChain(result.names, ctx, cache);
+		}
 	}
 
 	pi.registerCommand("do-always", {
 		description: "Pick a common task (review, readme, ...) by number — fills the prompt",
 		getArgumentCompletions: (prefix) => {
 			const p = prefix.trim().toLowerCase();
+			// Number tasks by position in the VISIBLE (when-filtered) list — the
+			// same list the selector and `/do-always <n>` use. The cache is
+			// refreshed on session start and every command run; when it is
+			// stale, fall back to the full list rather than guessing.
+			const visible = visibleCache?.cwd === loadedCwd ? visibleCache.visible : tasks;
 			const matches = [
 				{ value: "list", label: "list" },
 				{ value: "list-details", label: "list-details" },
-				...tasks.map((t, i) => ({ value: t.name, label: `${i + 1}. ${t.name}` })),
+				...visible.map((t, i) => ({ value: t.name, label: `${i + 1}. ${t.name}` })),
 			].filter((c) => c.value.toLowerCase().includes(p));
 			return matches.length > 0 ? matches : null;
 		},
@@ -502,48 +1453,39 @@ export default function doAlwaysExtension(pi: ExtensionAPI) {
 		},
 	});
 
-	// Keyboard shortcut: open the task selector without typing the command.
-	// The key is configurable via the "shortcut" field in do-always.json
-	// (null disables it). It is read once at extension load, so changing it
-	// requires a reload or a new session.
-	const configuredShortcut = loadConfig(process.cwd()).shortcut;
-	if (configuredShortcut !== null) {
-		const shortcutKey = isValidKeyId(configuredShortcut) ? configuredShortcut : DEFAULT_SHORTCUT;
-		if (shortcutKey !== configuredShortcut) {
-			console.warn(`do-always: invalid shortcut "${configuredShortcut}" in do-always.json — using ${DEFAULT_SHORTCUT}`);
-		}
-		pi.registerShortcut(shortcutKey as KeyId, {
-			description: "do-always: pick a common task",
-			handler: async (ctx) => {
-				await runDoAlways("", ctx);
-			},
-		});
-	}
-
 	async function runDoAlways(args: string, ctx: ExtensionContext): Promise<void> {
+		lastCtx = ctx;
 		// Reload when the active directory changes, so switching projects
 		// mid-session serves the right config instead of stale tasks.
 		if (ctx.cwd !== loadedCwd) {
 			loadedCwd = ctx.cwd;
-			tasks = loadConfig(ctx.cwd).tasks;
+			const onError = (m: string) => {
+				if (ctx.mode === "tui") ctx.ui.notify(m, "warning");
+				else console.warn(m);
+			};
+			const config = loadConfig(ctx.cwd, onError);
+			tasks = config.tasks;
+			reportEnabled = config.report;
 		}
 
+		// One context per command run: shared by visibility filtering, rendering,
+		// and the completion cache (never inside a render loop).
+		const cache = createContextCache();
+		const context = cache.get(ctx.cwd);
+		const visible = refreshVisible(ctx.cwd, context);
+
 		const arg = args.trim();
 
 		if (!arg) {
 			if (ctx.mode === "tui") {
-				await showSelector(ctx);
+				await showSelector(ctx, context, cache);
 			} else {
-				const context = buildContext(ctx.cwd);
-				const visible = tasks.filter((t) => evaluateWhen(t, context));
 				ctx.ui.notify(`do-always tasks (use /do-always <number|name>):\n${formatList(visible)}`, "info");
 			}
 			return;
 		}
 
 		if (arg.toLowerCase() === "list") {
-			const context = buildContext(ctx.cwd);
-			const visible = tasks.filter((t) => evaluateWhen(t, context));
 			ctx.ui.notify(formatList(visible), "info");
 			return;
 		}
@@ -551,14 +1493,13 @@ export default function doAlwaysExtension(pi: ExtensionAPI) {
 		if (arg.toLowerCase() === "list-details") {
 			// Display only — the description is metadata; selecting a task injects just its prompt.
 			// Render with the current context so what is shown is what gets injected.
-			const context = buildContext(ctx.cwd);
-			const visible = tasks.filter((t) => evaluateWhen(t, context));
+			const strings = toPromptContext(context);
 			const details = visible
 				.map((t, i) => {
 					const lines = [`${i + 1}. ${t.name}`];
 					if (t.description) lines.push(`   description: ${t.description}`);
 					lines.push("   prompt (this is what gets injected on select):");
-					for (const line of renderPrompt(t.prompt, context).split("\n")) lines.push(`   ${line}`);
+					for (const line of renderPrompt(t.prompt, strings).split("\n")) lines.push(`   ${line}`);
 					return lines.join("\n");
 				})
 				.join("\n\n");
@@ -573,8 +1514,6 @@ export default function doAlwaysExtension(pi: ExtensionAPI) {
 		// Numbers index the VISIBLE list (what the user sees in the selector and
 		// `list`); names resolve against the full set so picking a hidden task by
 		// name gets an explanatory message below instead of "unknown task".
-		const context = buildContext(ctx.cwd);
-		const visible = tasks.filter((t) => evaluateWhen(t, context));
 		const task = resolveTask(/^\d+$/.test(arg) ? visible : tasks, arg);
 		if (!task) {
 			const available = visible.map((t, i) => `${i + 1}=${t.name}`).join(", ");
@@ -587,6 +1526,6 @@ export default function doAlwaysExtension(pi: ExtensionAPI) {
 			ctx.ui.notify(`do-always: "${task.name}" is hidden by its "when" condition`, "info");
 			return;
 		}
-		await fillPrompt(task, ctx);
+		await fillPrompt(task, ctx, context);
 	}
 }