@maheidem/pi-loop 0.7.0

package/LICENSE

@@ -0,0 +1,32 @@
+MIT License
+
+Copyright (c) 2026 maheidem
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+This project builds against and vendors patterns from works under the MIT
+License, copyright their respective authors:
+
+- @earendil-works/pi-coding-agent (pi coding agent), including the official
+  `subagent` and `plan-mode` extension examples and RPC documentation.
+- @earendil-works/pi-tui.
+- The local `/loop` extension (same workspace), from which
+  `ui/settings-panel.ts` is vendored.

package/README.md

@@ -0,0 +1,118 @@
+# loop — `/loop` for pi
+
+Run any prompt on a schedule inside the current session. Modeled on
+Claude Code's `/loop` (CronCreate): the interval and the prompt are yours;
+the loop just keeps injecting the prompt into **this conversation** every X.
+
+The loop knows nothing about what the prompt says. It is a **generic
+mechanism**. Specializations — like the bundled `shepherd` skill
+(`skills/shepherd/`) — are *consumers* of `/loop`, not part of it.
+
+## Usage
+
+```
+/loop                                               # interactive dashboard
+/loop 5m check the deploy and tell me what happened
+/loop 30s run the test suite and fix failures       # fast loop (min 15s)
+/loop 2h <prompt>                                    # slow loop
+/loop status                                         # show active loop
+/loop stop                                           # cancel
+```
+
+The bare command opens a responsive dashboard in TUI mode. It shows the
+current schedule, live countdown, delivery mode, prompt preview, and safe
+start/edit/stop actions. In print/RPC/JSON modes, the bare command reports
+status instead. The nested forms remain the stable scripting interface and
+are taught by argument autocomplete.
+
+Interval formats: `30s`, `5m`, `2h`, `1d` (minimum 15s). Omit the interval
+for the default 10m. A trailing `every 5m` clause also works:
+`/loop check CI every 5m`.
+
+Each tick arrives as a `loop-tick` custom message — the prompt verbatim,
+with a one-line provenance header so the model knows it is a scheduled
+message, not a fresh user request — rendered in the TUI as a collapsible
+card (`↻ loop tick #7 · check the deploy…`):
+
+```
+[loop tick #7 · scheduled by /loop, not typed by the user]
+check the deploy and tell me what happened
+```
+
+## How it works
+
+One mechanism: an **in-session timer** (`index.ts`). Each tick is a single
+`pi.sendMessage({ customType: "loop-tick", content, display: true,
+details }, { deliverAs: "steer", triggerTurn: true })` call — steer
+injects into a busy agent and wakes an idle one in the same call, so there
+is no idle check to race. Catch-up: on `agent_settled`, if a tick's fire
+time passed while the agent was busy, it fires immediately (at most one
+catch-up tick, no backlog). The timer dies with the pi process, the same
+lifetime a Claude Code in-session cron has. (An earlier version also
+spawned an external RPC runner; it was removed — old state entries
+carrying a `runnerPid` are still read, the field is ignored.)
+
+### State & resume
+
+Loop state persists as a `loop` custom entry in the session JSONL
+(`pi.appendEntry`). On `/resume`, `session_start` re-arms the timer — CC's
+"restored on `--resume`" semantics. `/loop stop` appends a `stopped: true`
+entry. (Entries written by earlier versions under the old entry type, or
+carrying a legacy `runnerPid`, are still read.)
+
+### Safety & limits
+
+- One active loop per session (`/loop` while armed → stop first).
+- Session-scoped by lifetime (delivery is a single in-process call — no
+  child processes, nothing to orphan). No wall-clock expiry.
+
+## The shepherd skill (a consumer of /loop)
+
+The bundled `skills/shepherd/` skill (installed at
+`~/.pi/agent/skills/shepherd`) is the pi port of the Claude Code shepherd
+plugin: it pins `/loop` to a fixed 10-minute cadence with the
+shepherd-role prompt (watch, act, unblock, understand problems). It's a
+separate thing from the loop — the loop is generic; the skill just builds
+a specific prompt and hands it to `/loop`.
+
+```
+/skill:shepherd <goal to shepherd>
+```
+
+## Differences vs Claude Code `/loop`
+
+| | Claude Code | pi /loop |
+|---|---|---|
+| Scheduler | built-in `CronCreate` (in-process, session-scoped) | in-session timer, single steer delivery |
+| Survives model stall | yes (cron fires between turns) | yes (steer injects into a busy turn) |
+| Survives restart | no (restored on `--resume`) | no (re-armed on `/resume` via session entry) |
+| Interval | cron granularity, 1m–7d | any ≥15s, no expiry |
+| Dynamic interval | yes (model picks delay) | no — fixed interval only |
+| Jitter | yes (deterministic offset) | no |
+
+## Development
+
+```bash
+cd custom-extensions/loop
+npm install
+npm run typecheck
+npm test            # domain + dashboard contracts + real pi E2E (~30s)
+```
+
+Install as a pi package (`~/.pi/agent/settings.json` → `packages`):
+
+```json
+"/Users/maheidem/Documents/dev/pi-coder-management/custom-extensions/loop"
+```
+
+then `/reload` in pi. The skill is in `skills/shepherd/SKILL.md` (source of
+truth) and installed to `~/.pi/agent/skills/shepherd/` (copy after edits).
+
+## Files
+
+- `index.ts` — the extension: `/loop` commands, timer, steer delivery,
+  catch-up, tick renderer
+- `state.ts` — pure helpers: interval parsing, tick provenance line, state
+- `ui/loop-panel.ts` — Pi-free dashboard view model
+- `ui/settings-panel.ts` — vendored workbench panel interaction primitive
+- `skills/shepherd/SKILL.md` — the shepherd skill (a consumer of /loop)

package/index.ts

@@ -0,0 +1,388 @@
+/**
+ * loop — generic /loop for pi.
+ *
+ * Recurring scheduled prompts, modeled on Claude Code's /loop (CronCreate).
+ * The extension knows nothing about what the prompt says: whatever you give
+ * it fires verbatim every interval. Role/specialization (skills that use
+ * /loop) are consumers of the loop, not part of it.
+ *
+ * One mechanism: an in-session timer that fires each tick as a single
+ * `pi.sendMessage` call with `deliverAs: "steer", triggerTurn: true` — steer
+ * injects-when-busy and wakes-when-idle in one call, so there is no idle
+ * check to race. Dies with the session, same lifetime as a CC in-session
+ * cron. (An earlier external runner was removed; state entries carrying a
+ * `runnerPid` are still read, the field is ignored.)
+ *
+ * State persists as a `loop` custom entry in the session, so /resume
+ * re-arms the timer. (Legacy entry types from earlier versions are still
+ * read for compatibility.)
+ */
+
+import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+import {
+	CUSTOM_TYPE,
+	DEFAULT_INTERVAL_MS,
+	formatInterval,
+	loopTickMessage,
+	parseInterval,
+	readLoopState,
+	type LoopState,
+} from "./state.ts";
+import { buildLoopPanelSnapshot, formatCountdown } from "./ui/loop-panel.ts";
+import { SettingsPanel, type PanelResult } from "./ui/settings-panel.ts";
+
+const TAG = "[loop]";
+const TICK_CUSTOM_TYPE = "loop-tick";
+
+interface Runtime {
+	timer: NodeJS.Timeout | null;
+	nextFireAt: number;
+	state: LoopState | null;
+}
+
+function say(ctx: ExtensionContext, msg: string, level: "info" | "warning" | "error" = "info"): void {
+	if (ctx.hasUI) ctx.ui.notify(msg, level);
+	else console.log(msg);
+}
+
+export default function (pi: ExtensionAPI) {
+	const rt: Runtime = { timer: null, nextFireAt: 0, state: null };
+
+	/** Parse `/loop` args. Returns { intervalMs, prompt } or an error string. */
+	function parseArgs(args: string): { intervalMs: number; prompt: string } | string {
+		const tokens = args.trim().split(/\s+/).filter(Boolean);
+		if (tokens.length === 0) {
+			return "usage: /loop <interval> <prompt...>   (e.g. /loop 5m check the build)";
+		}
+		let intervalMs = NaN;
+		let rest = tokens;
+		const first = tokens[0];
+		if (/^\d/.test(first)) {
+			intervalMs = parseInterval(first);
+			if (Number.isNaN(intervalMs)) {
+				return `invalid interval "${first}" — use e.g. 30s, 5m, 2h, 1d`;
+			}
+			rest = tokens.slice(1);
+		} else {
+			// Trailing-clause form: "check the build every 5m"
+			const m = /(?:^|\s)every\s+(\d+(?:\.\d+)?[smhd])(?=\s|$)/i.exec(args);
+			if (m) intervalMs = parseInterval(m[1]);
+		}
+		if (Number.isNaN(intervalMs)) intervalMs = DEFAULT_INTERVAL_MS;
+		const prompt = rest.join(" ").trim();
+		if (!prompt) {
+			return "no prompt given — /loop <interval> <prompt...>";
+		}
+		return { intervalMs, prompt };
+	}
+
+	function loopStatusText(): string {
+		if (!rt.state) return `${TAG} no active loop. Start one from /loop or use /loop 5m <prompt>.`;
+		const state = rt.state;
+		return [
+			`${TAG} active`,
+			`interval: ${formatInterval(state.intervalMs)}`,
+			`next tick: ${formatCountdown(rt.nextFireAt - Date.now())}`,
+			`ticks sent: ${state.tickCount}`,
+			`delivery: in-session steer`,
+			`prompt: ${state.prompt}`,
+		].join("\n");
+	}
+
+	function panelView() {
+		const state = rt.state;
+		return {
+			active: Boolean(state),
+			interval: state ? formatInterval(state.intervalMs) : formatInterval(DEFAULT_INTERVAL_MS),
+			nextIn: state ? formatCountdown(rt.nextFireAt - Date.now()) : "—",
+			tickCount: state?.tickCount ?? 0,
+			delivery: state ? "in-session steer" : "—",
+			prompt: state?.prompt ?? "",
+		};
+	}
+
+	function fireTick(ctx: ExtensionContext) {
+		if (!rt.state) return;
+		const s = rt.state;
+		s.tickCount += 1;
+		s.lastTickAt = Date.now();
+		// ADVANCE the schedule on every fire. Without this, `due` in
+		// scheduleNext() goes negative after the first interval and the timer
+		// collapses into a 1-second re-fire storm.
+		rt.nextFireAt = Date.now() + s.intervalMs;
+		pi.appendEntry(CUSTOM_TYPE, { ...s });
+		say(ctx, `${TAG} tick #${s.tickCount} — sent (steer)`, "info");
+		// The prompt fires verbatim. The one-line meta prefix
+		// (loopTickMessage) only carries provenance — that this is a
+		// scheduled tick, not something the user typed — so the model
+		// doesn't misread the repetition as a fresh intent. What the tick does
+		// is entirely the prompt's own business.
+		const content = loopTickMessage(s.prompt, s.tickCount);
+		// ONE delivery call: steer injects when busy and triggers a turn when
+		// idle, so there is no isIdle() check to race against a submission.
+		pi.sendMessage(
+			{
+				customType: TICK_CUSTOM_TYPE,
+				content,
+				display: true,
+				details: { tickCount: s.tickCount, intervalMs: s.intervalMs, scheduledAt: Date.now() },
+			},
+			{ deliverAs: "steer", triggerTurn: true },
+		);
+		scheduleNext(ctx);
+	}
+
+	function scheduleNext(ctx: ExtensionContext) {
+		if (rt.timer) clearTimeout(rt.timer);
+		rt.timer = null;
+		if (!rt.state) return;
+		const due = rt.nextFireAt - Date.now();
+		rt.timer = setTimeout(() => fireTick(ctx), Math.max(1000, due));
+		rt.timer.unref?.();
+	}
+
+	function stopLoop(ctx: ExtensionContext, reason: string, announce = true) {
+		if (rt.timer) clearTimeout(rt.timer);
+		rt.timer = null;
+		const s = rt.state;
+		if (s) {
+			pi.appendEntry(CUSTOM_TYPE, { ...s, stopped: true });
+		}
+		rt.state = null;
+		if (announce) say(ctx, `${TAG} loop stopped (${reason})`, "info");
+	}
+
+	function armLoop(ctx: ExtensionContext, intervalMs: number, prompt: string) {
+		const state: LoopState = {
+			intervalMs,
+			prompt,
+			createdAt: Date.now(),
+			lastTickAt: 0,
+			tickCount: 0,
+		};
+		rt.state = state;
+		rt.nextFireAt = Date.now() + intervalMs;
+		pi.appendEntry(CUSTOM_TYPE, { ...state });
+		scheduleNext(ctx);
+
+		say(
+			ctx,
+			`${TAG} armed: every ${formatInterval(intervalMs)} — "${prompt.slice(0, 80)}${prompt.length > 80 ? "…" : ""}"`,
+			"info",
+		);
+		say(ctx, `${TAG} in-session steer active. Stop with /loop stop.`, "info");
+	}
+
+	function restoreFromSession(ctx: ExtensionContext) {
+		const entries = ctx.sessionManager.getEntries();
+		const s = readLoopState(entries);
+		if (!s) return;
+		rt.state = s;
+		rt.nextFireAt = Date.now() + s.intervalMs; // re-arm: next tick one interval from now
+		say(ctx, `${TAG} restored (every ${formatInterval(s.intervalMs)}, tick #${s.tickCount}) — re-arming`, "info");
+		scheduleNext(ctx);
+	}
+
+	async function editSchedule(ctx: ExtensionCommandContext, editing: boolean): Promise<boolean> {
+		const existing = editing ? rt.state : null;
+		let intervalMs: number | undefined;
+		let proposed = existing ? formatInterval(existing.intervalMs) : formatInterval(DEFAULT_INTERVAL_MS);
+		while (intervalMs === undefined) {
+			const raw = await ctx.ui.input("Loop interval", proposed);
+			if (raw === undefined) return false;
+			const parsed = parseInterval(raw.trim());
+			if (Number.isNaN(parsed)) {
+				say(ctx, "Interval must look like 30s, 10m, 2h, or 1d.", "error");
+				proposed = raw;
+				continue;
+			}
+			intervalMs = parsed;
+		}
+
+		const editedPrompt = await ctx.ui.editor("Recurring prompt", existing?.prompt ?? "");
+		if (editedPrompt === undefined) return false;
+		const prompt = editedPrompt.trim();
+		if (!prompt) {
+			say(ctx, "Recurring prompt cannot be empty.", "error");
+			return false;
+		}
+
+		if (editing && rt.state) stopLoop(ctx, "schedule replaced", false);
+		armLoop(ctx, intervalMs, prompt);
+		return true;
+	}
+
+	async function openLoopPanel(ctx: ExtensionCommandContext): Promise<void> {
+		if (ctx.mode !== "tui") {
+			say(ctx, loopStatusText());
+			return;
+		}
+
+		let initialKey = rt.state ? "edit" : "start";
+		for (;;) {
+			let refreshTimer: ReturnType<typeof setInterval> | undefined;
+			let result: PanelResult | undefined;
+			try {
+				result = await ctx.ui.custom<PanelResult>(
+					(tui, theme, keybindings, done) => {
+						const panel = new SettingsPanel({
+							theme,
+							keybindings,
+							initialKey,
+							snapshot: () => buildLoopPanelSnapshot(panelView()),
+							apply: () => "This row is read-only",
+							activate: (key) => ["start", "edit", "stop"].includes(key)
+								? { kind: "close", action: key }
+								: { kind: "error", message: `Unknown loop action: ${key}` },
+							requestRender: () => tui.requestRender(),
+							done,
+						});
+						refreshTimer = setInterval(() => {
+							panel.refresh();
+							tui.requestRender();
+						}, 1_000);
+						return panel;
+					},
+					{
+						overlay: true,
+						overlayOptions: {
+							anchor: "center",
+							width: 76,
+							minWidth: 44,
+							maxHeight: "90%",
+							margin: 1,
+						},
+					},
+				);
+			} finally {
+				if (refreshTimer) clearInterval(refreshTimer);
+			}
+
+			if (!result?.action) return;
+			if (result.action === "start" || result.action === "edit") {
+				await editSchedule(ctx, result.action === "edit");
+				initialKey = rt.state ? "edit" : "start";
+				continue;
+			}
+			if (result.action === "stop") {
+				const confirmed = await ctx.ui.confirm("Stop recurring loop?", "No further scheduled ticks will be delivered.");
+				if (confirmed && rt.state) stopLoop(ctx, "stopped from control panel");
+				initialKey = rt.state ? "edit" : "start";
+			}
+		}
+	}
+
+	// LR2: ticks render as collapsible cards — collapsed shows the tick
+	// number + the prompt's first line (after the provenance header),
+	// expanded shows the full content byte-for-byte.
+	pi.registerMessageRenderer(TICK_CUSTOM_TYPE, (message, options) => {
+		const d = (message.details ?? {}) as { tickCount?: number };
+		const raw = message.content;
+		const text =
+			typeof raw === "string" ? raw
+			: Array.isArray(raw) ? raw.map((b) => (b as { text?: string })?.text ?? "").join("\n")
+			: "";
+		const firstLine = text.split("\n").slice(1).find((l) => l.trim().length > 0) ?? "";
+		const header = `↻ loop tick #${d.tickCount ?? "?"}${firstLine ? ` · ${firstLine}` : ""}`;
+		return new Text(options.expanded ? `${header}\n${text}` : header, options.outputPad, 0);
+	});
+
+	pi.on("session_start", async (_event, ctx) => {
+		restoreFromSession(ctx);
+	});
+
+	pi.on("agent_settled", async (_event, ctx) => {
+		// Catch-up: if a tick's fire time passed while we were busy, fire now
+		// (no backlog — at most one catch-up tick). Same single steer call;
+		// no isIdle gate — steer handles busy and idle alike.
+		if (rt.state && rt.nextFireAt <= Date.now()) {
+			fireTick(ctx);
+		}
+	});
+
+	pi.on("session_shutdown", async () => {
+		if (rt.timer) clearTimeout(rt.timer);
+		rt.timer = null;
+	});
+
+	pi.registerCommand("loop", {
+		description: "Open recurring-loop controls or schedule with /loop <interval> <prompt...>",
+		getArgumentCompletions: (prefix) => {
+			const values = ["status", "stop", "30s ", "5m ", "10m ", "1h "];
+			const matches = values.filter((value) => value.startsWith(prefix));
+			return matches.length ? matches.map((value) => ({ value, label: value })) : null;
+		},
+		handler: async (args, ctx) => {
+			const a = (args ?? "").trim();
+			if (!a) {
+				await openLoopPanel(ctx);
+				return;
+			}
+			if (a === "status") {
+				say(ctx, loopStatusText());
+				return;
+			}
+			if (a === "stop") {
+				stopLoop(ctx, "user requested");
+				return;
+			}
+			const parsed = parseArgs(a);
+			if (typeof parsed === "string") {
+				say(ctx, `${TAG} ${parsed}`, "error");
+				return;
+			}
+			if (rt.state) {
+				say(ctx, `${TAG} a loop is already active — stop it first with /loop stop`, "warning");
+				return;
+			}
+			armLoop(ctx, parsed.intervalMs, parsed.prompt);
+		},
+	});
+
+	// The model cannot type slash commands — this tool is how the LLM arms
+	// or stops a loop (e.g. the shepherd skill). Same code path as /loop.
+	pi.registerTool({
+		name: "loop",
+		label: "Loop",
+		description:
+			"Arm or stop a recurring /loop in this session: re-runs a prompt verbatim on a fixed interval via an in-session steer delivery (one call — wakes an idle agent, injects into a busy one). Use it to start unattended periodic work (e.g. the shepherd skill) or to stop it. action: start (needs interval + prompt), status, stop.",
+		parameters: Type.Object({
+			action: Type.Union([
+				Type.Literal("start"),
+				Type.Literal("status"),
+				Type.Literal("stop"),
+			]),
+			interval: Type.Optional(Type.String({ description: "e.g. 30s, 5m, 2h, 1d. Default 10m, min 15s." })),
+			prompt: Type.Optional(Type.String({ description: "The prompt to fire each tick, verbatim. Required for action=start." })),
+		}),
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			if (params.action === "start") {
+				const parsed = parseArgs(`${params.interval ?? ""} ${params.prompt ?? ""}`.trim());
+				if (typeof parsed === "string") {
+					return { content: [{ type: "text" as const, text: `Cannot start loop: ${parsed}` }], details: {} };
+				}
+				if (rt.state) {
+					return { content: [{ type: "text" as const, text: "A loop is already active. Stop it first (action: stop)." }], details: {} };
+				}
+				armLoop(ctx, parsed.intervalMs, parsed.prompt);
+				return {
+					content: [{
+						type: "text" as const,
+						text: `Loop armed: every ${formatInterval(parsed.intervalMs)}, prompt "${parsed.prompt}". It re-fires in this session via steer delivery. Stop with action "stop".`,
+					}],
+					details: {},
+				};
+			}
+			if (params.action === "stop") {
+				if (!rt.state) {
+					return { content: [{ type: "text" as const, text: "No active loop." }], details: {} };
+				}
+				stopLoop(ctx, "stopped via loop tool");
+				return { content: [{ type: "text" as const, text: "Loop stopped." }], details: {} };
+			}
+			return { content: [{ type: "text" as const, text: loopStatusText() }], details: {} };
+		},
+	});
+}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@maheidem/pi-loop",
+  "version": "0.7.0",
+  "type": "module",
+  "description": "Pi extension: /loop \u2014 a generic recurring-prompt loop (Claude Code /loop style) delivered as in-session steer custom messages. Skills (e.g. shepherd) are consumers of /loop, not part of it.",
+  "keywords": [
+    "pi-package",
+    "extension",
+    "loop",
+    "cron",
+    "recurring"
+  ],
+  "files": [
+    "index.ts",
+    "state.ts",
+    "ui/settings-panel.ts",
+    "ui/loop-panel.ts",
+    "skills/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.json",
+    "test:unit": "tsx --test *.test.ts ui/*.test.ts",
+    "test:e2e": "node e2e.test.mjs",
+    "test": "npm run test:unit && npm run test:e2e",
+    "prepack": "npm run typecheck && npm test"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": ">=0.84.0",
+    "typebox": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.84.4",
+    "@earendil-works/pi-tui": "^0.84.4",
+    "@types/node": "^22.0.0",
+    "tsx": "^4.20.0",
+    "typescript": "^5.9.3"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "license": "MIT",
+  "author": "maheidem",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Maheidem/pi-coder-management.git",
+    "directory": "custom-extensions/loop"
+  },
+  "homepage": "https://github.com/Maheidem/pi-coder-management/tree/main/custom-extensions/loop#readme",
+  "bugs": {
+    "url": "https://github.com/Maheidem/pi-coder-management/issues"
+  }
+}

package/skills/shepherd/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: shepherd
+description: Start a recurring shepherd loop over a goal using the loop tool — it re-injects the checkpoint prompt every interval (wakes an idle session, steers a busy one), so the work keeps running without the user babysitting it. Use when the user says "shepherd this", wants unattended goal watching, or asks for a recurring watch/act/unblock loop.
+---
+
+# Shepherd
+
+You are the **shepherd** of a goal: a recurring loop that watches, acts,
+unblocks, and understands problems so the goal keeps running unattended —
+instead of the user babysitting it turn by turn.
+
+This skill is the pi port of the Claude Code `shepherd` plugin: same role,
+same fixed 10-minute cadence, built on the `loop` extension (the generic
+`/loop` mechanism).
+
+## How it works
+
+The `loop` extension provides a `loop` **tool** (same mechanism behind the
+user's `/loop` command): an in-session timer delivers each tick with a single
+steer call — it wakes the session when idle and is absorbed at your next
+model call when you are busy. Each tick arrives as your prompt verbatim with
+a one-line `[loop tick #N · scheduled by /loop, not typed by the user]`
+provenance header, rendered as a compact ↻ card.
+
+## Usage
+
+1. If no goal was given (the `User:` args below are empty), ask the user
+   what goal to shepherd, then continue.
+
+2. Start the loop by **calling the `loop` tool** (do NOT type `/loop` —
+   you cannot; the tool is your way in). Fixed **10-minute** interval, do
+   not self-pace. Arguments:
+
+   - `action`: `start`
+   - `interval`: `10m`
+   - `prompt`: the shepherd prompt below, with `<GOAL>` replaced by the
+     goal verbatim:
+
+   ```
+   You will be the shepherd of this goal: <GOAL>. You need to keep a close watch. You need to take action. You need to take agency. You need to unblock the execution. Understand problems. And act as someone truly useful to make sure this thing keeps on running. If work is incomplete or stuck, continue it now. If everything is done and verified, say so in one line and tell the user to run /loop stop.
+   ```
+
+   The tool confirms the arm (it also emits a `[loop] armed` notice in
+   the session). Then continue working on the goal — do not wait for
+   ticks.
+
+3. On every tick you will receive your prompt (with the loop provenance
+   header). When you do:
+   - Review what has happened since the last tick (transcript, files, tests).
+   - If work is incomplete or stuck: **continue it now**. Take action.
+   - Diagnose drift, breakage, or stalls; fix what you can.
+   - If everything is done and verified: say so in one line, and tell the
+     user they can stop the loop (`/loop stop`), or stop it yourself via
+     the `loop` tool (`action: stop`).
+
+## Doc-keeping variant
+
+If the user asks for the docs variant (or the goal is long-running enough
+that documentation drift is a real risk), use this prompt instead — it adds
+the doc-keeping duty from the Claude Code `shepherd-docs` command:
+
+```
+You will be the shepherd of this goal: <GOAL>. You need to keep a close watch. You need to take action. You need to take agency. You need to unblock the execution. Understand problems. And act as someone truly useful to make sure this thing keeps on running. Also, make sure you take notes and update any documentation that needs updating as we go. For anything—roadmap, issues, to-do, discoveries—all the project documentation, make sure you keep that up to date. If everything is done and verified, say so in one line and tell the user to run /loop stop.
+```
+
+## Rules
+
+- Use the fixed **10-minute** interval — do not self-pace.
+- Do not start new initiatives outside the goal's scope on a tick.
+- If the `loop` tool is not in your tool list, the loop extension is not
+  loaded in this session — tell the user to `/reload` in the session and
+  retry; do not try to arm the loop any other way.
+- The loop is session-scoped: it lives while this session exists (the
+  external runner self-exits when the session stops advancing). Re-run
+  this skill in a later session to keep watching.

package/state.ts

@@ -0,0 +1,91 @@
+/**
+ * loop — state helpers.
+ *
+ * Pure, pi-free logic: interval parsing, the tick provenance line, and
+ * reading the loop state out of session entries. Kept dependency-free so it
+ * can be unit-tested with `node --test` without loading the extension
+ * runtime.
+ */
+
+export const CUSTOM_TYPE = "loop";
+/** Earlier versions used a different entry type; still read for compat. */
+export const LEGACY_CUSTOM_TYPES = ["shepherd-loop"];
+const KNOWN_TYPES: string[] = [CUSTOM_TYPE, ...LEGACY_CUSTOM_TYPES];
+
+export const DEFAULT_INTERVAL_MS = 10 * 60 * 1000;
+export const MIN_INTERVAL_MS = 15 * 1000;
+
+/** Parse an interval token like `30s`, `5m`, `2h`, `1d` into milliseconds. */
+export function parseInterval(token: string | undefined, fallback = DEFAULT_INTERVAL_MS): number {
+	if (!token) return fallback;
+	const m = /^\s*(\d+(?:\.\d+)?)\s*([smhd])\s*$/i.exec(token);
+	if (!m) return NaN;
+	const n = parseFloat(m[1]);
+	const unit = m[2].toLowerCase();
+	const mult = { s: 1000, m: 60_000, h: 3_600_000, d: 86_400_000 }[unit]!;
+	return Math.max(MIN_INTERVAL_MS, Math.round(n * mult));
+}
+
+/** Human-readable form of a millisecond interval (for confirmations). */
+export function formatInterval(ms: number): string {
+	if (ms % 86_400_000 === 0) return `${ms / 86_400_000}d`;
+	if (ms % 3_600_000 === 0) return `${ms / 3_600_000}h`;
+	if (ms % 60_000 === 0) return `${ms / 60_000}m`;
+	return `${Math.round(ms / 1000)}s`;
+}
+
+/**
+ * Build the message injected on each tick: a single provenance meta line +
+ * the prompt verbatim. This is meta, NOT role framing: it tells the model
+ * the message is a scheduled /loop tick (and which one) so it doesn't
+ * misread the repetition as a fresh user intent. What the tick should DO is
+ * entirely up to the prompt.
+ */
+export function loopTickMessage(prompt: string, tickNumber: number): string {
+	return `[loop tick #${tickNumber} · scheduled by /loop, not typed by the user]\n${prompt}`;
+}
+
+export interface LoopState {
+	/** interval in ms */
+	intervalMs: number;
+	/** the user's prompt, verbatim */
+	prompt: string;
+	/** when this loop was armed (epoch ms) */
+	createdAt: number;
+	/** last tick fired (epoch ms), 0 if none yet */
+	lastTickAt: number;
+	/** number of ticks fired so far */
+	tickCount: number;
+	/** legacy field from the removed external runner (≤0.6). Read-compat only: ignored on restore, never written. */
+	runnerPid?: number;
+}
+
+export const isLoopState = (v: unknown): v is LoopState => {
+	if (!v || typeof v !== "object") return false;
+	const o = v as Record<string, unknown>;
+	return (
+		typeof o.intervalMs === "number" &&
+		typeof o.prompt === "string" &&
+		typeof o.createdAt === "number"
+	);
+};
+
+/**
+ * Extract the most recent active loop state from session entries.
+ * Entries are append-ordered; an entry with `data.stopped === true` (or
+ * missing data) closes the loop. Accepts the current entry type plus the
+ * legacy one (read-only compat, see LEGACY_CUSTOM_TYPES).
+ */
+export function readLoopState(entries: Array<{ type?: string; customType?: string; data?: unknown }>): LoopState | null {
+	let active: LoopState | null = null;
+	for (const e of entries) {
+		if (e.type !== "custom" || !KNOWN_TYPES.includes(e.customType ?? "")) continue;
+		const d = e.data as (LoopState & { stopped?: boolean }) | undefined;
+		if (!d || d.stopped) {
+			active = null;
+		} else if (isLoopState(d)) {
+			active = d;
+		}
+	}
+	return active;
+}

package/ui/loop-panel.ts

@@ -0,0 +1,87 @@
+import type { PanelSnapshot } from "./settings-panel.ts";
+
+export interface LoopPanelView {
+  active: boolean;
+  interval: string;
+  nextIn: string;
+  tickCount: number;
+  delivery: string;
+  prompt: string;
+}
+
+export function formatCountdown(milliseconds: number): string {
+  const seconds = Math.max(0, Math.ceil(milliseconds / 1000));
+  if (seconds < 60) return `${seconds}s`;
+  const minutes = Math.floor(seconds / 60);
+  const remainder = seconds % 60;
+  if (minutes < 60) return remainder ? `${minutes}m ${remainder}s` : `${minutes}m`;
+  const hours = Math.floor(minutes / 60);
+  const minuteRemainder = minutes % 60;
+  return minuteRemainder ? `${hours}h ${minuteRemainder}m` : `${hours}h`;
+}
+
+function promptPreview(prompt: string): string {
+  const oneLine = prompt.replace(/\s*\n\s*/g, " ↵ ").replace(/\s+/g, " ").trim();
+  if (!oneLine) return "(none)";
+  return oneLine.length > 240 ? `${oneLine.slice(0, 239)}…` : oneLine;
+}
+
+export function buildLoopPanelSnapshot(view: LoopPanelView): PanelSnapshot {
+  const statusRows: PanelSnapshot["sections"][number]["rows"] = [
+    {
+      key: "state",
+      label: "State",
+      value: view.active ? "active" : "inactive",
+      valueStyle: view.active ? "success" : "muted",
+      kind: "info",
+    },
+  ];
+
+  if (view.active) {
+    statusRows.push(
+      { key: "interval", label: "Interval", value: view.interval, valueStyle: "text", kind: "info" },
+      { key: "next", label: "Next tick", value: view.nextIn, valueStyle: "accent", kind: "info" },
+      { key: "ticks", label: "Ticks sent", value: String(view.tickCount), valueStyle: "text", kind: "info" },
+      { key: "delivery", label: "Delivery", value: view.delivery, valueStyle: "muted", kind: "info" },
+    );
+  }
+
+  return {
+    title: "Recurring Loop",
+    summaryLines: [
+      view.active
+        ? `A prompt is scheduled every ${view.interval}; next tick in ${view.nextIn}.`
+        : "No recurring prompt is armed for this session.",
+    ],
+    sections: [
+      { title: "Status", rows: statusRows },
+      ...(view.active
+        ? [{
+            title: "Prompt",
+            rows: [{ key: "prompt", label: "Recurring prompt", value: promptPreview(view.prompt), valueStyle: "muted" as const, kind: "info" as const }],
+          }]
+        : []),
+      {
+        title: "Actions",
+        rows: view.active
+          ? [
+              { key: "edit", label: "Edit schedule", value: "open…", kind: "action" },
+              { key: "stop", label: "Stop loop", value: "confirm…", valueStyle: "warning", kind: "action" },
+            ]
+          : [
+              { key: "start", label: "Start a loop", value: "open…", kind: "action" },
+            ],
+      },
+    ],
+    detailLines: ["Ticks are session-scoped and stop with the session (in-session steer delivery)."],
+    idleMessage: "Use nested /loop arguments for scripts",
+    shortcuts: view.active
+      ? [
+          { key: "e", label: "edit", action: "edit" },
+          { key: "x", label: "stop", action: "stop" },
+        ]
+      : [
+          { key: "s", label: "start", action: "start" },
+        ],
+  };
+}

package/ui/settings-panel.ts

@@ -0,0 +1,393 @@
+/** pi-extension-builder SettingsPanel v0.1.0 — canonical source and vendored primitive. */
+import type { KeybindingsManager, Theme } from "@earendil-works/pi-coding-agent";
+import {
+  Input,
+  matchesKey,
+  truncateToWidth,
+  visibleWidth,
+  type Component,
+  type Focusable,
+  type KeyId,
+} from "@earendil-works/pi-tui";
+
+export type PanelRowKind = "toggle" | "input" | "cycle" | "action" | "info";
+export type PanelValueStyle = "accent" | "success" | "warning" | "error" | "muted" | "text";
+
+export interface PanelRow {
+  key: string;
+  label: string;
+  value: string;
+  kind: PanelRowKind;
+  rawValue?: string;
+  choices?: string[];
+  inputHint?: string;
+  valueStyle?: PanelValueStyle;
+  disabled?: boolean;
+}
+
+export interface PanelSection {
+  title: string;
+  rows: PanelRow[];
+}
+
+export interface PanelShortcut {
+  key: KeyId;
+  label: string;
+  action: string;
+}
+
+export interface PanelSnapshot {
+  title: string;
+  summaryLines?: string[];
+  sections: PanelSection[];
+  detailLines?: string[];
+  idleMessage?: string;
+  shortcuts?: PanelShortcut[];
+}
+
+export type PanelActionResult =
+  | { kind: "updated"; message?: string }
+  | { kind: "close"; action: string }
+  | { kind: "error"; message: string }
+  | { kind: "none" };
+
+export interface PanelResult {
+  action?: string;
+}
+
+export interface SettingsPanelHost {
+  theme: Theme;
+  keybindings: KeybindingsManager;
+  initialKey?: string;
+  snapshot(): PanelSnapshot;
+  /** Apply a canonical setting value. Return an error string or null. */
+  apply(key: string, rawValue: string): string | null;
+  activate(key: string): PanelActionResult | void;
+  requestRender(): void;
+  done(result: PanelResult): void;
+}
+
+type FlashKind = "error" | "success" | "info";
+interface Flash {
+  kind: FlashKind;
+  text: string;
+}
+
+/**
+ * Reusable, synchronous control panel.
+ *
+ * Business logic stays in the host. The panel owns only navigation, editing,
+ * rendering, and transient feedback. Async or destructive actions should
+ * close with an action result and be handled by the command adapter.
+ */
+export class SettingsPanel implements Component, Focusable {
+  private readonly host: SettingsPanelHost;
+  private snapshotValue: PanelSnapshot;
+  private cursor = 0;
+  private editingKey: string | null = null;
+  private input: Input | null = null;
+  private flash: Flash | null = null;
+  private _focused = false;
+
+  constructor(host: SettingsPanelHost) {
+    this.host = host;
+    this.snapshotValue = host.snapshot();
+    if (host.initialKey) this.focusRow(host.initialKey);
+    this.clampCursor();
+  }
+
+  get focused(): boolean {
+    return this._focused;
+  }
+
+  set focused(value: boolean) {
+    this._focused = value;
+    if (this.input) this.input.focused = value;
+  }
+
+  invalidate(): void {
+    this.input?.invalidate();
+  }
+
+  handleInput(data: string): void {
+    if (this.input) {
+      this.input.handleInput(data);
+      this.host.requestRender();
+      return;
+    }
+
+    const kb = this.host.keybindings;
+    if (kb.matches(data, "tui.select.cancel") || matchesKey(data, "q")) {
+      this.host.done({});
+      return;
+    }
+
+    if (kb.matches(data, "tui.select.up") || matchesKey(data, "k")) {
+      this.move(-1);
+    } else if (kb.matches(data, "tui.select.down") || matchesKey(data, "j")) {
+      this.move(1);
+    } else if (kb.matches(data, "tui.select.confirm") || matchesKey(data, "space")) {
+      this.activateCurrent();
+    } else {
+      const shortcut = this.snapshotValue.shortcuts?.find((candidate) => matchesKey(data, candidate.key));
+      if (!shortcut) return;
+      this.runAction(shortcut.action, shortcut.label);
+    }
+
+    this.host.requestRender();
+  }
+
+  render(width: number): string[] {
+    const t = this.host.theme;
+    const lines: string[] = [this.topBorder(width, this.snapshotValue.title)];
+
+    for (const line of this.snapshotValue.summaryLines ?? []) {
+      lines.push(this.boxLine(t.fg("muted", ` ${line}`), width));
+    }
+
+    const selectedKey = this.selectableRows()[this.cursor]?.key;
+    for (const section of this.snapshotValue.sections) {
+      lines.push(this.boxLine(t.fg("accent", t.bold(` ${section.title}`)), width));
+      for (const row of section.rows) {
+        lines.push(this.renderRow(row, row.key === selectedKey, width));
+      }
+    }
+
+    for (const line of this.snapshotValue.detailLines ?? []) {
+      lines.push(this.boxLine(t.fg("dim", ` ${line}`), width));
+    }
+
+    lines.push(this.boxLine(this.renderMessageLine(), width));
+    const shortcutLine = this.renderShortcutLine();
+    if (shortcutLine) lines.push(this.boxLine(t.fg("dim", ` ${shortcutLine}`), width));
+    lines.push(this.boxLine(t.fg("dim", ` ${this.renderNavigationLine()}`), width));
+    lines.push(this.bottomBorder(width));
+    return lines;
+  }
+
+  private allRows(): PanelRow[] {
+    return this.snapshotValue.sections.flatMap((section) => section.rows);
+  }
+
+  private selectableRows(): PanelRow[] {
+    return this.allRows().filter((row) => row.kind !== "info" && !row.disabled);
+  }
+
+  private focusRow(key: string): void {
+    const index = this.selectableRows().findIndex((row) => row.key === key);
+    if (index >= 0) this.cursor = index;
+  }
+
+  private clampCursor(): void {
+    const rows = this.selectableRows();
+    this.cursor = Math.max(0, Math.min(this.cursor, Math.max(0, rows.length - 1)));
+  }
+
+  /** Refresh derived rows while preserving the current selection when possible. */
+  refresh(preferredKey?: string): void {
+    const currentKey = preferredKey ?? this.selectableRows()[this.cursor]?.key;
+    this.snapshotValue = this.host.snapshot();
+    if (currentKey) this.focusRow(currentKey);
+    this.clampCursor();
+  }
+
+  private move(delta: number): void {
+    const rows = this.selectableRows();
+    if (!rows.length) return;
+    this.cursor = (this.cursor + delta + rows.length) % rows.length;
+    this.flash = null;
+  }
+
+  private activateCurrent(): void {
+    const row = this.selectableRows()[this.cursor];
+    if (!row) return;
+
+    if (row.kind === "input") {
+      this.startEdit(row.key, row.rawValue ?? "");
+      return;
+    }
+
+    if (row.kind === "toggle") {
+      this.applyValue(row, row.rawValue === "true" ? "false" : "true");
+      return;
+    }
+
+    if (row.kind === "cycle") {
+      const choices = row.choices ?? [];
+      if (!choices.length) return;
+      const current = Math.max(0, choices.indexOf(row.rawValue ?? ""));
+      this.applyValue(row, choices[(current + 1) % choices.length] ?? choices[0] ?? "");
+      return;
+    }
+
+    if (row.kind === "action") this.runAction(row.key, row.label);
+  }
+
+  private applyValue(row: PanelRow, value: string): void {
+    const error = this.host.apply(row.key, value);
+    if (error) {
+      this.flash = { kind: "error", text: error };
+      return;
+    }
+
+    this.refresh(row.key);
+    const fresh = this.allRows().find((candidate) => candidate.key === row.key);
+    this.flash = { kind: "success", text: `${row.label}: ${fresh?.value ?? value}` };
+  }
+
+  private runAction(key: string, label: string): void {
+    const result = this.host.activate(key) ?? { kind: "none" as const };
+    if (result.kind === "close") {
+      this.host.done({ action: result.action });
+      return;
+    }
+    if (result.kind === "error") {
+      this.flash = { kind: "error", text: result.message };
+      return;
+    }
+    if (result.kind === "updated") {
+      this.refresh(key);
+      this.flash = { kind: "success", text: result.message ?? `${label} updated` };
+      return;
+    }
+    this.flash = { kind: "info", text: label };
+  }
+
+  private startEdit(key: string, initialValue: string): void {
+    this.editingKey = key;
+    this.input = new Input();
+    this.input.focused = this._focused;
+    this.input.setValue(initialValue);
+    // A fresh Input keeps its cursor at 0 after setValue(); move to End so a
+    // prefilled setting edits naturally.
+    this.input.handleInput("\x1b[F");
+    this.flash = null;
+
+    this.input.onSubmit = (value) => {
+      const row = this.allRows().find((candidate) => candidate.key === key);
+      if (!row) {
+        this.cancelEdit();
+        return;
+      }
+      const canonical = value.trim();
+      const error = this.host.apply(key, canonical);
+      if (error) {
+        this.flash = { kind: "error", text: error };
+        this.host.requestRender();
+        return;
+      }
+      this.input = null;
+      this.editingKey = null;
+      this.refresh(key);
+      const fresh = this.allRows().find((candidate) => candidate.key === key);
+      this.flash = { kind: "success", text: `${row.label}: ${fresh?.value ?? canonical}` };
+      this.host.requestRender();
+    };
+
+    this.input.onEscape = () => {
+      this.cancelEdit();
+      this.host.requestRender();
+    };
+  }
+
+  private cancelEdit(): void {
+    this.input = null;
+    this.editingKey = null;
+    this.flash = { kind: "info", text: "Edit cancelled" };
+  }
+
+  private renderRow(row: PanelRow, selected: boolean, width: number): string {
+    const t = this.host.theme;
+    const innerWidth = Math.max(1, width - 2);
+    const selectable = row.kind !== "info" && !row.disabled;
+    const prefix = selected ? t.fg("accent", " › ") : "   ";
+    const labelColor = row.disabled ? "dim" : selected ? "accent" : row.kind === "info" ? "muted" : "text";
+    const label = t.fg(labelColor, row.label);
+
+    if (this.editingKey === row.key && this.input) {
+      const left = `${prefix}${label}: `;
+      const available = Math.max(1, innerWidth - visibleWidth(left) - 1);
+      this.input.focused = this._focused;
+      const inputLine = this.input.render(available)[0] ?? "";
+      return this.boxLine(`${left}${inputLine}`, width);
+    }
+
+    const value = t.fg(this.valueColor(row), row.value);
+    const left = `${selectable ? prefix : "   "}${label}`;
+    const gap = Math.max(1, innerWidth - visibleWidth(left) - visibleWidth(value) - 2);
+    return this.boxLine(`${left}${" ".repeat(gap)}${value} `, width);
+  }
+
+  private renderMessageLine(): string {
+    const t = this.host.theme;
+    if (this.flash) {
+      const color = this.flash.kind === "error" ? "error" : this.flash.kind === "success" ? "success" : "muted";
+      return t.fg(color, ` ${this.flash.text}`);
+    }
+    if (this.editingKey) {
+      const row = this.allRows().find((candidate) => candidate.key === this.editingKey);
+      return t.fg("muted", ` ${row?.inputHint ?? "Enter saves · Esc cancels"}`);
+    }
+    return t.fg("dim", ` ${this.snapshotValue.idleMessage ?? "Changes save immediately"}`);
+  }
+
+  private renderShortcutLine(): string | null {
+    const shortcuts = this.snapshotValue.shortcuts ?? [];
+    if (!shortcuts.length) return null;
+    return shortcuts.map((shortcut) => `${shortcut.key} ${shortcut.label}`).join(" · ");
+  }
+
+  private renderNavigationLine(): string {
+    const kb = this.host.keybindings;
+    const up = this.bindingText(kb.getKeys("tui.select.up"), "↑");
+    const down = this.bindingText(kb.getKeys("tui.select.down"), "↓");
+    const confirm = this.bindingText(kb.getKeys("tui.select.confirm"), "enter");
+    const cancel = this.bindingText(kb.getKeys("tui.select.cancel"), "esc");
+    return `${up}/${down}/jk move · ${confirm} select · ${cancel}/q close`;
+  }
+
+  private bindingText(keys: readonly string[], fallback: string): string {
+    const first = keys[0];
+    if (!first) return fallback;
+    return first
+      .replace(/^up$/, "↑")
+      .replace(/^down$/, "↓")
+      .replace(/^left$/, "←")
+      .replace(/^right$/, "→")
+      .replace(/^escape$/, "esc")
+      .replace(/^return$/, "enter");
+  }
+
+  private valueColor(row: PanelRow): Parameters<Theme["fg"]>[0] {
+    if (row.valueStyle) return row.valueStyle;
+    if (row.disabled) return "dim";
+    if (row.kind === "toggle") return row.rawValue === "true" ? "success" : "muted";
+    if (row.kind === "action") return "accent";
+    return "text";
+  }
+
+  private boxLine(content: string, width: number): string {
+    const t = this.host.theme;
+    if (width <= 1) return truncateToWidth(content, Math.max(1, width), "", true);
+    const innerWidth = Math.max(0, width - 2);
+    const clipped = truncateToWidth(content, innerWidth, "…", true);
+    const padded = clipped + " ".repeat(Math.max(0, innerWidth - visibleWidth(clipped)));
+    return t.fg("border", "│") + padded + t.fg("border", "│");
+  }
+
+  private topBorder(width: number, title: string): string {
+    const t = this.host.theme;
+    if (width <= 1) return t.fg("borderAccent", "─".repeat(Math.max(1, width)));
+    const innerWidth = Math.max(0, width - 2);
+    const styledTitle = t.fg("accent", t.bold(` ${title} `));
+    const clippedTitle = truncateToWidth(styledTitle, innerWidth, "", false);
+    const tail = "─".repeat(Math.max(0, innerWidth - visibleWidth(clippedTitle)));
+    return t.fg("border", "╭") + clippedTitle + t.fg("border", `${tail}╮`);
+  }
+
+  private bottomBorder(width: number): string {
+    const t = this.host.theme;
+    if (width <= 1) return t.fg("border", "─".repeat(Math.max(1, width)));
+    return t.fg("border", `╰${"─".repeat(Math.max(0, width - 2))}╯`);
+  }
+}