@alphacoder-v0/pi-loops 0.22.7 → 0.24.0

package/src/job-health.ts

@@ -8,6 +8,8 @@
  */
 import { FAILURE_BACKOFF_AFTER } from "./scheduler.ts";
 import type { LoopJob } from "./store.ts";
+import { CHECK_FAILURE_BACKOFF_AFTER } from "./trigger-runtime.ts";
+import type { DynamicTriggerRule } from "./triggers.ts";
 
 /**
  * Jobs failing, worst first. The threshold is the scheduler's backoff threshold, which
@@ -18,11 +20,21 @@ export function failingJobs(jobs: LoopJob[]): LoopJob[] {
 	return jobs.filter((j) => j.enabled && (j.consecutiveFailures ?? 0) >= FAILURE_BACKOFF_AFTER).sort((a, b) => (b.consecutiveFailures ?? 0) - (a.consecutiveFailures ?? 0));
 }
 
-/** `2 job(s) failing (check-issues ×7)` — one clause, the worst one named, whatever the count. */
+/** `2 loops failing (check-issues ×7)` — one clause, the worst one named, whatever the count. */
 export function failingSummary(jobs: LoopJob[]): string | undefined {
 	const failing = failingJobs(jobs);
 	const worst = failing[0];
 	if (!worst) return undefined;
 	const label = worst.name ?? worst.id;
-	return `${failing.length} job(s) failing (${label.length > 24 ? `${label.slice(0, 23)}…` : label} ×${worst.consecutiveFailures})`;
+	return `${failing.length} ${failing.length === 1 ? "loop" : "loops"} failing (${label.length > 24 ? `${label.slice(0, 23)}…` : label} ×${worst.consecutiveFailures})`;
+}
+
+/**
+ * `[failing ×N]` for a rule whose checks have failed often enough that the runtime polls it with a
+ * widening gap, or undefined. The threshold is the runtime's own, so the listing and the poll cannot
+ * disagree; a disabled rule is not polled, so it is not marked, as `failingJobs` skips a disabled job.
+ */
+export function ruleFailureMark(rule: Pick<DynamicTriggerRule, "enabled" | "consecutiveFailures">): string | undefined {
+	const n = rule.consecutiveFailures ?? 0;
+	return rule.enabled && n >= CHECK_FAILURE_BACKOFF_AFTER ? `[failing ×${n}]` : undefined;
 }

package/src/job-lines.ts

@@ -6,37 +6,161 @@
  * was importable no test could see one go. Everything it reads is a parameter, so a test can hand it
  * a job, a run log and an inbox and read the lines a person reads.
  */
+import { projectLabel } from "./conversation-rows.ts";
+import { formatWait, queueOrder, queuedPrompt } from "./engine.ts";
+import { shortSessionId } from "./session-head.ts";
 import type { InboxEntry } from "./inbox.ts";
-import { asleepNote, runsIn } from "./job-owner.ts";
+import { asleepNote, runsSomewhere, type OwnerView } from "./job-owner.ts";
 import { QUIET_MARK_AFTER, SIGNAL_WINDOW_MS, loopSignal, signalSummary } from "./job-signal.ts";
 import { previewRedacted } from "./redact.ts";
+import type { SessionRequest } from "./requests.ts";
 import { computeNext, formatLocal, formatSchedule } from "./schedule.ts";
 import type { LoopJob, RunRecord } from "./store.ts";
+import type { DynamicTriggerRule } from "./triggers.ts";
 
 export interface JobLinesInput {
 	/** The whole run log, read once by the caller; only this listing's loops are filtered out of it. */
 	runs: RunRecord[];
 	/** The whole inbox, read once by the caller. */
 	inbox: InboxEntry[];
-	/** The session reading the list: a plain job of another session has no next run where it is. */
-	sessionId?: string;
+	/** A conversation's queued rows (`RequestStore.list`): a plain job whose prompt waits there is marked `[queued …]`. */
+	requests: (sessionId: string) => SessionRequest[];
+	/** Who holds which session, as the instance reading the list sees it: a plain job of a session nobody holds has no next run. */
+	view: OwnerView;
 	now: number;
 	/** `$HOME`, for `~` shortening; passed rather than read so a test's paths are its own. */
 	home: string;
 	/** Injected because the answer decides `[orphan: cwd missing]`, and a test should not make directories. */
 	cwdExists: (cwd: string) => boolean;
+	/** Whether each job's path is printed: only `/cron all` lists more than one project. */
+	showCwd: boolean;
 }
 
-/** The caller's `homeRel`, with `home` passed in: this module has no `process.env`. */
-const homeRel = (p: string, home: string) => (home && p.startsWith(home) ? `~${p.slice(home.length)}` : p);
+/**
+ * What a person calls a loop on every surface but the lists that take its id (`/cron`, `cron_list`,
+ * `inbox --json`): its name, else the first 13 characters of its id (`cron-` and 8 hex digits).
+ */
+export function loopLabel(job: { id: string; name?: string }): string {
+	return job.name || job.id.slice(0, 13);
+}
+
+/** A loop's generated id (`src/store.ts` newId): what the snapshot carries for a loop with no name. */
+const LOOP_ID = /^cron-[0-9a-f]{32}$/;
+
+/** A snapshot's `job` field (its name, else its id) as every surface labels the loop. */
+export function snapshotLoopLabel(job: string): string {
+	return LOOP_ID.test(job) ? loopLabel({ id: job }) : job;
+}
+
+
+/** What a queued row's source is called in `/cron queue`, the words the browser page uses for the same row. */
+export function queueSourceLabel(source: SessionRequest["source"], jobName: (id: string) => string | undefined): string {
+	const at = source.indexOf(":");
+	const [kind, arg] = at < 0 ? [source, ""] : [source.slice(0, at), source.slice(at + 1)];
+	if (source === "person") return "you";
+	if (kind === "cron") return `cron ${jobName(arg) ?? arg}`;
+	if (kind === "cron-run") return `/cron run ${jobName(arg) ?? arg}`;
+	if (kind === "rule" || kind === "inbox") return `${kind === "inbox" ? "claim" : kind} ${arg.slice(0, 8)}`;
+	if (kind === "push" || kind === "recipe") return `${kind} ${arg}`;
+	return source;
+}
+
+export interface QueueLinesInput {
+	now: number;
+	/** A plain job's name by id, for the clock's rows. */
+	jobName: (id: string) => string | undefined;
+	/** Rows pi was handed and has not written yet: listed, numbered, and said to be pi's already. */
+	inFlight: ReadonlySet<string>;
+}
+
+/**
+ * `/cron queue`: what waits for this conversation, in the order the engine offers it, one numbered
+ * line each with its source, how long it has waited and the start of its text. The numbers are what
+ * `/cron queue cancel <n>` takes, so they are the listing's and nothing else's.
+ */
+export function queueLines(rows: readonly SessionRequest[], opts: QueueLinesInput): string[] {
+	const inputs = queueOrder(rows);
+	if (!inputs.length) return ["(nothing is queued for this conversation)"];
+	return inputs.map((row, i) => {
+		const created = Date.parse(row.created_at);
+		const age = Number.isFinite(created) ? formatWait(opts.now - created) : "?";
+		const state = opts.inFlight.has(row.id) ? "handed to pi" : row.not_before && Date.parse(row.not_before) > opts.now ? `backing off${row.last_error ? `: ${previewRedacted(row.last_error, 80)}` : ""}` : row.wake === "append" ? "lands without a turn" : "waits for pi to be idle";
+		const text = previewRedacted(String(row.payload?.text ?? "").replace(/^\[Trigger [^\]]+\]\s*/, ""), 100) || (row.payload?.images?.length ? `[${plural(row.payload.images.length, "image")}]` : "");
+		return `${String(i + 1).padStart(2)}. ${queueSourceLabel(row.source, opts.jobName)} · ${age} · ${state} · ${row.id}\n    ${text}`;
+	});
+}
+
+/**
+ * Which queued row `ref` names, for `/cron queue cancel`: its number in the listing, its id, or a
+ * prefix of its id that names one row. Undefined when nothing matches; a prefix of several is nobody.
+ */
+export function pickQueued(rows: readonly SessionRequest[], ref: string): SessionRequest | undefined {
+	const inputs = queueOrder(rows);
+	const trimmed = ref.trim();
+	if (/^\d+$/.test(trimmed)) return inputs[Number(trimmed) - 1];
+	const exact = inputs.find((row) => row.id === trimmed);
+	if (exact) return exact;
+	const prefixed = trimmed ? inputs.filter((row) => row.id.startsWith(trimmed)) : [];
+	return prefixed.length === 1 ? prefixed[0] : undefined;
+}
+
+/** `1 loop`, `2 loops`: a count a person reads, never `loop(s)`. */
+export function plural(n: number, one: string, many = `${one}s`): string {
+	return `${n} ${n === 1 ? one : many}`;
+}
+
+/**
+ * The one-time line a session start says when plain jobs carry `--tools`: 0.22.8 stored the list
+ * and never used it, and since 0.23 a turn in a window asks before a tool outside it. Undefined when
+ * no enabled plain job has one. `names` are what `/cron set` takes.
+ */
+export function toolsCapNotice(jobs: readonly LoopJob[]): string | undefined {
+	const capped = jobs.filter((j) => j.enabled && !j.stateful && j.tools?.length);
+	if (!capped.length) return undefined;
+	const names = capped.map((j) => j.name ?? j.id);
+	const one = capped.length === 1;
+	return `[cron] ${plural(capped.length, "plain job")} ${one ? "has" : "have"} --tools, which now limit ${one ? "its" : "their"} turns (a tool outside the list asks you first in a window, and is refused in the background): ${names.join(", ")} — /cron set <ref> --tools - clears it`;
+}
+
+/**
+ * The one-time line a session start says about plain jobs running in the background: every enabled
+ * plain job of every conversation, since each runs there once its conversation has been opened in
+ * this pi-loops and closed again. 0.22.8 slept them while their conversation was closed, and closing
+ * it was how people stopped one. Undefined when there is none.
+ */
+export function heldJobsNotice(jobs: readonly LoopJob[]): string | undefined {
+	const plain = jobs.filter((j) => j.enabled && !j.stateful && j.sessionId);
+	if (!plain.length) return undefined;
+	const conversations = new Set(plain.map((j) => j.sessionId)).size;
+	const one = plain.length === 1;
+	return `[cron] ${plural(plain.length, "plain job")} in ${plural(conversations, "conversation")} ${one ? "runs" : "run"} in the background while ${one ? "its" : "their"} conversation is closed (once it has been opened in this pi-loops), and each run is a model turn — /cron all lists them`;
+}
+
+/**
+ * What a window says when it leaves a conversation (`/new`, `/resume`) that has plain jobs: in 0.22.8
+ * that stopped them; now they run in the background, or, with `[host] auto = false`, stop with the
+ * last window. Undefined when the conversation has none.
+ */
+export function leftConversationLine(sessionId: string, plainJobs: number, hostAuto: boolean): string | undefined {
+	if (!plainJobs) return undefined;
+	const run = plainJobs === 1 ? "runs" : "run";
+	const where = hostAuto ? `${run} in the background now, each run a model turn` : `${run} in the background while a pi window is open ([host] auto = false), each run a model turn`;
+	return `[cron] the conversation you left (${shortSessionId(sessionId)}) has ${plural(plainJobs, "plain job")} that ${where} — /cron all lists them, /cron disable <ref> stops one`;
+}
+
+/** A catch-up setting that differs from the default (loops catch up, plain jobs do not), in the flag's own spelling. */
+function catchUpMark(job: Pick<LoopJob, "stateful" | "catchUp">): string | undefined {
+	if (job.stateful) return job.catchUp ? undefined : "[no-catchup]";
+	return job.catchUp ? "[catchup]" : undefined;
+}
 
 export function jobLines(jobs: LoopJob[], opts: JobLinesInput): string[] {
-	const { runs, inbox, sessionId, now, home, cwdExists } = opts;
+	const { runs, inbox, requests, view, now, home, cwdExists, showCwd } = opts;
 	return jobs
 		.map((job, i) => {
-			// A next run is shown where it will happen: a plain job of a session not open here has none.
+			// A next run is shown when it will happen somewhere: a plain job of a session nobody holds has none.
 			const next =
-				job.enabled && runsIn(job, sessionId)
+				job.enabled && runsSomewhere(job, view)
 					? computeNext(
 							{
 								schedule: job.schedule,
@@ -46,7 +170,7 @@ export function jobLines(jobs: LoopJob[], opts: JobLinesInput): string[] {
 							now,
 						)
 					: undefined;
-			const asleepMark = asleepNote(job, sessionId);
+			const asleepMark = asleepNote(job, view);
 			const dormant = asleepMark ? `[${asleepMark}]` : undefined;
 			const orphan = job.stateful && !cwdExists(job.cwd) ? "[orphan: cwd missing]" : undefined;
 			// What the loop's runs came to (src/job-signal.ts): `quiet ×N` in the marks once N empty
@@ -54,15 +178,79 @@ export function jobLines(jobs: LoopJob[], opts: JobLinesInput): string[] {
 			// A loop was, until now, judged by whether it ran; this is whether it was worth running.
 			const signal = job.stateful ? loopSignal(job.id, runs, inbox, now - SIGNAL_WINDOW_MS) : undefined;
 			const quiet = signal && signal.quiet >= QUIET_MARK_AFTER ? `[quiet ×${signal.quiet}]` : undefined;
-			const marks = [job.stateful ? "[stateful]" : undefined, job.verify ? "[verify]" : undefined, dormant, orphan, quiet, job.running ? `running ${job.running.runId}` : undefined, job.catchUp ? undefined : "[no-catchup]"]
+			// A plain job's prompt waiting in its conversation's queue (for pi to be idle, after Esc,
+			// behind another turn): without this mark it looked exactly like one that is not queued.
+			const waiting = !job.stateful && job.sessionId ? queuedPrompt(job, requests(job.sessionId), now) : undefined;
+			const queued = waiting ? `[queued ${formatWait(now - Date.parse(waiting.since))}${waiting.reason ? ` — ${waiting.reason}` : ""}]` : undefined;
+			const marks = [job.stateful ? "[stateful]" : undefined, job.verify ? "[verify]" : undefined, dormant, orphan, quiet, queued, job.running ? `running ${job.running.runId}` : undefined, catchUpMark(job)]
 				.filter(Boolean)
 				.join("  ");
-			const head = `${String(i + 1).padStart(2)}. ${job.id}${job.name ? ` "${job.name}"` : ""}  ${job.enabled ? "enabled" : "disabled"}  ${formatSchedule(job.schedule)}${marks ? `  ${marks}` : ""}`;
+			const head = `${String(i + 1).padStart(2)}. ${job.id}${job.name ? ` "${job.name}"` : ""}${job.enabled ? "" : "  disabled"}  ${formatSchedule(job.schedule)}${marks ? `  ${marks}` : ""}`;
 			const action = `    action: ${previewRedacted(job.prompt, 120)}`;
 			const worth = signal ? signalSummary(signal) : undefined;
-			const meta = `    next ${next ? formatLocal(next) : "—"} · runs ${job.runCount}${job.skippedOverlap ? ` · skipped overlaps ${job.skippedOverlap}` : ""}${worth ? ` · 30d: ${worth}` : ""} · ${homeRel(job.cwd, home)}`;
-			const err = job.lastError ? `    last error: ${previewRedacted(job.lastError, 100)}` : job.lastFiredAt ? `    last fired: ${job.lastFiredAt}` : undefined;
+			const meta = `    next ${next ? formatLocal(next) : "—"} · runs ${job.runCount}${job.skippedOverlap ? ` · skipped overlaps ${job.skippedOverlap}` : ""}${worth ? ` · 30d: ${worth}` : ""}${showCwd ? ` · ${projectLabel(job.cwd, home)}` : ""}`;
+			const err = job.lastError ? `    last error: ${previewRedacted(job.lastError, 100)}` : job.lastFiredAt ? `    last fired: ${formatLocal(Date.parse(job.lastFiredAt))}` : undefined;
 			return [head, action, meta, err].filter((l): l is string => !!l);
 		})
 		.flat();
 }
+
+/** More than five rules or loops is a list, not a panel: `/triggers` and `/cron` have the rest. */
+const PANEL_ROW_LIMIT = 5;
+/** The latest runs; `/cron runs` has the rest. */
+export const PANEL_RUN_LIMIT = 3;
+
+export type PanelTone = "head" | "ok" | "dim" | "warn";
+
+/** What the widget shows for one project. The run line and a rule's failure mark come in made, as the run card and `/triggers` make them. */
+export interface PanelInput {
+	rules: (Pick<DynamicTriggerRule, "condition" | "action" | "enabled" | "fireOnce"> & { failureMark?: string })[];
+	/** The last rule check here; only an outcome other than `no match` or `matched N` is shown. */
+	poll?: { at: string; outcome: string };
+	jobs: LoopJob[];
+	runs: RunRecord[];
+	runText: (r: RunRecord, name?: string) => string;
+	sources: { name: string; state: string; tools: number }[];
+	hookEvents: string[];
+}
+
+/**
+ * The widget's lines, each with the tone the theme colours it in; none when there is nothing to
+ * show. A row carries a mark only where it differs (`[disabled]`, `[every time]`): the inbox count
+ * is the footer badge's, and the trace of a check is `/triggers audit`'s.
+ */
+export function panelLines(i: PanelInput): { text: string; tone: PanelTone }[] {
+	if (!i.rules.length && !i.jobs.length && !i.sources.length && !i.runs.length) return [];
+	const clip = (x: string, n: number) => previewRedacted(x, n);
+	const lines: { text: string; tone: PanelTone }[] = [];
+	const more = (n: number) => n > PANEL_ROW_LIMIT && lines.push({ text: `… ${n - PANEL_ROW_LIMIT} more`, tone: "dim" });
+	if (i.rules.length) {
+		lines.push({ text: "Rules", tone: "head" });
+		for (const r of i.rules.slice(0, PANEL_ROW_LIMIT)) {
+			const marks = [r.enabled ? "" : "[disabled]", r.fireOnce ? "" : "[every time]", r.failureMark ?? ""].filter(Boolean);
+			lines.push({ text: `${clip(r.condition, 40)} → ${clip(r.action, 40)}${marks.map((m) => `  ${m}`).join("")}`, tone: r.failureMark ? "warn" : r.enabled ? "ok" : "dim" });
+		}
+		more(i.rules.length);
+	}
+	if (i.poll && i.poll.outcome !== "no match" && !/^matched \d+$/.test(i.poll.outcome)) lines.push({ text: `Last check  ${formatLocal(Date.parse(i.poll.at)).slice(11)} · ${i.poll.outcome}`, tone: "warn" });
+	if (i.jobs.length) {
+		const disabled = i.jobs.filter((j) => !j.enabled).length;
+		lines.push({ text: `Loops  ${i.jobs.length}${disabled ? ` · ${disabled} disabled` : ""}`, tone: "head" });
+		for (const j of i.jobs.slice(0, PANEL_ROW_LIMIT))
+			lines.push({ text: `${loopLabel(j)}  ${formatSchedule(j.schedule)}  ${clip(j.prompt, 48)}${j.enabled ? "" : "  [disabled]"}${j.skippedOverlap ? `  skipped overlaps ${j.skippedOverlap}` : ""}`, tone: j.skippedOverlap ? "warn" : j.enabled ? "ok" : "dim" });
+		more(i.jobs.length);
+	}
+	if (i.runs.length) {
+		lines.push({ text: "Runs", tone: "head" });
+		const names = new Map(i.jobs.map((j) => [j.id, j.name]));
+		for (const r of i.runs.slice(-PANEL_RUN_LIMIT).reverse()) lines.push({ text: `${formatLocal(Date.parse(r.finishedAt)).slice(11)} ${i.runText(r, names.get(r.jobId))}`, tone: r.ok ? "ok" : r.aborted ? "dim" : "warn" });
+		if (i.runs.length > PANEL_RUN_LIMIT) lines.push({ text: "… /cron runs", tone: "dim" });
+	}
+	if (i.sources.length) {
+		lines.push({ text: `MCP  servers ${i.sources.length} · tools ${i.sources.reduce((n, s) => n + s.tools, 0)}`, tone: "head" });
+		const tone: PanelTone = i.sources.some((s) => s.state !== "connected" && s.state !== "disabled") ? "warn" : i.sources.some((s) => s.state === "connected") ? "ok" : "dim";
+		lines.push({ text: `  ${i.sources.map((s) => `${s.name} ${s.state}${s.tools ? ` · ${plural(s.tools, "tool")}` : ""}`).join("  ")}`, tone });
+	}
+	if (i.hookEvents.length) lines.push({ text: `Hooks  cli_hooks ${plural(i.hookEvents.length, "rule")} (${[...new Set(i.hookEvents)].join(", ")})`, tone: "head" });
+	return lines;
+}

package/src/job-owner.ts

@@ -1,29 +1,90 @@
 /**
  * Where a job runs, as one question the scheduler, the lists and `/cron run` all ask the same way.
  *
- * A stateful loop belongs to the machine: whichever process holds the clock runs it. A plain job
+ * A stateful loop belongs to the machine: the host runs it. A plain job
  * belongs to the session that created it — its result is a message in that conversation, so it
- * fires only in the process holding that session. Another session sees it, and sees that it is
- * asleep; it is not broken, and nothing here promises it a next run it will not get.
+ * fires in the instance holding that session's lease (src/lease.ts), and in the host while no window
+ * holds it. Another window on the same session is a viewer and fires nothing. A session the host
+ * cannot hold (a file pi-loops never saw) is asleep; it is not broken, and
+ * nothing here promises it a next run it will not get.
  */
+import { shortSessionId } from "./session-head.ts";
 import type { LoopJob } from "./store.ts";
 
-/** Would the process holding `sessionId` dispatch this job? (For a loop, only if it is also the leader.) */
-export function runsIn(job: Pick<LoopJob, "stateful" | "sessionId">, sessionId: string | undefined): boolean {
-	if (job.stateful) return true;
-	return !!sessionId && job.sessionId === sessionId;
+/** What the instance asking knows about sessions. */
+export interface OwnerView {
+	/** The session this instance has open. */
+	sessionId?: string;
+	/** Whether it holds that session's lease. A second window on the same conversation does not. */
+	holdsOwn: boolean;
+	/** The pid of the live holder of a session's lease, when there is one. */
+	holderOf?: (sessionId: string) => number | undefined;
+	/** It holds that session's lease but stands aside: its copy of the conversation is behind the file (src/lease.ts). */
+	standsAside?: boolean;
+	/**
+	 * Why no host will run anything right now, when that is so: stopped by hand, `[host] auto = false`,
+	 * `PI_LOOPS_HOST=off`, paused after crashes. Every loop, and every plain job only the host would
+	 * fire, is then paused: no next run is promised for a run that will not happen.
+	 */
+	hostPaused?: string;
+	/** The kind of that live holder: the host holding a conversation is running a turn in it; `page` is the page's pi. */
+	holderKind?: (sessionId: string) => "terminal" | "page" | "host" | undefined;
+	/** Whether the host fires a closed session's plain jobs: it is running and knows the session's file. */
+	hostRuns?: (sessionId: string) => boolean;
+}
+
+/** `terminal` is any window that holds the conversation; `page` says it is the page's pi. */
+export type Where = { kind: "machine" } | { kind: "here" } | { kind: "aside"; pid: number } | { kind: "terminal"; pid: number; page?: true } | { kind: "host" } | { kind: "paused"; reason: string } | { kind: "asleep" };
+
+type Owned = Pick<LoopJob, "stateful" | "sessionId">;
+
+export function whereRuns(job: Owned, view: OwnerView): Where {
+	if (job.stateful) return view.hostPaused ? { kind: "paused", reason: view.hostPaused } : { kind: "machine" };
+	if (!job.sessionId) return { kind: "asleep" };
+	if (job.sessionId === view.sessionId && view.holdsOwn) return { kind: "here" };
+	const pid = view.holderOf?.(job.sessionId);
+	const holder = pid === undefined ? undefined : view.holderKind?.(job.sessionId);
+	if (pid !== undefined && holder === "host") return { kind: "host" };
+	if (pid !== undefined && job.sessionId === view.sessionId && view.standsAside) return { kind: "aside", pid };
+	if (pid !== undefined) return holder === "page" ? { kind: "terminal", pid, page: true } : { kind: "terminal", pid };
+	if (!view.hostRuns?.(job.sessionId)) return { kind: "asleep" };
+	return view.hostPaused ? { kind: "paused", reason: view.hostPaused } : { kind: "host" };
+}
+
+/** Would this instance dispatch the job? (Only the host's scheduler is given loops.) */
+export function runsHere(job: Owned, view: OwnerView): boolean {
+	const where = whereRuns(job, view).kind;
+	return where === "machine" || where === "here";
+}
+
+/** Whether the job has a next run anywhere: a list shows it, wherever that is. */
+export function runsSomewhere(job: Owned, view: OwnerView): boolean {
+	const kind = whereRuns(job, view).kind;
+	return kind !== "asleep" && kind !== "paused";
 }
 
 /** The short form of the session a plain job belongs to. */
-export function ownerSession(job: Pick<LoopJob, "stateful" | "sessionId">): string | undefined {
-	return job.stateful ? undefined : (job.sessionId ?? "?").slice(0, 8);
+export function ownerSession(job: Owned): string | undefined {
+	return job.stateful ? undefined : shortSessionId(job.sessionId ?? "?");
+}
+
+/** Where a conversation is open, in the words every list and notice uses: never a pid. */
+export function openWhere(holder: "terminal" | "page" | "host" | undefined): string {
+	if (holder === "page") return "in the page";
+	if (holder === "host") return "in the background";
+	return "open in a terminal";
 }
 
 /**
- * The line a list shows for a plain job that will not run here — worded as what to do, because
+ * The mark a list shows for a plain job that will not run here — worded as what to do, because
  * "not open here" was read as an error. Undefined when the job runs here.
  */
-export function asleepNote(job: Pick<LoopJob, "stateful" | "sessionId">, sessionId: string | undefined): string | undefined {
-	if (runsIn(job, sessionId)) return undefined;
-	return `session ${ownerSession(job)} — resume it to run`;
+export function asleepNote(job: Owned, view: OwnerView): string | undefined {
+	const where = whereRuns(job, view);
+	if (where.kind === "terminal") return `session ${ownerSession(job)} — ${openWhere(where.page ? "page" : "terminal")}`;
+	if (where.kind === "aside") return `session ${ownerSession(job)} — this window shows an older copy; /resume it to run here`;
+	if (where.kind === "host") return `session ${ownerSession(job)} — ${openWhere("host")}`;
+	if (where.kind === "paused") return job.stateful ? `paused: ${where.reason}` : `session ${ownerSession(job)} — paused: ${where.reason}`;
+	if (where.kind === "asleep") return `session ${ownerSession(job)} — resume it to run`;
+	return undefined;
 }

package/src/job-tune.ts

@@ -0,0 +1,110 @@
+/**
+ * What the page suggests for a loop, as a function: at most one change, decided from the loop's
+ * signal (src/job-signal.ts), never applied by itself.
+ *
+ * Two kinds. A loop that has found nothing in its last `QUIET_SUGGEST_AFTER` runs and runs more
+ * often than hourly is offered "Run hourly instead"; one whose recent findings were all dismissed
+ * and none claimed is offered "Pause". A quiet hourly or daily loop gets nothing: quiet is not a
+ * fault (docs/loops.md, "Was it worth running").
+ *
+ * The key names the loop, the kind and the schedule it was computed under. The page posts only the
+ * key back; the server computes the suggestion again and refuses a key that no longer matches, so
+ * a page can never ask for a change the server would not suggest. Keep records the key on the job
+ * (`tuneKept`): the same suggestion is not offered again, and a schedule change makes a new key.
+ */
+import { applyJobEdit, type JobEditContext, type NextRun } from "./job-edit.ts";
+import type { LoopSignal } from "./job-signal.ts";
+import { computeNext, formatSchedule, type Schedule } from "./schedule.ts";
+import type { LoopJob } from "./store.ts";
+import type { AuditRecord } from "./triggers.ts";
+
+/** "Run hourly instead" from this many empty runs in a row. */
+export const QUIET_SUGGEST_AFTER = 12;
+/** "Pause" when the window has at least this many findings and this many dismissed, and none claimed. */
+export const PAUSE_FINDINGS = 5;
+export const PAUSE_DISMISSED = 5;
+const HOUR_MS = 3_600_000;
+
+export type TuneKind = "slower" | "pause";
+
+export interface Suggestion {
+	kind: TuneKind;
+	key: string;
+	label: "Run hourly instead" | "Pause";
+}
+
+/** The numbers a loop row shows: `30d: 6 findings · 0 claimed · 6 dismissed · quiet ×12`. */
+export interface RowSignal {
+	findings30d: number;
+	claimed30d: number;
+	dismissed30d: number;
+	quietStreak: number;
+}
+
+export function rowSignal(s: LoopSignal): RowSignal {
+	return { findings30d: s.findings, claimed30d: s.claimed, dismissed30d: s.dismissed, quietStreak: s.quiet };
+}
+
+/** How long the schedule waits between two runs from `now`; undefined when it has no two. */
+function periodMs(schedule: Schedule, createdAt: number, now: number): number | undefined {
+	if (schedule.kind === "every") return schedule.ms;
+	if (schedule.kind !== "cron") return undefined;
+	const first = computeNext({ schedule, createdAt }, now);
+	const second = first === undefined ? undefined : computeNext({ schedule, createdAt }, first);
+	return first === undefined || second === undefined ? undefined : second - first;
+}
+
+/** The hourly schedule of the same kind: `every 1h`, or the top of every hour. */
+function hourly(schedule: Schedule): Schedule {
+	return schedule.kind === "every" ? { kind: "every", ms: HOUR_MS } : { kind: "cron", expr: "0 * * * *" };
+}
+
+/** At most one suggestion for `job`, or none. */
+export function suggestTune(job: LoopJob, s: LoopSignal, now: number): Suggestion | undefined {
+	if (!job.enabled || !job.stateful || job.schedule.kind === "once" || job.running) return undefined;
+	const at = `${job.id}:${formatSchedule(job.schedule)}`;
+	let suggestion: Suggestion | undefined;
+	if (s.findings >= PAUSE_FINDINGS && s.claimed === 0 && s.dismissed >= PAUSE_DISMISSED) suggestion = { kind: "pause", key: `pause:${at}`, label: "Pause" };
+	else if (s.quiet >= QUIET_SUGGEST_AFTER) {
+		const period = periodMs(job.schedule, Date.parse(job.createdAt), now);
+		if (period !== undefined && period < HOUR_MS) suggestion = { kind: "slower", key: `slower:${at}`, label: "Run hourly instead" };
+	}
+	return suggestion && job.tuneKept === suggestion.key ? undefined : suggestion;
+}
+
+export interface AppliedTune {
+	/** Exactly the fields to write, under the store's lock. */
+	patch: Partial<LoopJob>;
+	/** The `cron_control_plane` state: a schedule change is `set`, a pause is `disable`. */
+	op: "set" | "disable";
+	changed: string[];
+	nextRun: NextRun;
+}
+
+/** Apply `suggestion` to `job`, through `applyJobEdit` for a schedule. */
+export function applyTune(job: LoopJob, suggestion: Suggestion, ctx: JobEditContext): AppliedTune {
+	if (suggestion.kind === "pause") return { patch: { enabled: false, tuneKept: undefined }, op: "disable", changed: ["paused from the page"], nextRun: { kind: "disabled" } };
+	const edit = applyJobEdit(job, { schedule: hourly(job.schedule) }, ctx);
+	return { patch: { ...edit.patch, tuneKept: undefined }, op: "set", changed: edit.changed, nextRun: edit.nextRun };
+}
+
+/**
+ * The `cron_control_plane` audit row for a loop changed in place, from the page's suggestion or the
+ * terminal's `/cron set`: `set` when its schedule changed, `disable` when it was turned off, and
+ * nothing for any other edit (a model, a name, a prompt), which the log already records.
+ */
+export function scheduleAudit(before: LoopJob, after: LoopJob, by: { sourceLabel: "page" | "slash"; suggestion?: string }): Omit<AuditRecord, "ts" | "traceId"> | undefined {
+	const was = formatSchedule(before.schedule);
+	const now = formatSchedule(after.schedule);
+	const state = was !== now ? "set" : before.enabled && !after.enabled ? "disable" : undefined;
+	if (!state) return undefined;
+	return {
+		cwd: before.cwd,
+		type: "cron_control_plane",
+		state,
+		sourceLabel: by.sourceLabel,
+		eventLabel: before.id,
+		summary: `${before.name ?? before.id}: ${state === "set" ? `${was} → ${now}` : "paused"}`,
+		details: { before_schedule: was, after_schedule: now, before_enabled: before.enabled, after_enabled: after.enabled, ...(by.suggestion ? { suggestion: by.suggestion } : {}) },
+	};
+}