@alphacoder-v0/pi-loops 0.17.3

package/src/host.ts

@@ -0,0 +1,329 @@
+/**
+ * The headless host — pi-loops with no pi window. Started by the last interactive pi to quit
+ * (`host-control.ts`), it keeps the clock on this machine: stateful loops, dynamic trigger checks
+ * for every project, MCP pushes, catch-up — with the same stores, the same in-process sub-agent
+ * runner (pi's SDK) and its own MCP client instances. Chat-bound results go to the inbox. The
+ * first interactive pi to open takes the clock back (its scheduler preempts a "host" leader) and
+ * this process exits. Nothing restarts it after a reboot until a pi opens.
+ *
+ *   node --import <pkg>/src/register-pi.mjs <pkg>/src/host-entry.mjs   (env: PI_LOOPS_DIR, PI_LOOPS_PI_PACKAGE)
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { ModelRuntime, ProjectTrustStore, SettingsManager, getAgentDir, readStoredCredential, type ToolDefinition } from "@earendil-works/pi-coding-agent";
+import type { Model } from "@earendil-works/pi-ai";
+import { loadConfig } from "./config.ts";
+import { computeNext, stamp } from "./schedule.ts";
+import { hostSocketPath, serveHostChannel } from "./host-control-channel.ts";
+import { HOST_LOG, clearHostRecord, hostProcessMatches, readHost, writeHostRecord } from "./host-control.ts";
+import { THINKING_LEVELS, thinkingLevelOrUndefined } from "./thinking.ts";
+import { withFileLock } from "./lock.ts";
+import { rotateInPlace } from "./log.ts";
+import { createHostRuntime } from "./host-runtime.ts";
+import { McpPool } from "./mcp-pool.ts";
+import { McpSource, droppedNotificationMessage, loadMcpConfigFiles, mapNotification, mcpToolDefinitions, mcpTokenFromEnv } from "./mcp.ts";
+import { previewRedacted, redact } from "./redact.ts";
+import { parentRuntimeFlags } from "./runner.ts";
+import type { SessionSnapshot } from "./scheduler.ts";
+import { createInProcessRunner } from "./sdk-runner.ts";
+import { defaultLoopsDir } from "./store.ts";
+import { isExactlyTrusted } from "./trust.ts";
+import { PI_LOOPS_VERSION } from "./version.ts";
+
+const agentDir = getAgentDir();
+const dir = process.env.PI_LOOPS_DIR || defaultLoopsDir(agentDir);
+const PACKAGE_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+fs.mkdirSync(dir, { recursive: true });
+const logFile = path.join(dir, HOST_LOG);
+const log = (msg: string) => {
+	const line = `${stamp()} ${redact(msg)}\n`;
+	try {
+		fs.appendFileSync(logFile, line);
+		// The host's stdout and stderr are this file too (host-control.ts), so a chatty MCP server
+		// writes here as well. It is the one file a user is told to read; keep it readable — by the
+		// same rule as every other log in this project, which lives in src/log.ts.
+		rotateInPlace(logFile);
+	} catch {
+		process.stderr.write(line);
+	}
+};
+
+let config = loadConfig(dir);
+/**
+ * Every config error this host has already said, so the 60-second re-read below can say a *new* one
+ * without repeating the old ones every minute. An error introduced by editing `config.toml` while
+ * the host is up was silently ignored for the rest of its life: the setting fell back to its
+ * default, and the only record of why was in a file nobody re-read.
+ */
+const saidConfigErrors = new Set<string>();
+function logConfigErrors(): void {
+	for (const e of config.errors) {
+		if (saidConfigErrors.has(e)) continue;
+		saidConfigErrors.add(e);
+		log(`config: ${e}`);
+	}
+}
+logConfigErrors();
+
+// The session the host "is": no chat, no project; for unpinned work, the model and thinking level
+// of the pi that handed off (env), else the settings' defaults. Never "some available model".
+const settings = SettingsManager.create(os.homedir(), agentDir, { projectTrusted: false });
+const settingsModel = settings.getDefaultProvider() && settings.getDefaultModel() ? `${settings.getDefaultProvider()}/${settings.getDefaultModel()}` : undefined;
+// The environment is a boundary: `PI_LOOPS_HOST_THINKING` is whatever the process that spawned this
+// one had, and it goes straight into every model call. An unknown level is dropped out loud rather
+// than cast to one, so a provider rejecting "hgih" is not the first anyone hears of it.
+const envThinking = process.env.PI_LOOPS_HOST_THINKING;
+const handedThinking = thinkingLevelOrUndefined(envThinking);
+if (envThinking && !handedThinking) log(`ignoring PI_LOOPS_HOST_THINKING=${envThinking}: not a thinking level (${THINKING_LEVELS.join(", ")})`);
+const session: SessionSnapshot = { cwd: "", model: process.env.PI_LOOPS_HOST_MODEL || settingsModel, thinking: handedThinking || settings.getDefaultThinkingLevel(), trusted: false };
+async function defaultModel(): Promise<Model<any> | undefined> {
+	if (!session.model) return undefined;
+	const rt = await ModelRuntime.create();
+	const [provider, ...rest] = session.model.split("/");
+	return rt.getModel(provider, rest.join("/")) ?? undefined;
+}
+let parentModel: Model<any> | undefined;
+
+/* ---------------------------------------------------------------- MCP */
+
+const mcpLoaded = loadMcpConfigFiles({ dir, projectTrusted: false });
+for (const d of mcpLoaded.diagnostics) log(`mcp: ${d}`);
+const mcpSources: McpSource[] = [];
+const mcpToolDefs = new Map<string, ToolDefinition<any, any>[]>();
+const mcpToolNames = new Map<string, string[]>();
+const resolveMcpToken = (ref: string): string | undefined => {
+	const fromEnv = mcpTokenFromEnv(ref);
+	if (fromEnv) return fromEnv;
+	try {
+		const cred: any = readStoredCredential(ref);
+		if (cred && typeof cred === "object") return cred.key ?? cred.access ?? cred.token;
+		if (typeof cred === "string") return cred;
+	} catch {
+		/* no store */
+	}
+	return undefined;
+};
+
+/* ------------------------------------------------------------ runtime */
+
+const runner = createInProcessRunner({
+	agentDir,
+	parentFlags: parentRuntimeFlags([]),
+	getParentModel: () => parentModel,
+	getParentThinking: () => session.thinking,
+	customTools: (req) => host.customTools(req),
+	// Only projects the user trusted before (pi's saved decisions); the host never trusts on its own.
+	// Exact trust only (src/trust.ts): nobody is watching what a job's cwd points at.
+	isTrusted: (cwd) => isExactlyTrusted(agentDir, cwd),
+	ownDir: PACKAGE_DIR,
+	allowCommands: () => config.allowCommands,
+	// The daily cap, read while a run is in flight and not only before it is dispatched. Lazy: the
+	// host owns the scheduler and is built with this runner, so it can only be asked at run time.
+	budget: () => host.scheduler.budgetState(),
+	log: (msg) => log(`sub-agent: ${msg}`),
+});
+/** Project-level MCP servers, connected on demand: the host itself has no project. */
+const mcpPool = new McpPool({ isTrusted: (cwd) => isExactlyTrusted(agentDir, cwd), resolveToken: resolveMcpToken, log: (msg) => log(`mcp pool: ${msg}`) });
+const host = createHostRuntime({
+	dir,
+	config: () => config,
+	session: () => session,
+	runner,
+	mcpTools: () => [...mcpToolDefs.values()].flat(),
+	projectMcpTools: (cwd, taken) => mcpPool.toolsFor(cwd, taken),
+	// Project-local hooks.toml: the same exact-trust rule as a project's MCP servers and tools.
+	isProjectTrusted: (cwd) => isExactlyTrusted(agentDir, cwd),
+	log,
+	exit: (code) => shutdown(code),
+});
+
+function startMcpSources(): void {
+	for (const cfg of mcpLoaded.servers) {
+		const source = new McpSource(cfg, {
+			onConnected: async (src) => {
+				let tools;
+				try {
+					tools = await src.listTools();
+				} catch (err: any) {
+					src.status.lastError = `tools/list failed: ${err?.message ?? err}`;
+					return;
+				}
+				const already = mcpToolNames.get(cfg.name) ?? [];
+				const defs = mcpToolDefs.get(cfg.name) ?? [];
+				const taken = new Set([...mcpToolDefs.values()].flat().map((d) => d.name));
+				for (const { def } of mcpToolDefinitions(src, tools, taken, already)) defs.push(def);
+				mcpToolNames.set(cfg.name, already);
+				mcpToolDefs.set(cfg.name, defs);
+				log(`mcp ${cfg.name}: connected, ${already.length} tool(s)`);
+			},
+			onNotification: (n) => {
+				const trigger = mapNotification(cfg.name, n);
+				if (!trigger) {
+					source.status.droppedCount++;
+					source.status.lastError = droppedNotificationMessage(n.method);
+					return;
+				}
+				const delivery = cfg.injectAndRun ? "inject_and_run" : cfg.injectSummary ? "inject_summary" : "sub_agent";
+				void host.triggers.handle(trigger, delivery).catch((err) => log(`trigger: ${err?.message ?? err}`));
+			},
+			resolveToken: resolveMcpToken,
+			log: (msg) => log(`mcp ${cfg.name}: ${previewRedacted(msg, 200)}`),
+		});
+		mcpSources.push(source);
+		source.start();
+	}
+}
+
+/* ------------------------------------------------------------ lifecycle */
+
+let stopping = false;
+async function shutdown(code: number): Promise<void> {
+	if (stopping) return;
+	stopping = true;
+	// Whatever hangs (a lock, an MCP server that will not die), the process leaves.
+	setTimeout(() => process.exit(code), 10_000).unref();
+	try {
+		await host.stop();
+		await mcpPool.stopAll();
+		await Promise.all(mcpSources.map((s) => s.stop()));
+	} catch (err: any) {
+		log(`shutdown: ${err?.message ?? err}`);
+	}
+	try {
+		channel?.close();
+		fs.rmSync(hostSocketPath(dir), { force: true });
+	} catch {
+		/* going away anyway */
+	}
+	// A clean exit removes the record; a crash leaves it so the next pi can say the host died.
+	if (code === 0) clearHostRecord(dir, process.pid);
+	log(`host stopped (exit ${code})`);
+	process.exit(code);
+}
+// `shutdown` stops stores, MCP servers and the scheduler; any of them can reject, and the process
+// is on its way out — so the exit does not depend on the shutdown succeeding.
+const leave = (code: number) => void shutdown(code).catch((err: any) => {
+	log(`shutdown failed: ${err?.message ?? err}`);
+	process.exit(code);
+});
+process.on("SIGTERM", () => leave(0));
+process.on("SIGINT", () => leave(0));
+process.on("uncaughtException", (err) => {
+	log(`uncaught: ${redact(String(err?.stack ?? err))}`);
+	leave(1);
+});
+process.on("unhandledRejection", (err: any) => log(`unhandled rejection: ${redact(String(err?.stack ?? err))}`));
+
+// One host per machine: two pis quitting together may both spawn one; the second to get here
+// leaves without touching the first's record (host.json names the survivor, so /cron host and
+// crash detection keep working).
+const claimed = await withFileLock(path.join(dir, "host.lock"), () => {
+	const other = readHost(dir);
+	if (other && other.pid !== process.pid && other.host === os.hostname() && hostProcessMatches(other)) return false;
+	writeHostRecord(dir, { pid: process.pid, host: os.hostname(), startedAt: stamp(), node: process.execPath, entry: process.argv[1] });
+	return true;
+});
+if (!claimed) {
+	log(`another host is already running (pid ${readHost(dir)?.pid}); exiting`);
+	process.exit(0);
+}
+log(`pi-loops ${PI_LOOPS_VERSION} headless host started (pid ${process.pid}, dir ${dir})`);
+// A window into a process with no chat: `/cron host` and `pi-loops host status` read this.
+const startedAt = stamp();
+/**
+ * A control channel that cannot be opened is a degraded host, not a dead one: `pi-loops host
+ * status` falls back to the recorded pid, and the loops keep running. This is the top level of the
+ * process, so a throw here would take the host down at startup instead.
+ */
+function serveHostChannelSafely(...args: Parameters<typeof serveHostChannel>): ReturnType<typeof serveHostChannel> | undefined {
+	try {
+		return serveHostChannel(...args);
+	} catch (err: any) {
+		log(`control channel unavailable: ${err?.message ?? err}`);
+		return undefined;
+	}
+}
+
+const channel = serveHostChannelSafely(
+	dir,
+	{
+		status: () => {
+			// One read of each store for the whole snapshot. jobs.json was read four times and
+			// triggers.json twice, so a tick landing in between could have `enabled` counted against
+			// one version of the file and `total` against another — a status line contradicting itself.
+			const jobs = host.scheduler.store.load();
+			const rules = host.triggers.store.load();
+			return {
+				pid: process.pid,
+				host: os.hostname(),
+				startedAt,
+				model: session.model,
+				leader: host.scheduler.isLeader,
+				runs: host.scheduler.runningRuns(),
+				checks: host.triggers.runningList().map((r) => ({ traceId: r.traceId, sourceLabel: r.sourceLabel, eventLabel: r.eventLabel, startedAt: r.startedAt, cwd: r.cwd })),
+				jobs: { enabled: jobs.filter((j) => j.enabled).length, total: jobs.length },
+				rules: { enabled: rules.filter((r) => r.enabled).length, total: rules.length },
+				inboxNew: host.scheduler.inbox.newCount(),
+				// Without these a host that has failed every run for six hours reads exactly like one
+				// that succeeded an hour ago: "nothing running right now".
+				recent: host.scheduler.store
+					.listRuns(undefined, 5)
+					.reverse()
+					.map((r) => ({ job: r.jobName ?? r.jobId, at: r.finishedAt, ok: r.ok, error: r.error ? previewRedacted(r.error, 100) : undefined, cost: r.usage?.cost })),
+				failing: jobs.filter((j) => j.enabled && j.lastError).map((j) => ({ job: j.name ?? j.id, error: previewRedacted(j.lastError ?? "", 120) })),
+				nextDue: (() => {
+					const next = jobs
+						.filter((j) => j.enabled && j.stateful)
+						.map((j) => computeNext({ schedule: j.schedule, createdAt: Date.parse(j.createdAt), lastFiredAt: j.lastFiredAt ? Date.parse(j.lastFiredAt) : undefined }, Date.now()))
+						.filter((n): n is number => n !== undefined)
+						.sort((a, b) => a - b)[0];
+					return next ? stamp(next) : undefined;
+				})(),
+				budget: (() => {
+					const b = host.scheduler.budgetState();
+					return b.cap > 0 ? { spent: b.spent, cap: b.cap } : undefined;
+				})(),
+				mcp: mcpSources.map((s) => ({ name: s.config.name, state: s.status.state, lastError: s.status.lastError ? previewRedacted(s.status.lastError, 120) : undefined })),
+			};
+		},
+		// The status lines show shortened ids, so that is what a watcher types back.
+		abortRun: (runId) => {
+			const match = host.scheduler.runningRuns().find((r) => r.runId === runId || r.runId.startsWith(runId));
+			return match ? host.scheduler.abortRun(match.runId) : false;
+		},
+		abortCheck: (traceId) => {
+			const match = host.triggers.runningList().find((r) => r.traceId === traceId || r.traceId.startsWith(traceId));
+			return match ? host.triggers.abort(match.traceId) : false;
+		},
+		stop: () => leave(0),
+	},
+	log,
+);
+parentModel = await defaultModel().catch((err) => {
+	log(`default model: ${err?.message ?? err}`);
+	return undefined;
+});
+log(`default model: ${parentModel ? `${parentModel.provider}/${parentModel.id}` : "none (jobs must pin one)"}`);
+startMcpSources();
+host.start();
+// The scheduler's timer is unref'd (an extension must never keep pi alive); the host wants to live,
+// and re-reads config.toml so edits take effect without a restart.
+setInterval(() => {
+	config = loadConfig(dir);
+	logConfigErrors();
+	host.triggers.pollIntervalSecs = config.triggerPollIntervalSecs;
+	host.triggers.runTimeoutMs = config.triggerRunTimeoutMs;
+	// And the model, on the same minute. This process can live for days: a credential added with
+	// `/login` in a pi that opened after the hand-off, or a provider that started resolving, would
+	// otherwise never reach it — `parentModel` was resolved once, at startup. Only an improvement is
+	// taken: a model that stops resolving leaves the one the host already has in place.
+	void defaultModel()
+		.then((model) => {
+			if (!model || (parentModel && parentModel.provider === model.provider && parentModel.id === model.id)) return;
+			parentModel = model;
+			log(`default model: ${model.provider}/${model.id}`);
+		})
+		.catch((err: any) => log(`default model: ${err?.message ?? err}`));
+}, 60_000);

package/src/inbox.ts

@@ -0,0 +1,232 @@
+/**
+ * The triage inbox — the routing layer. Global JSONL shared by every session and
+ * project: loops run wherever they were created; the inbox is what you open in
+ * the morning. Findings are one-liners with a new → claimed/dismissed lifecycle.
+ *
+ * Appends are line-atomic; status rewrites are serialized through a file lock.
+ * Corrupt lines are skipped on read, never deleted.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { withFileLock, writeFileAtomic } from "./lock.ts";
+import { INBOX_TEXT_MAX_CHARS, capChars } from "./protocol.ts";
+import { newId } from "./store.ts";
+import { stamp } from "./schedule.ts";
+
+export type InboxStatus = "new" | "claimed" | "dismissed";
+
+/** Past this the inbox drops its oldest triaged entries (docs/configuration.md). */
+export const INBOX_ROTATE_BYTES = 1_000_000;
+
+export interface InboxEntry {
+	id: string;
+	createdAt: string;
+	/** Bounded origin label, e.g. "cron:check-issues" or "cron:cron-1a2b3c4d". */
+	source: string;
+	text: string;
+	runId: string;
+	jobId: string;
+	cwd: string;
+	/** Session that owned the loop when it reported; loops are machine-global here. */
+	sessionId?: string;
+	status: InboxStatus;
+	claimedBy?: string;
+	/** true = passed the checker; false = checker dropped it (never appended); undefined = no checker / unreviewed. */
+	verified?: boolean;
+	/** Checker's reason when it kept a finding, if it gave one. */
+	verifiedReason?: string;
+}
+
+export class Inbox {
+	readonly file: string;
+	private readonly lockPath: string;
+
+	constructor(dir: string) {
+		this.file = path.join(dir, "inbox.jsonl");
+		this.lockPath = path.join(dir, "inbox.lock");
+	}
+
+	async append(entry: Omit<InboxEntry, "id" | "createdAt" | "status">): Promise<InboxEntry> {
+		const full: InboxEntry = {
+			id: newId("inb"), // inb-<32 hex>, the shape every other id in pi-loops has
+			createdAt: stamp(),
+			...entry,
+			source: capChars(entry.source, 80),
+			text: capChars(entry.text.replace(/\s+/g, " "), INBOX_TEXT_MAX_CHARS),
+			status: "new",
+		};
+		fs.mkdirSync(path.dirname(this.file), { recursive: true });
+		// Under the same lock as the triage rewrites: findings are appended by every pi window, the
+		// headless host and up to `max_concurrent_runs` loop runs, while `/inbox dismiss|clear`
+		// rewrites the whole file — an append landing mid-rewrite is a finding nobody ever sees.
+		// The lock is awaited, never spun on: a leftover lock directory from a killed process would
+		// otherwise block this process's event loop for the whole stale window.
+		await withFileLock(this.lockPath, () => {
+			fs.appendFileSync(this.file, `${JSON.stringify(toDisk(full))}\n`, "utf8");
+			this.rotate();
+		});
+		return full;
+	}
+
+	/**
+	 * Past `INBOX_ROTATE_BYTES`, drop the oldest already-triaged entries (`claimed`/`dismissed`) —
+	 * never anything still `new`, which is the whole point of the inbox, and the reason this is not the
+	 * blind halving the run log and the audit use. This file was the one that grew forever, and
+	 * `newCount()` re-parses it on every badge refresh. Caller holds the lock.
+	 */
+	private rotate(): void {
+		try {
+			if (fs.statSync(this.file).size < INBOX_ROTATE_BYTES) return;
+			const entries = this.list();
+			const triaged = entries.filter((e) => e.status !== "new");
+			const drop = Math.floor(triaged.length / 2);
+			// Nothing triaged to drop means an inbox full of unread findings: rewriting it would
+			// change nothing and would cost a full read+write on every append from here on.
+			if (drop === 0) return;
+			const dropped = new Set(triaged.slice(0, drop).map((e) => e.id));
+			this.rewrite(entries.filter((e) => !dropped.has(e.id)));
+		} catch {
+			/* best effort: a rotation that fails must never lose the append that just succeeded */
+		}
+	}
+
+	/** All entries, oldest first. Unparseable lines are skipped. */
+	list(): InboxEntry[] {
+		let text: string;
+		try {
+			text = fs.readFileSync(this.file, "utf8");
+		} catch (err: any) {
+			if (err?.code === "ENOENT") return [];
+			throw err;
+		}
+		const out: InboxEntry[] = [];
+		for (const line of text.split("\n")) {
+			if (!line.trim()) continue;
+			try {
+				const e = fromDisk(JSON.parse(line));
+				if (e && typeof e.id === "string" && typeof e.text === "string") out.push(e);
+			} catch {
+				/* skip corrupt line */
+			}
+		}
+		return out;
+	}
+
+	listNew(): InboxEntry[] {
+		return this.list().filter((e) => e.status === "new");
+	}
+
+	/** Count of new entries; 0 on any error (badge path must never throw). */
+	newCount(): number {
+		try {
+			return this.listNew().length;
+		} catch {
+			return 0;
+		}
+	}
+
+	async setStatus(id: string, status: InboxStatus, claimedBy?: string): Promise<InboxEntry | undefined> {
+		return withFileLock(this.lockPath, () => {
+			const entries = this.list();
+			const entry = entries.find((e) => e.id === id);
+			if (!entry) return undefined;
+			entry.status = status;
+			if (claimedBy) entry.claimedBy = claimedBy;
+			this.rewrite(entries);
+			return entry;
+		});
+	}
+
+	/** `match` limits it to what the caller listed — `/inbox clear` must not dismiss findings it did not show. */
+	async dismissAllNew(match?: (entry: InboxEntry) => boolean): Promise<number> {
+		return withFileLock(this.lockPath, () => {
+			const entries = this.list();
+			let changed = 0;
+			for (const e of entries) {
+				if (e.status === "new" && (!match || match(e))) {
+					e.status = "dismissed";
+					changed++;
+				}
+			}
+			if (changed) this.rewrite(entries);
+			return changed;
+		});
+	}
+
+	private rewrite(entries: InboxEntry[]): void {
+		writeFileAtomic(this.file, entries.map((e) => JSON.stringify(toDisk(e))).join("\n") + (entries.length ? "\n" : ""));
+	}
+}
+
+/**
+ * On disk the record shape is `{id, created_at, source, text, trace_id, session_id,
+ * status}` — plus pi-loops' extras (`job_id`, `cwd`, `claimed_by`, `verified`, `verified_reason`),
+ * so a reader of that shape can consume it. Lines written by pi-loops ≤ 0.1.2 (camelCase)
+ * are still understood.
+ */
+function toDisk(e: InboxEntry): Record<string, unknown> {
+	return {
+		id: e.id,
+		created_at: e.createdAt,
+		source: e.source,
+		text: e.text,
+		trace_id: e.runId,
+		session_id: e.sessionId ?? null,
+		status: e.status,
+		job_id: e.jobId,
+		cwd: e.cwd,
+		...(e.claimedBy !== undefined ? { claimed_by: e.claimedBy } : {}),
+		...(e.verified !== undefined ? { verified: e.verified } : {}),
+		...(e.verifiedReason !== undefined ? { verified_reason: e.verifiedReason } : {}),
+	};
+}
+
+function fromDisk(raw: any): InboxEntry | undefined {
+	if (!raw || typeof raw !== "object") return undefined;
+	const pick = <T>(...keys: string[]): T | undefined => {
+		for (const k of keys) if (raw[k] !== undefined && raw[k] !== null) return raw[k] as T;
+		return undefined;
+	};
+	const status = pick<string>("status");
+	return {
+		id: String(raw.id ?? ""),
+		createdAt: pick<string>("created_at", "createdAt") ?? "",
+		source: pick<string>("source") ?? "",
+		text: String(raw.text ?? ""),
+		runId: pick<string>("trace_id", "runId") ?? "",
+		jobId: pick<string>("job_id", "jobId") ?? "",
+		cwd: pick<string>("cwd") ?? "",
+		sessionId: pick<string>("session_id", "sessionId"),
+		status: status === "claimed" || status === "dismissed" ? status : "new",
+		claimedBy: pick<string>("claimed_by", "claimedBy"),
+		verified: pick<boolean>("verified"),
+		verifiedReason: pick<string>("verified_reason", "verifiedReason"),
+	};
+}
+
+/**
+ * The findings that belong to one project, in list order. The inbox is machine-wide because loops
+ * are; triage is not — a finding about another repository read in this one is guesswork, and
+ * claiming it runs it in the wrong directory. `/inbox` lists these the way `/cron` lists this
+ * project's jobs, with `--all` for the machine.
+ *
+ * `sameProject` is the caller's test (a worktree, a symlink or a subdirectory is the same project).
+ * A finding written without a cwd belongs to no project and is never hidden by the filter.
+ */
+export function inProject(entries: InboxEntry[], cwd: string, sameProject: (a: string, b: string) => boolean): InboxEntry[] {
+	return entries.filter((e) => belongsToProject(e, cwd, sameProject));
+}
+
+/** The same test for one finding — `/inbox clear` dismisses exactly what `/inbox` listed. */
+export function belongsToProject(entry: InboxEntry, cwd: string, sameProject: (a: string, b: string) => boolean): boolean {
+	return !entry.cwd || sameProject(entry.cwd, cwd);
+}
+
+/** Resolve "<n>" (1-based in the new list) or an id / unique id prefix. */
+export function resolveInboxRef(entries: InboxEntry[], ref: string): InboxEntry | undefined {
+	const trimmed = ref.trim();
+	if (!trimmed) return undefined;
+	if (/^\d+$/.test(trimmed)) return entries[Number(trimmed) - 1];
+	const matches = entries.filter((e) => e.id === trimmed || e.id.startsWith(trimmed));
+	return matches.length === 1 ? matches[0] : undefined;
+}

package/src/job-edit.ts

@@ -0,0 +1,113 @@
+/**
+ * What `/cron set` decides, as a function instead of a closure.
+ *
+ * The command handler lives inside the extension's default export, where nothing can import it, so
+ * everything it decided was covered by reading rather than by tests — and what it decides is not
+ * obvious: which stamp to anchor when a schedule changes, whether the job is now due at once,
+ * whether an expression that parses will ever match. This module holds those decisions; the
+ * handler is left with reading arguments, writing the store and printing.
+ *
+ * It returns a *patch*, not a whole job, on purpose. `JobStore.update` re-reads the job under a
+ * lock, so a tick that started a run between the read and the write has already set `running` —
+ * assigning a whole job built from a stale copy would erase it.
+ */
+import { computeDue, computeNext, formatSchedule, stamp, type Schedule } from "./schedule.ts";
+import type { LoopJob } from "./store.ts";
+
+export interface JobEdit {
+	model?: string | null;
+	thinking?: string | null;
+	timeoutMs?: number | null;
+	name?: string | null;
+	/** "here" pins the job to this machine; null lets any machine run it. */
+	host?: string | null;
+	prompt?: string;
+	schedule?: Schedule;
+}
+
+/** When the job runs next, for the confirmation. `due` means the next tick will fire it. */
+export type NextRun = { kind: "disabled" } | { kind: "due" } | { kind: "at"; at: number } | { kind: "none" };
+
+export interface AppliedJobEdit {
+	/** Exactly the fields to write. Anything absent must keep whatever the store has. */
+	patch: Partial<LoopJob>;
+	/** One line per field a person would not otherwise be able to recover, for the log. */
+	changed: string[];
+	nextRun: NextRun;
+}
+
+export interface JobEditContext {
+	now: number;
+	hostName: string;
+	maxPromptBytes: number;
+	/** Called with the requested name and the other jobs; throws if it is not usable as a reference. */
+	checkName: (name: string, others: LoopJob[]) => void;
+	/** Every other job, for the name check. The job being edited must not be in here. */
+	others: LoopJob[];
+}
+
+/**
+ * Apply `edit` to `job`. Throws — leaving the caller nothing to write — when the result would be a
+ * job that cannot run or cannot be referred to.
+ */
+export function applyJobEdit(job: LoopJob, edit: JobEdit, ctx: JobEditContext): AppliedJobEdit {
+	if (edit.prompt !== undefined) {
+		if (!edit.prompt.trim()) throw new Error("cron action cannot be empty");
+		if (Buffer.byteLength(edit.prompt, "utf8") > ctx.maxPromptBytes) throw new Error(`cron action exceeds ${ctx.maxPromptBytes} bytes`);
+	}
+	if (edit.name) ctx.checkName(edit.name, ctx.others);
+	// A one-shot is spent by running, and the scheduler deletes it afterwards — which would take the
+	// loop's notes with it. That is the opposite of why editing in place exists.
+	if (edit.schedule?.kind === "once") throw new Error("a job cannot be changed to a one-shot schedule; /cron run <id> runs it now instead");
+
+	const patch: Partial<LoopJob> = {};
+	const changed: string[] = [];
+	if (edit.model !== undefined) patch.model = edit.model ?? undefined;
+	if (edit.thinking !== undefined) patch.thinking = edit.thinking ?? undefined;
+	if (edit.timeoutMs !== undefined) patch.timeoutMs = edit.timeoutMs ?? undefined;
+	if (edit.name !== undefined) patch.name = edit.name ?? undefined;
+	if (edit.host !== undefined) patch.host = edit.host === "here" ? ctx.hostName : undefined;
+	if (edit.prompt !== undefined) {
+		patch.prompt = edit.prompt;
+		// The old wording is otherwise unrecoverable, and it is what ties "this loop started
+		// behaving differently" to the edit that caused it. Only when it actually changed.
+		if (edit.prompt !== job.prompt) changed.push(`prompt changed from ${JSON.stringify(job.prompt)} to ${JSON.stringify(edit.prompt)}`);
+	}
+
+	const schedule = edit.schedule ?? job.schedule;
+	const createdAt = Date.parse(job.createdAt);
+	const lastFiredAt = job.lastFiredAt ? Date.parse(job.lastFiredAt) : undefined;
+	if (edit.schedule !== undefined) {
+		// An expression can parse and still never match ("0 0 30 2 *"): the job would go quiet with
+		// nothing to see. Refuse it, so the caller writes nothing.
+		if (computeNext({ schedule, createdAt, lastFiredAt }, ctx.now) === undefined) {
+			throw new Error(`${formatSchedule(edit.schedule)} has no next run; the job is unchanged`);
+		}
+		patch.schedule = edit.schedule;
+		// A cron job owes every slot its expression matched since `lastDueAt`, so moving a daily job
+		// to "*/5 * * * *" at noon would owe a run at once — for a slot that only existed
+		// retroactively. Restart the clock at the edit; the first run under the new expression is its
+		// next one. An `every <dur>` job is measured from `lastFiredAt`, which is real bookkeeping and
+		// is left alone: "every 30m" means at most 30 minutes apart, so one that last ran an hour ago
+		// is genuinely overdue and should fire on the next tick.
+		patch.lastDueAt = stamp(ctx.now);
+		changed.push(`schedule changed from ${formatSchedule(job.schedule)} to ${formatSchedule(edit.schedule)}`);
+	}
+
+	const merged = { ...job, ...patch };
+	return { patch, changed, nextRun: nextRunOf(merged, ctx.now) };
+}
+
+/** Read the job back exactly as the scheduler will, so the confirmation cannot promise a fiction. */
+export function nextRunOf(job: LoopJob, now: number): NextRun {
+	if (!job.enabled) return { kind: "disabled" };
+	const input = {
+		schedule: job.schedule,
+		createdAt: Date.parse(job.createdAt),
+		lastDueAt: job.lastDueAt ? Date.parse(job.lastDueAt) : undefined,
+		lastFiredAt: job.lastFiredAt ? Date.parse(job.lastFiredAt) : undefined,
+	};
+	if (computeDue(input, now) !== undefined) return { kind: "due" };
+	const at = computeNext(input, now);
+	return at === undefined ? { kind: "none" } : { kind: "at", at };
+}