@alphacoder-v0/pi-loops 0.17.3

package/src/hooks.ts

@@ -0,0 +1,436 @@
+/**
+ * Lifecycle hooks: user-configured shell commands and JSON
+ * webhooks that fire on agent events. Best-effort side effects: they never mutate
+ * agent state and failures never fail a turn.
+ *
+ *   ~/.pi/agent/loops/hooks.toml      user hooks (top-level `allow_project_hooks = true` opts project hooks in)
+ *   <project>/.pi/hooks.toml          project hooks (ignored unless allowed)
+ */
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { envFlag } from "./config.ts";
+import { previewRedacted } from "./redact.ts";
+import { parseToml } from "./toml.ts";
+import { PI_LOOPS_VERSION } from "./version.ts";
+
+/**
+ * `run_start` / `run_end` exist because a scheduled run is not a turn. A run can happen with no
+ * conversation at all (the headless host) or beside one (a loop firing while you are typing), so
+ * overloading `agent_*` would mean a rule written about your own turns quietly started firing for
+ * automation too. A run gets its own pair, and `agent_*` keeps meaning what its author thought it
+ * meant.
+ */
+export const HOOK_EVENTS = ["agent_start", "agent_end", "run_start", "run_end", "turn_start", "turn_end", "message_start", "message_update", "message_end", "tool_start", "tool_update", "tool_end", "compaction"] as const;
+export type HookEvent = (typeof HOOK_EVENTS)[number];
+
+const DEFAULT_TIMEOUT_MS = 5000;
+const MAX_SUMMARY_CHARS = 2000;
+/** What a hook may put in the log per run. The same bound stderr has used for the failure message. */
+const MAX_OUTPUT_CHARS = 4000;
+
+export interface HookConfig {
+	event: HookEvent;
+	command?: string;
+	webhook?: string;
+	timeoutMs: number;
+	/** Where the command runs: `project` is the project directory, `loops` the pi-loops data directory, `home` the user's home. */
+	cwd: "project" | "loops" | "home";
+	onFailure: "warn" | "ignore";
+	tool?: string;
+	headers?: Record<string, string>;
+	source: "user" | "project";
+}
+
+/** The payload (webhook body and `$PI_HOOK_PAYLOAD` file). */
+export interface HookPayload {
+	event: HookEvent;
+	session_id: string;
+	cwd: string;
+	model_provider: string;
+	model_id: string;
+	thinking_level: string;
+	source?: "user" | "project";
+	message_kind?: string | null;
+	message_summary?: string | null;
+	assistant_event?: string | null;
+	tool_call_id?: string | null;
+	tool_name?: string | null;
+	tool_is_error?: boolean | null;
+	tool_args?: unknown | null;
+	tool_result_summary?: string | null;
+	compaction_trigger?: "auto" | "manual" | null;
+	compaction_tokens_before?: number | null;
+	compaction_summary?: string | null;
+	/** `run_start` / `run_end`: which job, and how it went. Null for every other event. */
+	run_job?: string | null;
+	run_id?: string | null;
+	run_ok?: boolean | null;
+	run_findings?: number | null;
+	run_error?: string | null;
+	run_cost_usd?: number | null;
+	/**
+	 * pi also reports a compaction that failed or was cancelled, and that
+	 * is the case a watcher most wants — a session that cannot compact is a session about to fail
+	 * on context length. It reaches the same `compaction` hook with this set, and no summary.
+	 */
+	compaction_failed?: boolean | null;
+}
+
+/** Event-specific fields; the runner fills in the session-level ones. */
+export type HookEventData = Pick<HookPayload, "event" | "message_kind" | "message_summary" | "assistant_event" | "tool_call_id" | "tool_name" | "tool_is_error" | "tool_args" | "tool_result_summary" | "compaction_trigger" | "compaction_tokens_before" | "compaction_summary" | "compaction_failed" | "run_job" | "run_id" | "run_ok" | "run_findings" | "run_error" | "run_cost_usd">;
+
+export interface ParsedHooksFile {
+	allowProjectHooks: boolean;
+	hooks: HookConfig[];
+	diagnostics: string[];
+}
+
+/** Bad rules are skipped with a diagnostic, the rest still load. */
+export function parseHooksToml(text: string, source: "user" | "project"): ParsedHooksFile {
+	const doc = parseToml(text);
+	const out: ParsedHooksFile = { allowProjectHooks: doc.allow_project_hooks === true, hooks: [], diagnostics: [] };
+	const hooks = Array.isArray(doc.hook) ? (doc.hook as any[]) : [];
+	hooks.forEach((h, i) => {
+		if (h?.enabled === false) return;
+		if (!h || typeof h.event !== "string" || !(HOOK_EVENTS as readonly string[]).includes(h.event)) {
+			out.diagnostics.push(`hooks ${source}: hook #${i + 1} has unknown event ${JSON.stringify(h?.event)}`);
+			return;
+		}
+		const command = typeof h.command === "string" && h.command.trim() ? h.command : undefined;
+		const webhook = typeof h.webhook === "string" ? h.webhook : undefined;
+		if (!command && !webhook) {
+			out.diagnostics.push(`hooks ${source}: hook #${i + 1} has neither command nor webhook`);
+			return;
+		}
+		const cwd = h.cwd ?? "project";
+		if (!["project", "loops", "home"].includes(cwd)) {
+			out.diagnostics.push(`hooks ${source}: hook #${i + 1} has invalid cwd ${JSON.stringify(h.cwd)} (project | loops | home)`);
+			return;
+		}
+		out.hooks.push({
+			event: h.event,
+			command,
+			webhook,
+			timeoutMs: typeof h.timeout_ms === "number" ? h.timeout_ms : DEFAULT_TIMEOUT_MS,
+			cwd,
+			onFailure: h.on_failure === "ignore" ? "ignore" : "warn",
+			tool: typeof h.tool === "string" ? h.tool : undefined,
+			headers: h.headers && typeof h.headers === "object" ? Object.fromEntries(Object.entries(h.headers).map(([k, v]) => [k, String(v)])) : undefined,
+			source,
+		});
+	});
+	return out;
+}
+
+export interface HookRunnerOptions {
+	loopsDir: string;
+	projectCwd: string;
+	/** From config.toml; the user hooks.toml's own `allow_project_hooks` and PI_ALLOW_PROJECT_HOOKS also count. */
+	allowProjectHooks?: boolean;
+	warn: (message: string) => void;
+	/**
+	 * Where a hook's own output goes (the per-process log, `logs/pi-<pid>.log`). Without it the
+	 * usual debugging move — echo something and look at it — has nowhere to land, and that file is
+	 * already the answer to "what did my automation do last night".
+	 */
+	log?: (message: string) => void;
+	getSession: () => { sessionId?: string; cwd: string; model?: string; thinking?: string };
+}
+
+export class HookRunner {
+	readonly hooks: HookConfig[] = [];
+	readonly diagnostics: string[] = [];
+	private readonly opts: HookRunnerOptions;
+	/** Hooks run in event order, one rule at a time — but never block the agent. */
+	private queue: Promise<void> = Promise.resolve();
+
+	constructor(opts: HookRunnerOptions) {
+		this.opts = opts;
+	}
+
+	load(): void {
+		this.hooks.length = 0;
+		this.diagnostics.length = 0;
+		const userFile = path.join(this.opts.loopsDir, "hooks.toml");
+		const projectFile = path.join(this.opts.projectCwd, ".pi", "hooks.toml");
+		const user = this.readFile(userFile, "user");
+		const allowProject = envFlag("ALLOW_PROJECT_HOOKS") || !!this.opts.allowProjectHooks || !!user?.allowProjectHooks;
+		if (user) this.hooks.push(...user.hooks);
+		if (fs.existsSync(projectFile)) {
+			if (allowProject) {
+				const project = this.readFile(projectFile, "project");
+				if (project) this.hooks.push(...project.hooks);
+			} else {
+				this.diagnostics.push(`project hooks ignored at ${projectFile}; set allow_project_hooks = true in ${userFile} or PI_ALLOW_PROJECT_HOOKS=1`);
+			}
+		}
+	}
+
+	private readFile(file: string, source: "user" | "project"): ParsedHooksFile | undefined {
+		let text: string;
+		try {
+			text = fs.readFileSync(file, "utf8");
+		} catch (err: any) {
+			if (err?.code !== "ENOENT") this.diagnostics.push(`hooks ${source}: read ${file} failed: ${err?.message ?? err}`);
+			return undefined;
+		}
+		try {
+			const parsed = parseHooksToml(text, source);
+			this.diagnostics.push(...parsed.diagnostics);
+			return parsed;
+		} catch (err: any) {
+			this.diagnostics.push(`hooks ${source}: parse ${file} failed: ${err?.message ?? err}`);
+			return undefined;
+		}
+	}
+
+	hasHooksFor(event: HookEvent): boolean {
+		return this.hooks.some((h) => h.event === event);
+	}
+
+	/** Wait for queued hooks to finish; bounded so quitting never hangs. */
+	async drain(timeoutMs = 3000): Promise<boolean> {
+		let timer: NodeJS.Timeout | undefined;
+		const timeout = new Promise<false>((r) => {
+			timer = setTimeout(() => r(false), timeoutMs);
+		});
+		const done = this.queue.then(() => true as const, () => true as const);
+		const result = await Promise.race([done, timeout]);
+		if (timer) clearTimeout(timer);
+		return result;
+	}
+
+	/** Queue every matching rule for this event. Returns when they have all run (tests await it; callers may not). */
+	fire(data: HookEventData, signal?: AbortSignal): Promise<void> {
+		const matching = this.hooks.filter((h) => h.event === data.event && (!h.tool || h.tool === data.tool_name));
+		if (!matching.length) return this.queue;
+		const run = async () => {
+			for (const h of matching) {
+				if (signal?.aborted) return;
+				try {
+					// Inside the try: building the payload reads the session and the event, and a throw
+					// here would reject the shared queue promise — which callers deliberately do not
+					// await, so it would surface as an unhandled rejection and take pi down.
+					const payload = this.payloadFor(h, data);
+					await this.runRule(h, payload, signal);
+				} catch (err: any) {
+					if (h.onFailure === "warn") this.opts.warn(`hook ${h.source} ${h.event}${h.tool ? ` (tool=${h.tool})` : ""} failed: ${previewRedacted(err?.message ?? String(err), 300)}`);
+				}
+			}
+		};
+		this.queue = this.queue.then(run, run);
+		return this.queue;
+	}
+
+	/** Every payload field is serialized; absent optionals are `null`, never omitted. */
+	private payloadFor(h: HookConfig, data: HookEventData): HookPayload {
+		const s = this.opts.getSession();
+		const [provider, ...rest] = (s.model ?? "").split("/");
+		return {
+			event: data.event,
+			session_id: s.sessionId ?? "",
+			cwd: s.cwd,
+			model_provider: s.model ? provider : "",
+			model_id: s.model ? rest.join("/") : "",
+			thinking_level: s.thinking ?? "off",
+			source: h.source,
+			message_kind: data.message_kind ?? null,
+			message_summary: data.message_summary ?? null,
+			assistant_event: data.assistant_event ?? null,
+			tool_call_id: data.tool_call_id ?? null,
+			tool_name: data.tool_name ?? null,
+			tool_is_error: data.tool_is_error ?? null,
+			tool_args: data.tool_args ?? null,
+			tool_result_summary: data.tool_result_summary ?? null,
+			compaction_trigger: data.compaction_trigger ?? null,
+			compaction_tokens_before: data.compaction_tokens_before ?? null,
+			compaction_summary: data.compaction_summary ?? null,
+			compaction_failed: data.compaction_failed ?? null,
+			run_job: data.run_job ?? null,
+			run_id: data.run_id ?? null,
+			run_ok: data.run_ok ?? null,
+			run_findings: data.run_findings ?? null,
+			run_error: data.run_error ?? null,
+			run_cost_usd: data.run_cost_usd ?? null,
+		};
+	}
+
+	private resolveCwd(h: HookConfig): string {
+		if (h.cwd === "home") return os.homedir();
+		if (h.cwd === "loops") return this.opts.loopsDir;
+		return this.opts.projectCwd;
+	}
+
+	private async runRule(h: HookConfig, payload: HookPayload, signal?: AbortSignal): Promise<void> {
+		const json = JSON.stringify(payload);
+		const dir = path.join(os.tmpdir(), "pi-hooks");
+		fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+		const payloadFile = path.join(dir, `${randomUUID()}.json`);
+		fs.writeFileSync(payloadFile, json, { mode: 0o600 });
+		try {
+			if (h.command) await this.runCommand(h, payload, payloadFile, signal);
+			if (h.webhook) await this.postWebhook(h, json, signal);
+		} finally {
+			fs.rmSync(payloadFile, { force: true });
+		}
+	}
+
+	private runCommand(h: HookConfig, payload: HookPayload, payloadFile: string, signal?: AbortSignal): Promise<void> {
+		const vars: Record<string, string | null | undefined> = {
+			HOOK_EVENT: payload.event,
+			HOOK_PAYLOAD: payloadFile,
+			SESSION_ID: payload.session_id,
+			CWD: payload.cwd,
+			MODEL_PROVIDER: payload.model_provider,
+			MODEL_ID: payload.model_id,
+			THINKING_LEVEL: payload.thinking_level,
+			MESSAGE_KIND: payload.message_kind,
+			ASSISTANT_EVENT: payload.assistant_event,
+			TOOL_CALL_ID: payload.tool_call_id,
+			TOOL_NAME: payload.tool_name,
+			TOOL_IS_ERROR: payload.tool_is_error == null ? undefined : String(payload.tool_is_error),
+			COMPACTION_TRIGGER: payload.compaction_trigger,
+			COMPACTION_TOKENS_BEFORE: payload.compaction_tokens_before == null ? undefined : String(payload.compaction_tokens_before),
+			COMPACTION_FAILED: payload.compaction_failed == null ? undefined : String(payload.compaction_failed),
+			RUN_JOB: payload.run_job,
+			RUN_ID: payload.run_id,
+			// A string, because `[ "$PI_RUN_OK" = false ]` is the shape a shell hook will be written in.
+			RUN_OK: payload.run_ok == null ? undefined : String(payload.run_ok),
+			RUN_FINDINGS: payload.run_findings == null ? undefined : String(payload.run_findings),
+			RUN_ERROR: payload.run_error,
+			RUN_COST_USD: payload.run_cost_usd == null ? undefined : String(payload.run_cost_usd),
+		};
+		// Environment variables exist only when they have a value; the JSON payload carries nulls.
+		const env: Record<string, string> = { ...(process.env as Record<string, string>) };
+		for (const [key, value] of Object.entries(vars)) {
+			if (value == null) continue;
+			env[`PI_${key}`] = value;
+		}
+		const isWin = process.platform === "win32";
+		return new Promise<void>((resolve, reject) => {
+			// Own process group (setsid equivalent) so a timeout kills the whole tree, not just `sh`.
+			// stdout is piped only when there is somewhere to put it; otherwise it goes to /dev/null as before.
+			const proc = spawn(isWin ? "cmd" : "sh", [isWin ? "/C" : "-c", h.command!], { cwd: this.resolveCwd(h), env, stdio: ["ignore", this.opts.log ? "pipe" : "ignore", "pipe"], detached: !isWin });
+			let stderr = "";
+			proc.stderr?.on("data", (d) => {
+				if (stderr.length < MAX_OUTPUT_CHARS) stderr += d.toString();
+			});
+			// What the hook itself printed. Bounded: a hook that prints a megabyte would otherwise put
+			// a megabyte in the log and rotate away everything the automation had recorded before it.
+			let stdout = "";
+			let overflowed = false;
+			proc.stdout?.on("data", (d) => {
+				if (stdout.length >= MAX_OUTPUT_CHARS) overflowed = true;
+				else stdout += d.toString();
+			});
+			const logOutput = () => {
+				const text = stdout.trim();
+				if (!text) return; // a silent hook stays silent
+				const capped = overflowed || text.length > MAX_OUTPUT_CHARS;
+				this.opts.log?.(`hook ${h.source} ${h.event}${h.tool ? ` (tool=${h.tool})` : ""}: ${capped ? `${text.slice(0, MAX_OUTPUT_CHARS)}… (output truncated)` : text}`);
+			};
+			const killTree = () => {
+				try {
+					if (!isWin && proc.pid) process.kill(-proc.pid, "SIGKILL");
+					else proc.kill("SIGKILL");
+				} catch {
+					/* already gone */
+				}
+			};
+			let done = false;
+			const finish = (err?: Error) => {
+				if (done) return;
+				done = true;
+				clearTimeout(timer);
+				signal?.removeEventListener("abort", onAbort);
+				err ? reject(err) : resolve();
+			};
+			const timer = setTimeout(() => {
+				killTree();
+				finish(new Error(`timed out after ${h.timeoutMs}ms`));
+			}, h.timeoutMs);
+			const onAbort = () => {
+				killTree();
+				finish(new Error("cancelled"));
+			};
+			if (signal?.aborted) onAbort();
+			else signal?.addEventListener("abort", onAbort, { once: true });
+			proc.on("error", (err) => finish(new Error(`spawn: ${err.message}`)));
+			proc.on("close", (code) => {
+				// Also on a timeout or an abort, where `finish` has already rejected: what the hook
+				// managed to say before it was killed is exactly what the reader needs.
+				logOutput();
+				if (code === 0) finish();
+				else finish(new Error(`command exited ${code ?? -1}: ${stderr.trim()}`));
+			});
+		});
+	}
+
+	private async postWebhook(h: HookConfig, json: string, signal?: AbortSignal): Promise<void> {
+		const signals = [AbortSignal.timeout(h.timeoutMs), ...(signal ? [signal] : [])];
+		const res = await fetch(h.webhook!, {
+			method: "POST",
+			headers: { "Content-Type": "application/json", "User-Agent": `pi-loops/${PI_LOOPS_VERSION}`, ...(h.headers ?? {}) },
+			body: json,
+			signal: AbortSignal.any(signals),
+		});
+		if (!res.ok) {
+			const text = await res.text().catch(() => "");
+			throw new Error(`webhook status ${res.status}: ${Array.from(text).slice(0, 500).join("")}`);
+		}
+	}
+}
+
+/* ------------------------------------------------ pi event → payload data */
+
+export function truncateSummary(text: string): string {
+	const chars = Array.from(text);
+	return chars.length <= MAX_SUMMARY_CHARS ? text : `${chars.slice(0, MAX_SUMMARY_CHARS).join("")}…`;
+}
+
+/** `message_kind`: user | assistant | tool_result | <custom role> (pi: the message's customType). */
+export function messageKind(msg: any): string | undefined {
+	const role = msg?.role;
+	if (typeof role !== "string") return undefined;
+	if (role === "toolResult") return "tool_result";
+	if (role === "custom" && typeof msg.customType === "string" && msg.customType) return msg.customType;
+	return role;
+}
+
+/** `message_summary`: text joined with placeholders for thinking / tool calls / images, truncated. */
+export function messageSummary(msg: any): string | undefined {
+	if (!msg) return undefined;
+	const content = msg.content;
+	if (typeof content === "string") return truncateSummary(content);
+	if (!Array.isArray(content)) return truncateSummary(typeof msg === "object" ? JSON.stringify(msg.payload ?? msg.details ?? "") : "");
+	return truncateSummary(
+		content
+			.map((b: any) => {
+				switch (b?.type) {
+					case "text":
+						return b.text ?? "";
+					case "thinking":
+						return "<thinking>";
+					case "toolCall":
+						return `<tool_call ${b.name ?? ""}>`;
+					case "image":
+						return `<image ${b.mimeType ?? b.mime_type ?? ""}>`;
+					default:
+						return "";
+				}
+			})
+			.join("\n"),
+	);
+}
+
+/** `result_summary` for tool results / partial results. */
+export function resultSummary(result: any): string | undefined {
+	if (result === undefined || result === null) return undefined;
+	if (typeof result === "string") return truncateSummary(result);
+	const content = Array.isArray(result?.content) ? result.content : Array.isArray(result) ? result : undefined;
+	if (!content) return truncateSummary(typeof result === "object" ? JSON.stringify(result) : String(result));
+	return truncateSummary(content.map((b: any) => (b?.type === "text" ? (b.text ?? "") : b?.type === "image" ? `<image ${b.mimeType ?? ""}>` : "")).join("\n"));
+}

package/src/host-control-channel.ts

@@ -0,0 +1,243 @@
+/**
+ * A window into the headless host, and a way to interrupt it.
+ *
+ * The answer to "I am away and want to look in" would normally be that its process is still open: `--web` serves
+ * a loopback UI and `/web-connect` relays it. pi-loops' host has no chat at all, so it publishes
+ * the same snapshot the extension builds for `/cron scheduler` and `/triggers` over a unix socket
+ * in the loops directory, plus the one control a watcher actually needs: abort a run that has gone
+ * wrong. Read-mostly by design — a host that could be prompted would be a second chat.
+ *
+ * The socket is created 0600 under `PI_LOOPS_DIR`, so only the user who owns the host can read it.
+ */
+import { createHash } from "node:crypto";
+import * as fs from "node:fs";
+import * as net from "node:net";
+import * as os from "node:os";
+import * as path from "node:path";
+
+export const HOST_SOCKET = "host.sock";
+const MAX_UNIX_SOCKET_PATH = 100; // 104 on macOS, minus headroom so a rename or a longer socket name cannot cross it
+
+/**
+ * Where the host listens. Normally `<dir>/host.sock`, but a unix socket path is capped at 108
+ * bytes on Linux (104 on macOS) — the whole `sockaddr_un.sun_path` — and a loops directory nested
+ * a few levels deep goes past that. `listen()` then fails with EINVAL, the host runs on with no
+ * control channel, and `pi-loops host status|abort|stop` report a host that "is not answering"
+ * while it is perfectly healthy. So a long path falls back to a short one, named by a hash of the
+ * loops directory so two of them never collide.
+ *
+ * The fallback lives one directory down, in a per-user directory this process owns, never directly
+ * in the shared temp directory: this socket accepts `abort` and `stop`, so a predictable path any
+ * local account could bind first would let someone else answer for the host — `host stop` would
+ * report success against a forged reply while the real host kept running unattended.
+ */
+export function hostSocketPath(dir: string): string {
+	const preferred = path.join(dir, HOST_SOCKET);
+	// A byte count, not a character count: the kernel measures bytes.
+	if (Buffer.byteLength(preferred) <= MAX_UNIX_SOCKET_PATH) return preferred;
+	const digest = createHash("sha256").update(path.resolve(dir)).digest("hex").slice(0, 16);
+	return path.join(os.tmpdir(), `pi-loops-${process.getuid?.() ?? "u"}`, `host-${digest}.sock`);
+}
+
+/**
+ * The socket's directory, restricted to this user and verified rather than assumed: in a shared
+ * temp directory the path can already exist as someone else's directory, or as a symlink into one.
+ * Returns false when it cannot be made safe, and the caller then runs without a control channel
+ * rather than listening somewhere anyone can reach.
+ */
+function prepareSocketDir(socketPath: string, log?: (message: string) => void): boolean {
+	const parent = path.dirname(socketPath);
+	try {
+		fs.mkdirSync(parent, { recursive: true, mode: 0o700 });
+		const st = fs.lstatSync(parent);
+		if (!st.isDirectory()) return fail(`${parent} is not a directory`);
+		if (st.uid !== (process.getuid?.() ?? st.uid)) return fail(`${parent} belongs to another user`);
+		if (st.mode & 0o077) {
+			fs.chmodSync(parent, 0o700);
+			if (fs.lstatSync(parent).mode & 0o077) return fail(`${parent} is readable by other users`);
+		}
+		return true;
+	} catch (err: any) {
+		return fail(err?.message ?? String(err));
+	}
+	function fail(reason: string): boolean {
+		log?.(`control channel: refusing to listen — ${reason}`);
+		return false;
+	}
+}
+
+/**
+ * Is this the socket we created, and not someone else's? The mode is deliberately not part of the
+ * test: `listen()` creates the socket under the process umask and the chmod lands a tick later, so
+ * a mode check here would reject a healthy host that had only just started. What actually gates
+ * access is the directory — 0700 and ownership-checked — plus this uid comparison, which is what
+ * stops another account's socket from answering for the host.
+ */
+function ownedSocket(socketPath: string): boolean {
+	try {
+		// lstat, so a symlink pointing at someone else's socket is rejected rather than followed.
+		const st = fs.lstatSync(socketPath);
+		return st.isSocket() && st.uid === (process.getuid?.() ?? st.uid);
+	} catch {
+		return false;
+	}
+}
+
+export interface HostSnapshot {
+	pid: number;
+	host: string;
+	startedAt: string;
+	model?: string;
+	leader: boolean;
+	runs: Array<{ runId: string; label: string; jobId: string; startedAt: string; promptPreview: string }>;
+	checks: Array<{ traceId: string; sourceLabel: string; eventLabel: string; startedAt: string; cwd: string }>;
+	jobs: { enabled: number; total: number };
+	rules: { enabled: number; total: number };
+	inboxNew: number;
+	mcp: Array<{ name: string; state: string; lastError?: string }>;
+	/** The last few runs, newest first: a host that has been failing for hours must not look idle. */
+	recent?: Array<{ job: string; at: string; ok: boolean; error?: string; cost?: number }>;
+	/** Jobs currently carrying an error, and when anything is next due. */
+	failing?: Array<{ job: string; error: string }>;
+	nextDue?: string;
+	/** Today's spend against the cap, when one is configured. */
+	budget?: { spent: number; cap: number };
+}
+
+export type HostRequest = { op: "status" } | { op: "abort"; runId?: string; traceId?: string } | { op: "stop" };
+export type HostResponse = { ok: true; snapshot?: HostSnapshot; aborted?: boolean } | { ok: false; error: string };
+
+export interface HostChannelHandlers {
+	status: () => HostSnapshot;
+	abortRun: (runId: string) => boolean;
+	abortCheck: (traceId: string) => boolean;
+	stop: () => void;
+}
+
+/** One newline-delimited JSON request per connection, answered and closed. */
+export function serveHostChannel(dir: string, handlers: HostChannelHandlers, log?: (message: string) => void): net.Server {
+	const socketPath = hostSocketPath(dir);
+	if (!prepareSocketDir(socketPath, log)) return net.createServer();
+	// The directory holds prompts, findings, transcripts and now a control socket: it is the
+	// owner's alone. `listen()` creates the socket with the process umask (0775 under umask 002)
+	// and only chmods afterwards, so the directory mode is what closes that window.
+	fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+	try {
+		fs.chmodSync(dir, 0o700);
+	} catch (err: any) {
+		log?.(`could not restrict ${dir} to this user: ${err?.message ?? err}`);
+	}
+	try {
+		// `force` only swallows ENOENT: in a sticky temp directory this can be EPERM, and an
+		// unhandled throw here would take the whole host down at startup.
+		if (ownedSocket(socketPath)) fs.rmSync(socketPath, { force: true }); // left by a crashed host
+		else if (fs.existsSync(socketPath)) throw new Error(`${socketPath} exists and is not ours`);
+	} catch (err: any) {
+		log?.(`control channel: ${err?.message ?? err}`);
+		return net.createServer(); // an unbound server: the host runs, `host status` falls back to the pid
+	}
+	const server = net.createServer((socket) => {
+		socket.setEncoding("utf8");
+		let buf = "";
+		socket.on("data", (chunk) => {
+			buf += chunk;
+			const nl = buf.indexOf("\n");
+			if (nl < 0) {
+				if (buf.length > 4096) socket.destroy();
+				return;
+			}
+			let response: HostResponse;
+			try {
+				const req = JSON.parse(buf.slice(0, nl)) as HostRequest;
+				if (req.op === "status") response = { ok: true, snapshot: handlers.status() };
+				else if (req.op === "abort") response = { ok: true, aborted: req.runId ? handlers.abortRun(req.runId) : req.traceId ? handlers.abortCheck(req.traceId) : false };
+				else if (req.op === "stop") {
+					response = { ok: true };
+					setTimeout(() => handlers.stop(), 50).unref?.();
+				} else response = { ok: false, error: `unknown op ${JSON.stringify((req as any).op)}` };
+			} catch (err: any) {
+				response = { ok: false, error: err?.message ?? String(err) };
+			}
+			socket.end(`${JSON.stringify(response)}\n`, () => socket.destroy());
+			buf = "";
+			socket.removeAllListeners("data"); // one request per connection, never replayed
+		});
+		socket.on("error", () => socket.destroy());
+		socket.setTimeout(10_000, () => socket.destroy());
+	});
+	server.on("error", (err: any) => log?.(`control channel: ${err?.message ?? err}`));
+	server.listen(socketPath, () => {
+		try {
+			fs.chmodSync(socketPath, 0o600);
+		} catch (err: any) {
+			// Never leave a reachable control socket behind because a chmod failed.
+			log?.(`could not restrict the control socket; closing it: ${err?.message ?? err}`);
+			server.close();
+		}
+	});
+	server.unref();
+	return server;
+}
+
+/** Ask a running host something. Returns undefined when no host is listening. */
+export function askHost(dir: string, request: HostRequest, timeoutMs = 2000): Promise<HostResponse | undefined> {
+	const socketPath = hostSocketPath(dir);
+	return new Promise((resolve) => {
+		// Not just "does it exist": whoever is listening there gets to answer for the host, and this
+		// answer decides whether `host stop` sends a signal. Someone else's socket is no host at all.
+		if (!ownedSocket(socketPath)) return resolve(undefined);
+		const socket = net.createConnection(socketPath);
+		let buf = "";
+		const done = (value: HostResponse | undefined) => {
+			socket.destroy();
+			resolve(value);
+		};
+		const timer = setTimeout(() => done(undefined), timeoutMs);
+		timer.unref?.();
+		socket.setEncoding("utf8");
+		socket.on("connect", () => socket.write(`${JSON.stringify(request)}\n`));
+		socket.on("data", (chunk) => {
+			buf += chunk;
+			const nl = buf.indexOf("\n");
+			if (nl < 0) return;
+			clearTimeout(timer);
+			try {
+				done(JSON.parse(buf.slice(0, nl)) as HostResponse);
+			} catch {
+				done(undefined);
+			}
+		});
+		socket.on("error", () => {
+			clearTimeout(timer);
+			done(undefined);
+		});
+	});
+}
+
+/**
+ * Everything here arrived over a socket and is printed to a terminal. Even with the socket
+ * ownership-checked, a snapshot is data from another process: escape sequences would repaint the
+ * lines around it, and a number that is not a number would throw out of `toFixed`.
+ */
+function line(text: unknown): string {
+	return String(text ?? "").replace(/[\u0000-\u001f\u007f-\u009f]/g, " ");
+}
+function money(n: unknown, digits: number): string {
+	return Number.isFinite(Number(n)) ? Number(n).toFixed(digits) : "?";
+}
+
+/** The lines `/cron host` shows for a live host. */
+export function renderHostSnapshot(s: HostSnapshot): string[] {
+	const lines = [
+		`  pid ${line(s.pid)} on ${line(s.host)}, started ${line(s.startedAt)}${s.model ? `, model ${line(s.model)}` : ""}`,
+		`  ${s.leader ? "owns the clock" : "standby"} · ${line(s.jobs?.enabled)}/${line(s.jobs?.total)} loop(s), ${line(s.rules?.enabled)}/${line(s.rules?.total)} rule(s) enabled · inbox: ${line(s.inboxNew)} new`,
+	];
+	for (const r of s.runs ?? []) lines.push(`  running ${line(r.label)} (${line(r.runId).slice(0, 12)}) since ${line(r.startedAt)}: ${line(r.promptPreview)}`);
+	for (const c of s.checks ?? []) lines.push(`  checking ${line(c.sourceLabel)}/${line(c.eventLabel)} (${line(c.traceId).slice(0, 8)}) in ${line(c.cwd)}`);
+	for (const m of s.mcp ?? []) lines.push(`  mcp ${line(m.name)}: ${line(m.state)}${m.lastError ? ` — ${line(m.lastError)}` : ""}`);
+	if (!s.runs?.length && !s.checks?.length) lines.push(`  nothing running right now${s.nextDue ? ` · next due ${line(s.nextDue)}` : ""}`);
+	if (s.budget && Number(s.budget.cap) > 0) lines.push(`  spent today: $${money(s.budget.spent, 2)} of $${money(s.budget.cap, 2)}${Number(s.budget.spent) >= Number(s.budget.cap) ? " — dispatching is paused" : ""}`);
+	for (const f of s.failing ?? []) lines.push(`  ! ${line(f.job)}: ${line(f.error)}`);
+	for (const r of s.recent ?? []) lines.push(`  ${r.ok ? "ok  " : "FAIL"} ${line(r.at)}  ${line(r.job)}${r.cost ? ` · $${money(r.cost, 3)}` : ""}${r.error ? ` — ${line(r.error)}` : ""}`);
+	return lines;
+}