@alphacoder-v0/pi-loops 0.22.7 → 0.24.0

package/src/cli.ts

@@ -8,26 +8,35 @@
  *   pi-loops export [--session <id>] [--cwd <dir>] [--output <file>] [--exclude-triggers]
  *   pi-loops import <file> [--cwd <dir>] [--activate-triggers=off|ask|on]
  */
-import { spawn, spawnSync } from "node:child_process";
+import { execFileSync, spawn, spawnSync } from "node:child_process";
+import { plural } from "./job-lines.ts";
 import * as fs from "node:fs";
+import * as net from "node:net";
 import * as os from "node:os";
 import * as path from "node:path";
 import * as readline from "node:readline";
-import { fileURLToPath } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
 import { SessionManager, getAgentDir } from "@earendil-works/pi-coding-agent";
 import { applyImport, automationOf, exportSession, defaultExportPath, importSession, inspectArchive, offerToEnable, parseActivateMode } from "./archive.ts";
-import { askHost, renderHostSnapshot } from "./host-control-channel.ts";
+import { API_KEY_REFUSAL, CONTROL_TIMEOUT_MS, COPY_KEY_MS, askHost, hostSocketPath, openConversations, renderHostSnapshot, requestLines, requestQueues, ringHost } from "./host-control-channel.ts";
+import { heldTurnFor, stopRow } from "./engine.ts";
+import { LeaseStore, procStart, sessionFileName } from "./lease.ts";
+import { RequestStore } from "./requests.ts";
 import { FINDING_FIELDS, Inbox, type InboxEntry, inProject, resolveInboxRef } from "./inbox.ts";
-import { sameProject } from "./presence.ts";
+import { cardLine, cardOrigin, inboxCard } from "./inbox-card.ts";
+import { sameProject } from "./paths.ts";
 import { redact } from "./redact.ts";
-import { liveHost, stopHost } from "./host-control.ts";
+import { crashPaused, crashPauseText, ensureHost, HOST_LOG, hostCommand, hostServiceAlive, LEAVE_WAIT_MS, readHostService, RESTART_WAIT_LINE, readSpawnLog, removeHostService, type EnsureHostOptions, type HostServiceRecord } from "./host-control.ts";
+import { loadConfig, pageBindPort } from "./config.ts";
+import { writeUiPref } from "./ui-prefs.ts";
 import { type UiPrefs, clearUiPref, readUiPrefs } from "./ui-prefs.ts";
-import { JobStore, defaultLoopsDir } from "./store.ts";
-import { automationBadge, previewText, readSessionHead } from "./session-head.ts";
+import { JobStore, defaultLoopsDir, homeLoopsDir } from "./store.ts";
+import { automationBadge, previewText, readSessionHead, shortSessionId } from "./session-head.ts";
 import { AUTONOMY_LEVELS, type AutonomyLevel, INSTALL_ROOT, TRACKER_FILE, addLineFor, ensureExcluded, installDirFor, installFiles, installedRecipes, listRecipes, loadRecipe, planInstall, playbookFiles, readRecord, resolveRecipeRef } from "./recipe.ts";
 import { TriggerStore } from "./triggers.ts";
 import { PI_LOOPS_VERSION } from "./version.ts";
-import { stamp } from "./schedule.ts";
+import { formatLocal, stamp } from "./schedule.ts";
+import { canonicalDir } from "./trust.ts";
 
 /**
  * Which front end `pi-loops` opens when you do not say. A browser is the better window when one is
@@ -44,79 +53,96 @@ export function resolveUiMode(input: { web: boolean; tui: boolean; interactiveTt
 	return input.remoteTty ? "terminal" : "web";
 }
 
+/** pi's flags that run it without drawing in a terminal: one answer, a protocol, or a listing. */
+const PI_NO_TERMINAL_FLAGS = new Set(["-p", "--print", "--mode", "--help", "-h", "--version", "-v", "--list-models", "--export"]);
+
+/**
+ * The line `pi-loops` says, and exits 1 on, when it would start pi in a terminal that is not there:
+ * no `--web` or `--tui`, stdin or stdout not a terminal, and nothing in pi's arguments that runs
+ * without one. Started anyway, pi had nowhere to draw and exited with nothing said.
+ */
+export function noTerminalRefusal(input: { web: boolean; tui: boolean; interactiveTty: boolean; piArgs: readonly string[] }): string | undefined {
+	if (input.web || input.tui || input.interactiveTty) return undefined;
+	if (input.piArgs.some((a) => PI_NO_TERMINAL_FLAGS.has(a.split("=")[0]))) return undefined;
+	return `pi-loops: there is no terminal here to open pi in; run pi-loops --web to open the page, or pi-loops -- -p "<prompt>" for one answer`;
+}
+
 /** ssh and mosh set at least one of these; opening a browser on the far end helps nobody. */
 export function isRemoteTty(env: NodeJS.ProcessEnv = process.env): boolean {
 	return ["SSH_CONNECTION", "SSH_CLIENT", "SSH_TTY", "MOSH_CONNECTION"].some((k) => !!env[k]);
 }
 
-/** Flags `pi-loops` reads for itself when launching; everything else is pi's. */
+/**
+ * Flags `pi-loops` reads for itself when launching; everything else is pi's. `port`, `host`,
+ * `allow-host` and `no-auth` are claimed only to be refused: the page outlives the command now, so
+ * its address lives in config.toml.
+ */
 const LAUNCH_FLAGS = new Set(["web", "tui", "port", "host", "allow-host", "open", "no-open", "no-auth", "loops-dir", "help"]);
 /** The ones that take the next argument as their value. */
 const LAUNCH_FLAGS_WITH_VALUE = new Set(["port", "host", "allow-host", "loops-dir"]);
 
 /**
  * Split `pi-loops <flags> <rest>` into ours and pi's. Unknown flags go to pi on purpose: the point
- * of this command is that you can type what you would have typed after `pi`.
+ * of this command is that you can type what you would have typed after `pi`. With `--`, everything
+ * after it is pi's, and a flag before it that is not ours is `misplaced`: it used to be dropped
+ * without a word, which lost a `--session` and opened a new conversation instead.
  */
-export function splitLaunchArgs(argv: string[]): { ours: string[]; pi: string[] } {
+export function splitLaunchArgs(argv: string[]): { ours: string[]; pi: string[]; misplaced: string[] } {
 	const dashdash = argv.indexOf("--");
-	if (dashdash !== -1) return { ours: argv.slice(0, dashdash), pi: argv.slice(dashdash + 1) };
+	const before = dashdash === -1 ? argv : argv.slice(0, dashdash);
 	const ours: string[] = [];
-	const pi: string[] = [];
-	for (let i = 0; i < argv.length; i++) {
-		const arg = argv[i];
+	const rest: string[] = [];
+	for (let i = 0; i < before.length; i++) {
+		const arg = before[i];
 		const name = arg.startsWith("--") ? arg.slice(2).split("=")[0] : undefined;
 		if (name && LAUNCH_FLAGS.has(name)) {
 			ours.push(arg);
-			// `--port 4173` takes a value; `--web` does not.
-			if (!arg.includes("=") && LAUNCH_FLAGS_WITH_VALUE.has(name) && argv[i + 1] && !argv[i + 1].startsWith("-")) ours.push(argv[++i]);
+			// `--loops-dir <dir>` takes a value; `--web` does not.
+			if (!arg.includes("=") && LAUNCH_FLAGS_WITH_VALUE.has(name) && before[i + 1] && !before[i + 1].startsWith("-")) ours.push(before[++i]);
 			continue;
 		}
-		pi.push(arg);
+		rest.push(arg);
 	}
-	return { ours, pi };
+	if (dashdash === -1) return { ours, pi: rest, misplaced: [] };
+	return { ours, pi: argv.slice(dashdash + 1), misplaced: rest };
 }
 
-export const CLI_USAGE = [
-	"pi-loops [--web | --tui] [--port <n>] [--no-auth] [<pi flags>]",
-	"    Start a session. On a local terminal that means the browser UI; over ssh, and anywhere",
-	"    without a terminal, it means pi itself. --web and --tui say which, and anything this",
-	"    command does not recognise is passed to pi (pi-loops --model anthropic/claude-opus-5).",
-	"    --no-auth drops the token: the browser UI is then open to anything on this machine.",
-	"    --host <addr> binds somewhere other than loopback, so a phone can reach it; the terminal",
-	"    prints a six-digit pairing code for that device. --allow-host <name,...> accepts a proxy,",
-	"    and a name resolved by public DNS puts the token back in charge of keeping strangers out.",
+/** A command typed wrong: the entry point prints the message and that command's usage, and exits 2. */
+export class UsageError extends Error {}
+
+const CLI_USAGE = [
+	"pi-loops [--web | --tui] [--no-open] [--loops-dir <dir>] [<pi flags>] [-- <pi flags>]",
+	"    Open a conversation: the browser page on a local terminal, pi itself over ssh (pi-loops web and pi-loops tui say which).",
 	"",
 	"pi-loops upgrade [--check]",
-	"    Install the newest release from the repository this copy came from. --check only looks.",
+	"    Install the newest release from the repository this copy came from.",
 	"",
 	"pi-loops install-launcher [--dir <dir>]",
-	"    Put a `pi-loops` launcher on your PATH, so this command works from anywhere.",
+	"    Put a `pi-loops` launcher on your PATH.",
 	"",
 	"pi-loops export [--session <id>] [--cwd <dir>] [--output <file>] [--exclude-triggers]",
 	"    Bundle a session and its automation into a .pisession archive.",
-	"    Default session: the newest one for --cwd (default: the current directory).",
 	"",
 	"pi-loops import <file> [--cwd <dir>] [--activate-triggers=off|ask|on]",
-	"    Restore an archive into --cwd (default: the current directory).",
-	"    --activate-triggers: off never asks, on activates, ask (the default) prompts after the import.",
+	"    Restore an archive into a project.",
 	"",
 	"pi-loops sessions [--all] [--limit <n>]",
-	"    List sessions, newest first: short id, when it started, its automation, what was first said in it.",
+	"    List sessions, newest first.",
 	"",
 	"pi-loops inspect <file>",
 	"    Show what an archive contains without writing anything.",
 	"",
-	"pi-loops host status | abort <run-id|trace-id> | stop",
-	"    Look in on the background host that keeps the clock while no pi is open, or interrupt it.",
+	"pi-loops start | stop | restart | status [--url] | abort <run-id|trace-id|session-id>",
+	"    Run, stop or check pi-loops in the background, or stop one run or turn.",
+	"",
+	"pi-loops pair",
+	"    Print a one-use code that signs another device in to the page.",
 	"",
 	"pi-loops recipe list | show <name|path> | add <name|path> [--cwd <dir>] [--level report|propose|act] [--overwrite]",
-	"    The packaged recipes; what one installs; copy its playbooks into a project (.agents/skills/<name>/).",
-	"    The setup script and the jobs need a pi open in the project: /recipe add <name> finds the copies and finishes.",
+	"    List, show or install the packaged recipes.",
 	"",
 	"pi-loops inbox list [--all] [--cwd <dir>] | claim <id> | dismiss <id> [--reason <text>]   [--json]",
-	"    The triage inbox with no pi open: what /inbox lists, and the two things it does to a finding.",
-	"    --json prints the shape docs/downstream.md fixes for programs.",
+	"    List, claim or dismiss findings with no pi open.",
 ].join("\n");
 
 /**
@@ -184,9 +210,19 @@ export function pickSession(sessions: SessionFile[], opts: { id?: string; cwd: s
 		if (byPrefix.length > 1) throw new Error(`session id ${opts.id} is ambiguous (${byPrefix.length} matches)`);
 		throw new Error(`no session with id ${opts.id}`);
 	}
+	// The nearest directory's newest session: this directory's own, else the closest one above or below
+	// it, which finds the project's session from a subdirectory without reaching past it to an
+	// unrelated parent (a `/tmp` session, say) that happens to be newer.
+	const cwd = canonicalDir(opts.cwd);
+	const distance = (dir: string): number => {
+		const d = canonicalDir(dir);
+		const rel = path.relative(d, cwd) || path.relative(cwd, d);
+		return rel ? rel.split(path.sep).length : 0;
+	};
 	const here = sessions.filter((s) => sameProject(s.cwd, opts.cwd));
 	if (!here.length) throw new Error(`no sessions recorded for ${opts.cwd}; pass --session <id>`);
-	return here[0];
+	// Sorting is stable, so within one distance the newest (the order `sessions` came in) stays first.
+	return [...here].sort((a, b) => distance(a.cwd) - distance(b.cwd))[0];
 }
 
 interface Parsed {
@@ -238,19 +274,25 @@ function runChild(command: string, args: string[], env?: NodeJS.ProcessEnv): Pro
 			process.stderr.write(`pi-loops: could not start ${command}: ${err?.message ?? err}\n`);
 			resolve(1);
 		});
-		// A signal that reaches us reaches this child too: the launcher and what it starts — pi in a
-		// terminal, or `web.mjs` — share the terminal's process group, so Ctrl-C arrives at both. The
-		// browser front end starts its own pi *outside* that group on purpose (see `src/web.mjs`), so
-		// that pi is ended by web.mjs asking it to quit rather than by the group's SIGINT, and gets to
-		// hand the clock to a headless host on the way out. Either way, wait for the child to finish
-		// rather than exiting first and leaving a session with no terminal attached to it.
+		// A signal that reaches us reaches this child too: pi in a terminal shares the terminal's
+		// process group, so Ctrl-C arrives at both. Wait for it to finish rather than exiting first and
+		// leaving a session with no terminal attached to it. The browser page's pis are not started
+		// here: they are children of pi-loops in the background.
 		child.on("exit", (code, signal) => resolve(signal ? 1 : (code ?? 0)));
 	});
 }
 
 export async function runCli(argv: string[], out: (line: string) => void = console.log): Promise<number> {
-	if (cliRoute(argv) === "launch") return launch(argv, out);
+	const route = cliRoute(argv);
+	if (route === "launch") return launch(argv, out);
+	if (route === "help") {
+		out(usageFor(argv[0]));
+		return 0;
+	}
 	const { command, positional, flags } = parseCliArgs(argv);
+	// `host` is the 0.22.8 spelling of the service verbs; `stop help` asks how stop works.
+	const [verb, words] = command === "host" ? [positional[0] ?? "status", positional.slice(1)] : [command, positional];
+	if (!(SERVICE_VERBS.has(verb) && words.includes("help"))) refuseUnread(verb, words, flags);
 	const str = (name: string): string | undefined => {
 		const v = flags.get(name);
 		return typeof v === "string" ? v : undefined;
@@ -270,7 +312,7 @@ export async function runCli(argv: string[], out: (line: string) => void = conso
 		// negative offset or a fraction, and change what is listed without ever saying so.
 		const limitFlag = flags.get("limit");
 		if (limitFlag !== undefined && (typeof limitFlag !== "string" || !/^\d+$/.test(limitFlag) || Number(limitFlag) < 1))
-			throw new Error(`--limit takes a whole number of sessions ≥ 1; got ${limitFlag === true ? "nothing" : JSON.stringify(limitFlag)}`);
+			throw new UsageError(`--limit takes a whole number of sessions ≥ 1; got ${limitFlag === true ? "nothing" : JSON.stringify(limitFlag)}`);
 		const limit = limitFlag === undefined ? 20 : Number(limitFlag);
 		// `pickSession` refuses an unknown id, and there was no way to discover one.
 		const sessions = listSessions(path.join(agentDir, "sessions"));
@@ -293,7 +335,7 @@ export async function runCli(argv: string[], out: (line: string) => void = conso
 	if (command === "inspect") {
 		// What is in this archive, without writing anything.
 		const file = positional[0];
-		if (!file) throw new Error("inspect needs an archive path");
+		if (!file) throw new UsageError("inspect needs an archive path");
 		const info = inspectArchive(path.resolve(file));
 		out(`${plain(info.schema)}  exported ${plain(info.createdAt)}  from ${plain(info.sourceCwd)}`);
 		// The counts come out of the same manifest and are only numbers if it says so.
@@ -324,7 +366,7 @@ export async function runCli(argv: string[], out: (line: string) => void = conso
 
 	if (command === "import") {
 		const file = positional[0];
-		if (!file) throw new Error("import needs an archive path");
+		if (!file) throw new UsageError("import needs an archive path");
 		const mode = parseActivateMode(str("activate-triggers"));
 		const jobStore = new JobStore(loopsDir);
 		const triggerStore = new TriggerStore(loopsDir);
@@ -348,55 +390,18 @@ export async function runCli(argv: string[], out: (line: string) => void = conso
 			if (process.stdin.isTTY) out(detail); // what the dialog shows above the question
 			return askYesNo(question);
 		} : undefined);
-		if (enabled.jobs || enabled.rules) out(`enabled ${enabled.jobs} cron job(s) and ${enabled.rules} trigger rule(s)`);
+		if (enabled.jobs || enabled.rules) out(`enabled ${enabled.jobs} ${enabled.jobs === 1 ? "loop" : "loops"} and ${enabled.rules} ${enabled.rules === 1 ? "rule" : "rules"}`);
 		else if (!summary.automationEnabled && (summary.jobs.length || summary.rules.length)) out("automation is disabled; enable it with /cron enable <id> or re-import with --activate-triggers=on");
 		return 0;
 	}
 
-	if (command === "host") {
-		const sub = positional[0] ?? "status";
-		if (sub === "status") {
-			const res = await askHost(loopsDir, { op: "status" });
-			if (!res) {
-				// No answer is not the same as no host: one wedged on a hung MCP read still holds the
-				// record. Fall back to it, so the user gets a pid and a log to look at.
-				const rec = liveHost(loopsDir);
-				if (rec) {
-					out(`background host pid ${rec.pid} on ${rec.host} is not answering (started ${rec.startedAt})`);
-					out(`  log: ${path.join(loopsDir, "host.log")}`);
-					out(`  stop it with: pi-loops host stop`);
-					return 1;
-				}
-				out("no background host is running (it runs only while no pi is open)");
-				return 1;
-			}
-			if (!res.ok) throw new Error(res.error);
-			out("background host");
-			for (const line of renderHostSnapshot(res.snapshot!)) out(line);
-			return 0;
-		}
-		if (sub === "abort") {
-			const ref = positional[1];
-			if (!ref) throw new Error("host abort needs a run id or a trigger trace id");
-			// A run id is `run-<32 hex>`; anything else is treated as a trigger trace.
-			const res = await askHost(loopsDir, ref.startsWith("run-") ? { op: "abort", runId: ref } : { op: "abort", traceId: ref });
-			if (!res) throw new Error("no background host is running");
-			if (!res.ok) throw new Error(res.error);
-			out(res.aborted ? `aborted ${ref}` : `nothing running with id ${ref}`);
-			return res.aborted ? 0 : 1;
-		}
-		if (sub === "stop") {
-			const res = await askHost(loopsDir, { op: "stop" });
-			if (res?.ok) {
-				out("asked the background host to stop");
-				return 0;
-			}
-			// It did not answer; SIGTERM the recorded pid, which is what `/cron host stop` does.
-			const pid = stopHost(loopsDir);
-			out(pid ? `background host (pid ${pid}) was not answering; sent SIGTERM` : "no background host is running");
-			return pid ? 0 : 1;
-		}
-		throw new Error(`unknown host command ${JSON.stringify(sub)}`);
+	// 0.22.8 shipped `pi-loops host status|abort|stop`: they stay spellings of the same commands.
+	if (SERVICE_VERBS.has(command) || command === "host") {
+		const code = await serviceCommand(verb, words, flags, loopsDir, out);
+		// In 0.22.8 this spelling stopped the running process and recorded nothing; a script written then
+		// should learn that it now pauses everything.
+		if (command === "host" && verb === "stop" && code === 0 && !flags.has("help") && !words.includes("help")) out("pi-loops host stop: stopped; nothing runs until `pi-loops start` (every loop, every rule, and the plain jobs of closed conversations)");
+		return code;
 	}
 
 	const asked = command && command !== "help" && command !== "--help";
@@ -411,12 +416,17 @@ export async function runCli(argv: string[], out: (line: string) => void = conso
 		const spec = upgradeSpec(packageRoot(), manifest().name ?? "", agentDir, "<newer release>", configuredNpmSource(packageRoot(), manifest().name ?? ""));
 		out(`if you expected it, the copy you are running may be older than the command: ${spec ? `pi install ${spec}` : checkoutUpgradeHint()}`);
 		out("");
+		out("pi-loops --help lists the commands");
+		return 2;
 	}
 	out(CLI_USAGE);
-	return asked ? 2 : 0;
+	return 0;
 }
 
-const SUBCOMMANDS = new Set(["export", "import", "sessions", "inspect", "host", "recipe", "inbox", "web", "upgrade", "install-launcher", "help"]);
+/** What runs loops while no pi is open, started, stopped and looked at by name. */
+const SERVICE_VERBS = new Set(["start", "stop", "restart", "status", "abort", "pair"]);
+
+const SUBCOMMANDS = new Set(["export", "import", "sessions", "inspect", "start", "stop", "restart", "status", "abort", "pair", "host", "recipe", "inbox", "web", "upgrade", "install-launcher", "help"]);
 
 /**
  * `pi-loops inbox`: `/inbox list|claim|dismiss` for a shell with no pi open, and — with `--json` —
@@ -449,7 +459,12 @@ async function inboxCommandBody(positional: string[], opts: { all: boolean; json
 			return 0;
 		}
 		if (!entries.length) out(opts.all ? "inbox: nothing new on this machine" : `inbox: nothing new in ${cwd} (--all lists every project)`);
-		for (const e of entries) out(findingLine(e));
+		const names = new Map(new JobStore(loopsDir).load().map((j) => [j.id, j.name]));
+		const ctx = { loopName: (id: string) => names.get(id) };
+		for (const e of entries) {
+			const card = inboxCard(e, ctx);
+			if (card) out(plain(cardLine(card, `${e.id}  `, `  (${path.basename(e.cwd) || e.cwd || "—"}, ${cardOrigin(card)}, ${formatLocal(Date.parse(e.created_at))})`)));
+		}
 		return 0;
 	}
 	if (sub === "claim" || sub === "dismiss") {
@@ -462,8 +477,12 @@ async function inboxCommandBody(positional: string[], opts: { all: boolean; json
 		// digits only pick the wording, since "no entry matching '1'" reads like a missing finding.
 		const entry = resolveInboxRef(inbox.listNew(), ref);
 		if (!entry) return fail(/^\d+$/.test(ref.trim()) ? `inbox ${sub} takes a finding id (inb-…) or a prefix of one, not a number` : `no new inbox entry matching '${ref}'`);
-		const updated = await inbox.setStatus(entry.id, sub === "claim" ? "claimed" : "dismissed", sub === "claim" ? "cli" : undefined, opts.reason);
-		if (!updated) return fail(`inbox entry ${entry.id} is gone`);
+		// Resolved outside the lock; `decide` checks `new` again under it, so a claim racing this one
+		// (another shell, a terminal, the page) wins or loses as a whole.
+		const decided = await inbox.decide(entry.id, sub === "claim" ? "claimed" : "dismissed", sub === "claim" ? { by: "cli" } : { reason: opts.reason });
+		if ("missing" in decided) return fail(`inbox entry ${entry.id} is gone`);
+		if ("already" in decided) return fail(`inbox entry ${entry.id} is already ${decided.already}`);
+		const updated = decided.ok;
 		out(opts.json ? JSON.stringify({ finding: findingJson(updated) }) : `${updated.status} ${updated.id}`);
 		return 0;
 	}
@@ -482,12 +501,6 @@ function findingJson(e: InboxEntry): Record<string, unknown> {
 	return out;
 }
 
-/** A person's line: the full id (it is what `claim` takes), the finding, where and when it came from. */
-function findingLine(e: InboxEntry): string {
-	const mark = `${e.kind === "checkpoint" ? "⚑ " : ""}${e.verified ? "✓ " : ""}`;
-	return `${e.id}  ${mark}${plain(redact(e.text))}  (${path.basename(e.cwd) || e.cwd || "—"}, ${e.source}, ${e.created_at})`;
-}
-
 /**
  * `pi-loops recipe`: the deterministic part of `/recipe`, for a shell with no pi open. `add` copies
  * the playbooks, lists the directory in `.git/info/exclude` and writes the record — and stops there:
@@ -503,7 +516,7 @@ async function recipeCommand(positional: string[], opts: { level?: string; overw
 		for (const r of packaged) {
 			const rec = installed.get(r.manifest.name);
 			const n = jobs.filter((j) => j.recipe === r.manifest.name).length;
-			out(`${r.manifest.name.padEnd(17)} ${(rec ? `installed: ${rec.level}, ${n} job(s)` : "—").padEnd(28)} ${r.manifest.summary}`);
+			out(`${r.manifest.name.padEnd(17)} ${rec ? `[installed: ${rec.level}, ${plural(n, "loop")}] ` : ""}${r.manifest.line ?? r.manifest.summary}`);
 		}
 		for (const rec of installed.values()) if (!packaged.some((r) => r.manifest.name === rec.recipe)) out(`${rec.recipe.padEnd(17)} installed from ${rec.source} (${rec.level})`);
 		if (!packaged.length && !installed.size) out("no recipes packaged, none installed here");
@@ -511,7 +524,7 @@ async function recipeCommand(positional: string[], opts: { level?: string; overw
 	}
 	if (sub === "show" || sub === "add") {
 		const ref = positional[1];
-		if (!ref) throw new Error(`recipe ${sub} needs a recipe name or a directory`);
+		if (!ref) throw new UsageError(`recipe ${sub} needs a recipe name or a directory`);
 		const resolved = resolveRecipeRef(ref, { cwd });
 		const recipe = loadRecipe(resolved.dir);
 		const m = recipe.manifest;
@@ -535,7 +548,7 @@ async function recipeCommand(positional: string[], opts: { level?: string; overw
 		const record = installFiles(recipe, cwd, level, { overwrite: opts.overwrite, source: resolved.source });
 		const excluded = ensureExcluded(cwd, rel);
 		if (m.needsTracker && fs.existsSync(path.join(cwd, TRACKER_FILE))) ensureExcluded(cwd, TRACKER_FILE, "file");
-		out(`copied ${record.files.length} file(s) → ${plan.targetDir}/ (level ${level}${opts.level ? "" : ", the lowest; --level to choose"})`);
+		out(`copied ${plural(record.files.length, "file")} → ${plan.targetDir}/ (level ${level}${opts.level ? "" : ", the lowest; --level to choose"})`);
 		for (const f of plan.changed) out(`  ${f}: ${opts.overwrite ? "overwritten" : "kept as edited (--overwrite replaces it)"}`);
 		out(excluded === "no-git" ? "not a git repository: nothing to exclude" : `.git/info/exclude: ${excluded === "added" ? "added" : "already listed"}`);
 		if (m.needsTracker && !fs.existsSync(path.join(cwd, TRACKER_FILE))) out(`${m.name} reads docs/agents/issue-tracker.md and this project has none: /recipe add ${m.name} in pi writes it with you first`);
@@ -751,17 +764,70 @@ async function upgrade(checkOnly: boolean, out: (line: string) => void): Promise
  *
  * A bare word is never passed on, though: `pi-loops exprot` is a typo, and turning it into an
  * argument for pi would start a session and hide the mistake, which is the worst of both.
+ *
+ * `-h` or `--help` anywhere before a `--` asks how a subcommand works, and asking must not run it:
+ * `install-launcher --help` wrote the launcher and `upgrade --help` ran the upgrade. After `--`
+ * they are pi's.
  */
-export function cliRoute(argv: string[]): "launch" | "subcommand" {
+export function cliRoute(argv: string[]): "launch" | "subcommand" | "help" {
 	const first = argv[0];
 	if (first === undefined) return "launch";
-	if (first === "--help" || first === "-h" || first === "help") return "subcommand";
+	if (first === "--help" || first === "-h" || first === "help") return "help";
 	if (first.startsWith("-")) return "launch";
+	const dashdash = argv.indexOf("--");
+	const before = dashdash === -1 ? argv.slice(1) : argv.slice(1, dashdash);
+	if (Object.hasOwn(USAGE_SECTIONS, first) && before.some((a) => a === "-h" || a === "--help")) return "help";
 	// Known or not, a word goes down the subcommand path — which is where the unknown-command
 	// message lives, and `web` and `tui` are handled there as launch words.
 	return "subcommand";
 }
 
+/** Each subcommand, and the line that starts its section of `CLI_USAGE`. */
+const USAGE_SECTIONS: Record<string, string> = {
+	web: "pi-loops [--web", tui: "pi-loops [--web", upgrade: "pi-loops upgrade", "install-launcher": "pi-loops install-launcher",
+	export: "pi-loops export", import: "pi-loops import", sessions: "pi-loops sessions", inspect: "pi-loops inspect",
+	start: "pi-loops start | stop", stop: "pi-loops start | stop", restart: "pi-loops start | stop", status: "pi-loops start | stop",
+	abort: "pi-loops start | stop", host: "pi-loops start | stop", pair: "pi-loops pair", recipe: "pi-loops recipe", inbox: "pi-loops inbox",
+};
+
+/** The flags every subcommand reads. */
+const GLOBAL_FLAGS = new Set(["cwd", "help"]);
+
+/** The flags each subcommand reads beside the global ones; any other is refused, not ignored. */
+const VERB_FLAGS: Record<string, readonly string[]> = {
+	upgrade: ["check"], "install-launcher": ["dir"], import: ["activate-triggers"], export: ["session", "output", "exclude-triggers"],
+	sessions: ["limit", "all"], recipe: ["level", "overwrite"], inbox: ["all", "json", "reason"], start: ["foreground"], status: ["url"],
+	inspect: [], stop: [], restart: [], abort: [], pair: [],
+};
+
+/** How many words each subcommand reads after its name. */
+const VERB_POSITIONALS: Record<string, number> = {
+	upgrade: 0, "install-launcher": 0, export: 0, sessions: 0, start: 0, stop: 0, restart: 0, status: 0, pair: 0,
+	import: 1, inspect: 1, abort: 1, recipe: 2, inbox: 2,
+};
+
+/**
+ * Refuses what `verb` does not read. Ignoring it did what nobody asked: `export <path>` wrote into
+ * the project, and `status --json` printed prose to a program.
+ */
+function refuseUnread(verb: string, positional: readonly string[], flags: ReadonlyMap<string, unknown>): void {
+	const known = Object.hasOwn(VERB_FLAGS, verb) ? VERB_FLAGS[verb] : undefined;
+	if (!known) return;
+	for (const flag of flags.keys()) if (!GLOBAL_FLAGS.has(flag) && !known.includes(flag)) throw new UsageError(`${verb} does not take --${flag}`);
+	const extra = positional[VERB_POSITIONALS[verb]];
+	if (extra !== undefined) throw new UsageError(`${verb}: unexpected argument ${JSON.stringify(extra)}`);
+}
+
+/** The usage for `command`: its own section of `CLI_USAGE`, or all of it. */
+export function usageFor(command: string | undefined): string {
+	const head = command !== undefined && Object.hasOwn(USAGE_SECTIONS, command) ? USAGE_SECTIONS[command] : undefined;
+	if (!head) return CLI_USAGE;
+	const lines = CLI_USAGE.split("\n");
+	const at = lines.findIndex((line) => line.startsWith(head));
+	const end = lines.indexOf("", at);
+	return lines.slice(at, end === -1 ? undefined : end).join("\n");
+}
+
 /**
  * Where the launcher goes: `--dir` if given, otherwise the first of ~/.local/bin and /usr/local/bin
  * that is on PATH. One function, because the question asked before writing and the write itself
@@ -990,27 +1056,280 @@ function staleReason(old: string, entryDir: string, node: string): string {
 }
 
 /**
- * Start a session: the browser front end, or pi itself. Both are complete pi sessions — the browser
- * one runs `pi --mode rpc` behind a page (src/web.mjs) — so this is a choice of window, not of
+ * Start a session: the browser page, or pi itself. Both are complete pi sessions — the page's is a
+ * `pi --mode rpc` that pi-loops runs in the background — so this is a choice of window, not of
  * product, and `--tui` is always there when the guess is wrong.
  */
 async function launch(argv: string[], out: (line: string) => void): Promise<number> {
-	const { ours, pi } = splitLaunchArgs(argv[0] === "web" || argv[0] === "tui" ? argv.slice(1) : argv);
-	const has = (name: string) => ours.includes(`--${name}`);
+	const { ours, pi, misplaced } = splitLaunchArgs(argv[0] === "web" || argv[0] === "tui" ? argv.slice(1) : argv);
+	const has = (name: string) => ours.some((a) => a === `--${name}` || a.startsWith(`--${name}=`));
 	if (has("help")) {
 		out(CLI_USAGE);
 		return 0;
 	}
-	const mode = resolveUiMode({
-		web: argv[0] === "web" || has("web"),
-		tui: argv[0] === "tui" || has("tui"),
-		interactiveTty: !!process.stdout.isTTY && !!process.stdin.isTTY,
-		remoteTty: isRemoteTty(),
-	});
-	const withDefaults = applyRememberedModel(pi, readUiPrefs(loopsDir(ours)));
+	if (misplaced.length) {
+		out(`pi-loops: ${misplaced[0]} goes to pi, so it belongs after --: ${["pi-loops", ...ours, "--", ...misplaced, ...pi].join(" ")}`);
+		return 2;
+	}
+	const asked = { web: argv[0] === "web" || has("web"), tui: argv[0] === "tui" || has("tui"), interactiveTty: !!process.stdout.isTTY && !!process.stdin.isTTY };
+	const noTerminal = noTerminalRefusal({ ...asked, piArgs: pi });
+	if (noTerminal) {
+		out(noTerminal);
+		return 1;
+	}
+	const mode = resolveUiMode({ ...asked, remoteTty: isRemoteTty() });
+	const dir = loopsDir(ours);
+	const withDefaults = applyRememberedModel(pi, readUiPrefs(dir));
 	if (mode === "terminal") return runChild(process.env.PI_BIN || "pi", withDefaults);
-	const web = path.join(path.dirname(fileURLToPath(import.meta.url)), "web.mjs");
-	return runChild(process.execPath, [web, ...ours.filter((a) => a !== "--web" && a !== "--tui"), ...(withDefaults.length ? ["--", ...withDefaults] : [])]);
+
+	const refused = pageFlagRefusal(ours);
+	if (refused) {
+		for (const line of refused) out(line);
+		return 2;
+	}
+	if (withDefaults.some((a) => a === "--resume" || a === "-r" || a.startsWith("--resume="))) {
+		out("pi-loops: --resume is pi's picker, which the page has as /resume; pi-loops --session <id> opens one by id");
+		return 2;
+	}
+	const target = pageTarget(withDefaults, process.cwd());
+	if ("error" in target) {
+		out(`pi-loops: ${target.error}`);
+		return 1;
+	}
+
+	// Refused here, before anything starts: the page would refuse it after pi-loops was up.
+	if (target.piArgs.some((a) => a === "--api-key" || a.startsWith("--api-key="))) {
+		out(`pi-loops: ${API_KEY_REFUSAL}`);
+		return 1;
+	}
+	// Asking for the page is asking for pi-loops: a stop by hand ends here, or the process it starts
+	// would find the mark and leave again. Every loop and rule resumes with it, which is said once
+	// pi-loops is up; if it does not come up, the stop stays as it was.
+	const liftedStop = readUiPrefs(dir).host === "stopped";
+	if (liftedStop) clearUiPref(dir, "host");
+	const ensured = await ensureHost(pageLaunchHost(dir));
+	// Running, started, or being started by a window right now: each of these has a page coming.
+	const why = ensured.error ?? (ensured.action.kind === "none" && ensured.action.reason !== "running" && ensured.action.reason !== IN_PROGRESS ? ensured.action.reason : undefined);
+	const rec = await waitForSocket(dir, why ? 0 : PAGE_WAIT_MS);
+	if (liftedStop) {
+		if (rec) out(STOP_LIFTED_LINE);
+		else writeUiPref(dir, "host", "stopped");
+	}
+	if (!rec) {
+		out(why ? `pi-loops did not start: ${why}` : `pi-loops: the page did not come up within ${PAGE_WAIT_MS / 1000} s; see ${path.join(dir, HOST_LOG)}`);
+		return 1;
+	}
+	const waiting = (r: HostServiceRecord | undefined) => (r && !r.url && r.pageWaiting ? pageWaitingLine(r.pageWaiting.reason, pageAddress(dir)) : undefined);
+	const held = waiting(rec);
+	if (held) {
+		out(held);
+		return 1;
+	}
+	// Asked while the page may still be binding: pi starts beside the bind, and the answer brings the
+	// address. Opening may also wait for an older pi in that conversation to stop, up to 15 s.
+	const tty = !!process.stdout.isTTY;
+	const wantOpen = tty && !has("no-open") && !isRemoteTty();
+	const slow = setTimeout(() => process.stderr.write("waiting for pi-loops to open the conversation…\n"), PAGE_OPEN_SLOW_MS);
+	const res = await askHost(dir, { op: "page-open", cwd: process.cwd(), sessionId: target.sessionId, sessionFile: target.sessionFile, piArgs: target.piArgs, ...(wantOpen ? { openFile: true } : {}), ...(tty ? { copyKey: true } : {}) }, PAGE_OPEN_WAIT_MS).finally(() => clearTimeout(slow));
+	if (!res) {
+		out(`pi-loops (pid ${rec.pid}) is not answering; see ${path.join(dir, HOST_LOG)}`);
+		return 1;
+	}
+	if (!res.ok) {
+		out(waiting(readHostService(dir)) ?? `pi-loops: ${res.error}`);
+		return 1;
+	}
+	// The browser opens on a file only this user can read, which holds the key: an argv is anyone's.
+	// "Opened" only when an opener started; whether the browser could read the file it cannot tell.
+	const opened = wantOpen && !!res.openFile && (await openBrowser(openFileUrl(res.openFile!)));
+	const lines = pageLaunchLines({
+		startedPid: ensured.up && ensured.pid === rec.pid ? rec.pid : undefined,
+		url: res.url!,
+		copyKey: res.copyKey,
+		opened,
+		tty,
+		ignoredArgs: res.ignoredArgs,
+	});
+	for (const line of lines) out(line);
+	return 0;
+}
+
+/**
+ * What a page launch asks `ensureHost` for: a start with nothing to run, but not a start by name.
+ * Under `[host] auto = false` the page and its conversations count as windows, and the process
+ * leaves with the last of them.
+ */
+export function pageLaunchHost(dir: string): EnsureHostOptions {
+	return {
+		dir,
+		packageDir: packageRoot(),
+		piPackage: process.env.PI_LOOPS_PI_PACKAGE,
+		startedBy: "the shell that ran pi-loops",
+		automation: { loops: 0, rules: 0, pushServers: 0 },
+		auto: true,
+		stopped: false,
+		page: true,
+		myVersion: PI_LOOPS_VERSION,
+	};
+}
+
+/** What `pi-loops` prints when opening the page ends a stop by hand. */
+export const STOP_LIFTED_LINE = "pi-loops was stopped by hand; it runs again now (loops and rules resume)";
+/** What starts pi-loops again after `pi-loops stop`. */
+const STARTS_AGAIN = "pi-loops start, /pi-loops start or pi-loops opening the page";
+
+/** How long `pi-loops` waits for pi-loops to take `page-open`. */
+export const PAGE_WAIT_MS = 10_000;
+/** `page-open` answers once a new conversation's pi has said its id: as long as the socket keeps it open, and a second for the answer. */
+const PAGE_OPEN_WAIT_MS = CONTROL_TIMEOUT_MS["page-open"] + 1_000;
+/** After this long, `pi-loops` says what it is waiting for. */
+const PAGE_OPEN_SLOW_MS = 3_000;
+/** How long `pi-loops start` waits for a start another window has under way. */
+const START_WAIT_MS = 10_000;
+/** What `ensureHost` answers while another window is starting pi-loops: wait for that start. */
+const IN_PROGRESS = "a start is in progress";
+
+/**
+ * The record of a live pi-loops once its control socket takes connections, or undefined after `ms`
+ * with no live record at all. The socket opens a moment after the record is written, before the
+ * page binds; a record that already has the page's address, or why it has none, is past that. A
+ * start another window has under way counts: it is waited for, not reported as a failure. A socket
+ * still shut at the deadline is left for `page-open` to find not answering.
+ */
+async function waitForSocket(dir: string, ms: number): Promise<HostServiceRecord | undefined> {
+	const deadline = Date.now() + ms;
+	let live: HostServiceRecord | undefined;
+	for (;;) {
+		const rec = readHostService(dir);
+		if (rec && hostServiceAlive(rec)) {
+			if (rec.url || rec.pageWaiting || (await socketOpen(hostSocketPath(dir)))) return rec;
+			live = rec;
+		}
+		if (Date.now() >= deadline) return live;
+		await new Promise((r) => setTimeout(r, 20));
+	}
+}
+
+/** Whether something listens on the socket: connected, then closed again without a word. */
+function socketOpen(socketPath: string): Promise<boolean> {
+	return new Promise((resolve) => {
+		const socket = net.createConnection(socketPath);
+		socket.once("connect", () => {
+			socket.destroy();
+			resolve(true);
+		});
+		socket.once("error", () => resolve(false));
+	});
+}
+
+/**
+ * The address the page binds, as the port-held lines name it: the choice src/host.ts makes
+ * (`pageBindPort`). A port chosen when it binds is not known here, and is not made up.
+ */
+export function pageAddress(dir: string): string {
+	const config = loadConfig(dir);
+	const port = pageBindPort(config, { defaultDir: path.resolve(dir) === path.resolve(homeLoopsDir(getAgentDir())), env: process.env.PI_LOOPS_PAGE_PORT });
+	return port ? `${config.pageHost}:${port}` : `${config.pageHost} (on a free port; pi-loops status names it)`;
+}
+
+/** Why `pi-loops` opened nothing: the page's port is held. */
+export function pageWaitingLine(reason: "older-page" | "other-program", where: string): string {
+	return reason === "older-page"
+		? `pi-loops: an older pi-loops page is still open on ${where}; quit it (Ctrl-C in its terminal) and this page takes its place within 30 seconds`
+		: `pi-loops: ${where} is used by another program; set [page] port in config.toml, then pi-loops restart`;
+}
+
+/**
+ * The flags 0.23 took for the page's address, refused with the config.toml lines that replace them:
+ * the page outlives this command, so a flag on it would last only until the next restart.
+ */
+export function pageFlagRefusal(ours: string[]): string[] | undefined {
+	const valueOf = (name: string): string | undefined => {
+		const eq = ours.find((a) => a.startsWith(`--${name}=`));
+		if (eq) return eq.slice(name.length + 3);
+		const at = ours.indexOf(`--${name}`);
+		return at !== -1 && ours[at + 1] && !ours[at + 1].startsWith("-") ? ours[at + 1] : undefined;
+	};
+	const has = (name: string) => ours.some((a) => a === `--${name}` || a.startsWith(`--${name}=`));
+	const keys: string[] = [];
+	if (has("port")) {
+		const v = valueOf("port");
+		keys.push(`port = ${v && /^\d+$/.test(v) ? Number(v) : 4200}`);
+	}
+	if (has("host")) keys.push(`host = ${JSON.stringify(valueOf("host") ?? "0.0.0.0")}`);
+	if (has("allow-host")) {
+		const names = (valueOf("allow-host") ?? "name").split(",").map((n) => n.trim()).filter(Boolean);
+		keys.push(`allow_host = [${names.map((n) => JSON.stringify(n)).join(", ")}]`);
+	}
+	const lines: string[] = [];
+	if (has("no-auth")) lines.push("pi-loops: --no-auth is gone in 0.24: the page is always on and always behind its token");
+	if (keys.length) lines.push("pi-loops: the page outlives this command, so its address is set in config.toml:", "  [page]", ...keys.map((k) => `  ${k}`), "then: pi-loops restart");
+	return lines.length ? lines : undefined;
+}
+
+/**
+ * Which conversation the page opens: `--continue` (`-c`) and `--session <id|prefix>` name one pi
+ * already has, found the way `pi-loops export` finds it and taken out of pi's arguments; without
+ * either, a new one in `cwd` with the arguments as they are.
+ */
+export function pageTarget(piArgs: string[], cwd: string, sessionsRoot = path.join(getAgentDir(), "sessions")): { sessionId?: string; sessionFile?: string; piArgs: string[] } | { error: string } {
+	const rest: string[] = [];
+	let id: string | undefined;
+	let latest = false;
+	for (let i = 0; i < piArgs.length; i++) {
+		const arg = piArgs[i];
+		if (arg === "--continue" || arg === "-c") latest = true;
+		else if (arg.startsWith("--session=")) id = arg.slice("--session=".length);
+		else if (arg === "--session" && piArgs[i + 1] !== undefined) id = piArgs[++i];
+		else rest.push(arg);
+	}
+	if (id === undefined && !latest) return { piArgs: rest };
+	try {
+		const picked = pickSession(listSessions(sessionsRoot), { id, cwd });
+		return { sessionId: picked.id, sessionFile: picked.file, piArgs: rest };
+	} catch (err: any) {
+		return { error: err?.message ?? String(err) };
+	}
+}
+
+/**
+ * What `pi-loops` prints once the page has the conversation. The token is on a terminal only: it is
+ * a way in, and stdout redirected to a file would keep it. No pairing code: one armed on every launch
+ * is one any local process can burn; `pi-loops pair` arms one when somebody asks.
+ */
+export function pageLaunchLines(i: { startedPid?: number; url: string; copyKey?: string; opened: boolean; tty: boolean; ignoredArgs?: string[] }): string[] {
+	const lines: string[] = [];
+	if (i.startedPid !== undefined) lines.push("started pi-loops in the background");
+	lines.push(`pi-loops page: ${i.url} (${i.opened ? "opened in your browser" : "open it in a browser"})`);
+	// A one-use key, not the token: scrollback, recordings and shared screens keep what is printed,
+	// and the token is a shell for as long as pi-loops runs.
+	if (i.tty && i.copyKey) lines.push(`  ${i.opened ? "if it did not open, or" : "first visit"} from another browser: ${i.url}?open=${i.copyKey} (works once, for ${COPY_KEY_MS / 60_000} minutes)`);
+	if (i.ignoredArgs?.length) {
+		const flags = i.ignoredArgs.filter((a) => a.startsWith("-"));
+		const named = flags.length ? flags : i.ignoredArgs;
+		lines.push(`  this conversation was already open; ${named.join(" ")} ${named.length === 1 ? "was" : "were"} not applied`);
+	}
+	return lines;
+}
+
+/** What the opener is given for the launch file: a file: URL, which holds no key. */
+export function openFileUrl(file: string): string {
+	return pathToFileURL(file).href;
+}
+
+/** Hand `url` to the system's opener; true once it has started, false when there is none. */
+function openBrowser(url: string): Promise<boolean> {
+	const [cmd, args] = process.platform === "darwin" ? ["open", [url]] : process.platform === "win32" ? ["cmd", ["/c", "start", "", url]] : ["xdg-open", [url]];
+	return new Promise((resolve) => {
+		try {
+			const child = spawn(cmd, args, { stdio: "ignore", detached: true });
+			child.once("spawn", () => resolve(true));
+			child.once("error", () => resolve(false)); // no opener on this machine: the address is printed
+			child.unref();
+		} catch {
+			resolve(false); // a URL on stdout is enough
+		}
+	});
 }
 
 /**
@@ -1042,3 +1361,305 @@ export function applyRememberedModel(piArgs: string[], prefs: UiPrefs): string[]
 	if (prefs.thinking && !said("thinking")) out.push("--thinking", prefs.thinking);
 	return out;
 }
+
+export type AbortTarget = { kind: "run"; runId: string } | { kind: "trace"; traceId: string } | { kind: "session"; sessionId: string } | { kind: "ambiguous"; matches: string[] };
+
+/**
+ * What `pi-loops abort <ref>` names. A run id (`run-…`) and anything that matches no session are
+ * the socket's: a loop run, a rule check. A session id pi-loops knows (a lease or a queue), or a
+ * unique prefix of one, names that conversation's turn. The ref is typed by hand and becomes a file
+ * name, so one `sessionFileName` refuses is refused before any match.
+ */
+export function abortTarget(ref: string, sessions: readonly string[]): AbortTarget {
+	if (ref.startsWith("run-")) return { kind: "run", runId: ref };
+	sessionFileName(ref);
+	if (sessions.includes(ref)) return { kind: "session", sessionId: ref };
+	// A short trace id can be the start of a session id too: fewer characters name a trace, as before.
+	if (ref.length < SESSION_PREFIX_MIN) return { kind: "trace", traceId: ref };
+	const matches = [...new Set(sessions.filter((id) => id.startsWith(ref)))].sort();
+	if (matches.length === 1) return { kind: "session", sessionId: matches[0] };
+	if (matches.length > 1) return { kind: "ambiguous", matches };
+	return { kind: "trace", traceId: ref };
+}
+
+/** How long `pi-loops abort` waits for the stop row to be read before it reports it as queued. */
+export const STOP_WAIT_MS = 5000;
+/** The shortest session prefix `pi-loops abort` resolves to a session; anything shorter is a trace id. */
+export const SESSION_PREFIX_MIN = 8;
+
+/**
+ * The line `pi-loops abort` ends with for a stop row's audit state, and the exit code. `undefined`:
+ * the row is still queued. `done` and `stale` are the two states a stop ends in; any other is named,
+ * so a new one is never read as queued.
+ */
+export function stopReport(state: string | undefined, sessionId: string): { line: string; code: number } {
+	const id8 = shortSessionId(sessionId);
+	switch (state) {
+		case "done":
+			return { line: `stopped the turn in session ${id8}`, code: 0 };
+		case "stale":
+			return { line: `nothing was running in session ${id8}`, code: 1 };
+		case undefined:
+			return { line: `stop queued for session ${id8}; it takes effect when that conversation's pi or pi-loops reads it`, code: 0 };
+		default:
+			return { line: `the stop for session ${id8} ended as ${state}; see /triggers audit`, code: 1 };
+	}
+}
+
+/**
+ * Stop a conversation's turn through a request row: written, rung to pi-loops in the background (a
+ * window hears the file change itself), then waited for. The row leaves the file once its holder read
+ * it, and the audit line says what it did; still in the file after STOP_WAIT_MS, it is queued.
+ */
+async function stopThroughRow(loopsDir: string, sessionId: string, target: NonNullable<Parameters<typeof stopRow>[1]>, out: (line: string) => void): Promise<number> {
+	const requests = new RequestStore(loopsDir);
+	const row = stopRow(sessionId, target, "cli", { pid: process.pid, instance: "cli", procStart: procStart(process.pid), version: PI_LOOPS_VERSION });
+	requests.append(row);
+	await ringHost(loopsDir, `request:${sessionId}`);
+	const deadline = Date.now() + STOP_WAIT_MS;
+	while (requests.list(sessionId).some((r) => r.id === row.id) && Date.now() < deadline) await new Promise((r) => setTimeout(r, 50));
+	const state = new TriggerStore(loopsDir).listAudit(1, (r) => r.type === "request" && r.traceId === row.id)[0]?.state;
+	const report = stopReport(state, sessionId);
+	out(report.line);
+	return report.code;
+}
+
+/**
+ * `pi-loops start | stop | restart | status | abort`: the process that runs loops and rule checks
+ * while no pi is open. It is pi-loops to the person using it; "host" is the code's word for it.
+ */
+async function serviceCommand(verb: string, args: string[], flags: Map<string, string | true>, loopsDir: string, out: (line: string) => void): Promise<number> {
+	// Asking how a command works must not run it: `pi-loops stop --help` stopped every loop.
+	if (flags.has("help") || args.includes("help")) {
+		const lines = CLI_USAGE.split("\n");
+		const at = lines.findIndex((line) => line.startsWith(verb === "pair" ? "pi-loops pair" : "pi-loops start | stop"));
+		for (const line of lines.slice(at, lines.indexOf("", at))) out(line);
+		return 0;
+	}
+	const live = (): HostServiceRecord | undefined => {
+		const rec = readHostService(loopsDir);
+		return rec && hostServiceAlive(rec) ? rec : undefined;
+	};
+	if (verb === "status" && flags.has("url")) {
+		// The token is in the URL so the page can be opened with one click; it is printed only when asked.
+		const rec = live();
+		if (!rec) {
+			out("pi-loops is not running");
+			return 1;
+		}
+		if (!rec.url) {
+			out(`pi-loops (pid ${rec.pid}) has no page: its port could not be bound (see ${path.join(loopsDir, HOST_LOG)})`);
+			return 1;
+		}
+		out(`${rec.url}?token=${rec.token}`);
+		return 0;
+	}
+	if (verb === "pair") {
+		const rec = live();
+		if (!rec) {
+			out("pi-loops is not running; pi-loops start starts it");
+			return 1;
+		}
+		const res = await askHost(loopsDir, { op: "pair" });
+		if (!res) {
+			out(`pi-loops (pid ${rec.pid}) is not answering; see ${path.join(loopsDir, HOST_LOG)}`);
+			return 1;
+		}
+		if (!res.ok) {
+			out(`pi-loops: ${res.error}`);
+			return 1;
+		}
+		out(`pairing code for another device: ${res.code} (10 minutes)`);
+		for (const address of res.addresses ?? []) out(`  on that device, open ${address} and type it`);
+		if (!res.addresses?.length) out(`  only this machine can reach ${rec.url ?? "the page"}: tailscale serve, or [page] host in config.toml, gives that device an address`);
+		return 0;
+	}
+	if (verb === "start" && flags.has("foreground")) return runInForeground(loopsDir);
+	if (verb === "start") {
+		// A person asking by name: the stop mark goes, and it starts even with nothing to run yet. The
+		// "started" mark is what keeps it, under `[host] auto = false`, after the last window: also when it
+		// is already running, started by a window.
+		writeUiPref(loopsDir, "host", "started");
+		const running = live();
+		if (running) {
+			out("pi-loops is already running");
+			return 0;
+		}
+		const res = await ensureHost({
+			dir: loopsDir,
+			packageDir: packageRoot(),
+			piPackage: process.env.PI_LOOPS_PI_PACKAGE,
+			startedBy: "the shell that ran pi-loops start",
+			automation: { loops: 0, rules: 0, pushServers: 0 },
+			auto: true,
+			stopped: false,
+			asked: true,
+			myVersion: PI_LOOPS_VERSION,
+		});
+		let rec = live();
+		// A window starting it at this moment is not a failure: that start is waited for.
+		if (!rec && res.action.kind === "none" && res.action.reason === IN_PROGRESS) {
+			for (const deadline = Date.now() + START_WAIT_MS; !rec && Date.now() < deadline; rec = live()) await new Promise((r) => setTimeout(r, 100));
+		}
+		if (rec) {
+			out("pi-loops is running");
+			return 0;
+		}
+		out(`pi-loops did not start: ${res.error ?? (res.action.kind === "none" ? res.action.reason : `see ${path.join(loopsDir, HOST_LOG)}`)}`);
+		return 1;
+	}
+	if (verb === "restart") {
+		const old = live();
+		if (old) out(RESTART_WAIT_LINE);
+		if (old && !(await stopAndWait(loopsDir, old, () => undefined, { reason: "restart" }))) {
+			out(`pi-loops (pid ${old.pid}) has not exited after ${LEAVE_WAIT_MS / 1000} s, and it is marked stopped: run pi-loops start once it has gone (see ${path.join(loopsDir, HOST_LOG)})`);
+			return 1;
+		}
+		return serviceCommand("start", [], new Map(), loopsDir, out);
+	}
+	if (verb === "status") {
+		const res = await askHost(loopsDir, { op: "status" });
+		if (!res) {
+			// What waits for each conversation, from the files: a live host says it in its snapshot, and
+			// a row waiting for a closed conversation is exactly what a person wants to see when it is down.
+			const queues = () => requestLines(requestQueues(new RequestStore(loopsDir), new LeaseStore(loopsDir)), Date.now());
+			// No answer is not the same as not running: one wedged on a hung MCP read still holds the
+			// record. Fall back to it, so the person gets a pid and a log to look at.
+			const rec = live();
+			if (rec) {
+				out(`pi-loops (pid ${rec.pid}) is not answering (started ${formatLocal(Date.parse(rec.startedAt))})`);
+				out(`  log: ${path.join(loopsDir, HOST_LOG)}`);
+				out("  stop it with: pi-loops stop");
+				for (const l of queues()) out(l);
+				return 1;
+			}
+			// Why, when something keeps it from starting: each of these pauses every loop and check.
+			const spawns = readSpawnLog(loopsDir);
+			const why = readUiPrefs(loopsDir).host === "stopped" ? "it was stopped by hand; pi-loops start, or pi-loops opening the page, starts it" : process.env.PI_LOOPS_HOST?.toLowerCase() === "off" ? "PI_LOOPS_HOST=off is set" : !loadConfig(loopsDir).hostAuto ? "[host] auto = false in config.toml; pi-loops start starts it" : crashPaused(spawns, Date.now()) ? `${crashPauseText(spawns).replace("/pi-loops start", "pi-loops start")} (last: ${spawns.lastError ?? "?"})` : spawns.notBefore && Date.now() < Date.parse(spawns.notBefore) ? `it could not start (${spawns.lastError ?? `see ${HOST_LOG}`}); retrying after ${formatLocal(Date.parse(spawns.notBefore))}` : undefined;
+			out(why ? `pi-loops is not running: ${why}` : "pi-loops is not running (a pi window starts it when there is work to run)");
+			for (const l of queues()) out(l);
+			return 1;
+		}
+		if (!res.ok) {
+			// An error it answered with is about it, not about how this command was typed: no usage.
+			out(`pi-loops is running but could not say how it is: ${res.error}`);
+			out(`  log: ${path.join(loopsDir, HOST_LOG)}`);
+			return 1;
+		}
+		out("pi-loops");
+		for (const line of renderHostSnapshot(res.snapshot!)) out(line);
+		return 0;
+	}
+	if (verb === "abort") {
+		const ref = args[0];
+		if (!ref) throw new UsageError("abort needs a run id, a trigger trace id or a session id");
+		const leases = new LeaseStore(loopsDir);
+		let target: AbortTarget;
+		try {
+			target = abortTarget(ref, [...leases.list().map((l) => l.sessionId), ...new RequestStore(loopsDir).sessions()]);
+		} catch {
+			throw new Error(`${JSON.stringify(ref)} is not a run id, a trigger trace id or a session id`);
+		}
+		if (target.kind === "ambiguous") {
+			out(`${ref} is a prefix of ${target.matches.length} sessions; give more of the id:`);
+			for (const id of target.matches) out(`  ${id}`);
+			return 1;
+		}
+		if (target.kind === "session") return stopThroughRow(loopsDir, target.sessionId, { current: true, started_before: stamp() }, out);
+		const res = await askHost(loopsDir, target.kind === "run" ? { op: "abort", runId: ref } : { op: "abort", traceId: ref });
+		if (res) {
+			if (!res.ok) throw new Error(res.error);
+			out(res.aborted ? `aborted ${ref}` : `nothing running with id ${ref}`);
+			return res.aborted ? 0 : 1;
+		}
+		// No answer, but a turn in a conversation is on the leases: the row reaches it where the socket could not.
+		const held = target.kind === "run" ? heldTurnFor(leases.list(), ref) : undefined;
+		if (held?.kind === "ambiguous") {
+			out(`${ref} is a prefix of ${held.matches.length} running turns; give more of the id:`);
+			for (const id of held.matches) out(`  ${id}`);
+			return 1;
+		}
+		if (!held) throw new Error("pi-loops is not running");
+		return stopThroughRow(loopsDir, held.sessionId, { id: held.runId }, out);
+	}
+	if (verb === "stop") {
+		// Stopped by hand stays stopped: without this mark the next window's tick starts it again.
+		writeUiPref(loopsDir, "host", "stopped");
+		const rec = live();
+		if (!rec) {
+			out(`pi-loops is not running; the stop is recorded, so nothing starts it until ${STARTS_AGAIN}`);
+			return 0;
+		}
+		// How many conversations the page had open, asked before it goes: they close with it.
+		const before = await askHost(loopsDir, { op: "status" });
+		const open = before?.ok ? Number(before.snapshot?.pageOpen) || 0 : 0;
+		// Waited on, so a process too wedged to run its SIGTERM handler is killed rather than left running.
+		const stopped = await stopAndWait(loopsDir, rec, out, { reason: "stop", waitMs: 15_000 });
+		if (open) out(`  the page and its ${openConversations(open)} closed with it; pi-loops start opens it again`);
+		return stopped ? 0 : 1;
+	}
+	throw new Error(`unknown command ${JSON.stringify(verb)}: pi-loops start | stop | restart | status | abort <id>`);
+}
+
+/**
+ * Stop it and wait until that process has gone (its pid, and its start time against a reused pid);
+ * false when it is still there after `waitMs`. A restart starts the new one only after this, and
+ * waits `LEAVE_WAIT_MS`: the old process first lets a turn in the browser page finish.
+ */
+export async function stopAndWait(loopsDir: string, rec: HostServiceRecord, out: (line: string) => void, how: { reason: "stop" | "restart"; waitMs?: number }): Promise<boolean> {
+	const waitMs = how.waitMs ?? LEAVE_WAIT_MS;
+	await stopService(loopsDir, rec, out, how.reason);
+	const deadline = Date.now() + waitMs;
+	while (hostServiceAlive(rec) && Date.now() < deadline) await new Promise((r) => setTimeout(r, 200));
+	if (!hostServiceAlive(rec)) return true;
+	// Still there: a process whose event loop is blocked never runs its SIGTERM handler, and a person
+	// asked for it to stop. As a window evicting a wedged one does.
+	try {
+		process.kill(rec.pid, "SIGKILL");
+	} catch {
+		/* it left between the look and the signal */
+	}
+	removeHostService(loopsDir, rec.pid);
+	out(`pi-loops (pid ${rec.pid}) did not stop within ${Math.round(waitMs / 1000)}s; sent SIGKILL`);
+	const killed = Date.now() + 5_000;
+	while (hostServiceAlive(rec) && Date.now() < killed) await new Promise((r) => setTimeout(r, 100));
+	return !hostServiceAlive(rec);
+}
+
+/** Ask it to stop over its socket; one that does not answer gets SIGTERM, and its record is forgotten. */
+export async function stopService(loopsDir: string, rec: HostServiceRecord, out: (line: string) => void, reason: "stop" | "restart" = "stop"): Promise<void> {
+	writeUiPref(loopsDir, "host", "stopped");
+	const res = await askHost(loopsDir, { op: "stop", reason });
+	if (res?.ok) {
+		out(`asked pi-loops to stop; nothing starts it again until ${STARTS_AGAIN}`);
+		return;
+	}
+	try {
+		process.kill(rec.pid, "SIGTERM");
+	} catch {
+		/* gone already */
+	}
+	removeHostService(loopsDir, rec.pid);
+	out(`pi-loops (pid ${rec.pid}) was not answering; sent SIGTERM`);
+}
+
+/**
+ * `pi-loops start --foreground`: run in this terminal until stopped, for a service manager the person
+ * set up (a systemd user unit, a LaunchAgent). It exits 0 when stopped, so the manager does not
+ * restart it, and 78 when it cannot run here at all; during a crash-pause it waits the pause out.
+ */
+function runInForeground(loopsDir: string): Promise<number> {
+	// A start like any other, as `systemctl start` is: a stop by hand lasts until the next start.
+	clearUiPref(loopsDir, "host");
+	const { node, args, env } = hostCommand({ dir: loopsDir, packageDir: packageRoot(), piPackage: process.env.PI_LOOPS_PI_PACKAGE, startedBy: "the service manager that ran pi-loops start --foreground" });
+	const child = spawn(node, args, { stdio: "inherit", cwd: os.homedir(), env: { ...env, PI_LOOPS_HOST_MANAGED: "foreground" } });
+	const forward = (signal: NodeJS.Signals) => () => child.kill(signal);
+	for (const signal of ["SIGTERM", "SIGINT", "SIGHUP"] as const) process.on(signal, forward(signal));
+	return new Promise((resolve) => {
+		child.once("error", (err) => {
+			process.stderr.write(`pi-loops: ${err.message}\n`);
+			resolve(78);
+		});
+		child.once("exit", (code, signal) => resolve(code ?? (signal ? 128 + (os.constants.signals[signal] ?? 0) : 1)));
+	});
+}