@alphacoder-v0/pi-loops 0.20.0 → 0.22.0

package/src/pi-loops.ts

@@ -15,16 +15,17 @@ import * as path from "node:path";
 import { fileURLToPath } from "node:url";
 import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext, ToolDefinition } from "@earendil-works/pi-coding-agent";
 import { ProjectTrustStore, VERSION as PI_VERSION, getAgentDir, readStoredCredential } from "@earendil-works/pi-coding-agent";
-import { ARCHIVE_EXT, defaultExportPath, exportSession, importSession } from "./archive.ts";
+import { ARCHIVE_EXT, type ActivateMode, applyImport, automationOf, defaultExportPath, exportSession, importSession, offerToEnable, parseActivateMode } from "./archive.ts";
 import { Box, Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 import { parseAddArgs, parseSetArgs, splitCommand, tokenize } from "./args.ts";
 import { envFlag, loadConfig } from "./config.ts";
-import { GOAL_ENTRY, type GoalAction, type GoalState, MAX_CONTINUATIONS, applyDecision, branchMovedSince, continuationPrompt, evaluatorPrompt, latestGoal, newGoal, parseDecision, pauseFor, transcriptFromMessages } from "./goal.ts";
-import { withinProject } from "./presence.ts";
+import { GOAL_ENTRY, type GoalAction, type GoalState, MAX_CONTINUATIONS, abortedTurn, applyDecision, branchMovedSince, continuationPrompt, evaluatorPrompt, latestGoal, newGoal, parseDecision, pauseFor, transcriptFromMessages } from "./goal.ts";
+import { sameProject } from "./presence.ts";
 import { isExactlyTrusted, sessionTrustCovers } from "./trust.ts";
-import { HookRunner, type HookEventData, messageKind, messageSummary, resultSummary, truncateSummary } from "./hooks.ts";
+import { HookRunner, type HookEventData, messageKind, messageSummary, resultSummary, runEndEvent, runStartEvent, truncateSummary } from "./hooks.ts";
 import { failingSummary } from "./job-health.ts";
+import { QUIET_MARK_AFTER, SIGNAL_WINDOW_MS, loopSignal, signalSummary } from "./job-signal.ts";
 import { LoopsLog, pruneLogs } from "./log.ts";
 import { type InboxEntry, belongsToProject, inProject, resolveInboxRef } from "./inbox.ts";
 import { McpPool } from "./mcp-pool.ts";
@@ -38,7 +39,7 @@ import { createHash } from "node:crypto";
 import { computeDue, computeNext, formatLocal, formatSchedule, localOffset, parseSchedule, stamp } from "./schedule.ts";
 import { applyJobEdit } from "./job-edit.ts";
 import { asleepNote, runsIn } from "./job-owner.ts";
-import { AUTONOMY_LEVELS, type AutonomyLevel, INSTALL_ROOT, type Recipe, type UpdateResult, addLineFor, ensureExcluded, installDirFor, installFiles, installedRecipes, isRecipeName, listRecipes, MAX_SETUP_SHOWN, TRACKER_FILE, loadRecipe, packagedRecipesDir, parseAddWords, planInstall, playbookFiles, purgeInstall, readRecord, requireRecipeName, resolveRecipeRef, updateFiles } from "./recipe.ts";
+import { AUTONOMY_LEVELS, type AutonomyLevel, INSTALL_ROOT, RECIPE_TIERS, type Recipe, type UpdateResult, addLineFor, ensureExcluded, installDirFor, installFiles, installedRecipes, isRecipeName, listRecipes, MAX_SETUP_SHOWN, TRACKER_FILE, loadRecipe, neverSection, packagedRecipesDir, parseAddWords, planInstall, playbookFiles, preflightChecks, purgeInstall, readRecord, renderPreflight, requireRecipeName, resolveRecipeRef, runPreflight, updateFiles } from "./recipe.ts";
 import { LoopScheduler, type SessionSnapshot } from "./scheduler.ts";
 import { MAX_PROMPT_BYTES, type LoopJob, type RunRecord, defaultLoopsDir, newId, resolveJobRef, sessionExists } from "./store.ts";
 import { parentRuntimeFlags, type SubagentRequest } from "./runner.ts";
@@ -191,9 +192,7 @@ export default function piLoops(pi: ExtensionAPI) {
 			onRunStart: (job, runId) => {
 				auditCronStart(triggers.store, job, runId);
 				refreshBadge();
-				// The same two events the headless host fires. Whether a run happens here or there is
-				// an accident of who held the clock, and a hook rule should not be able to tell.
-				fireRunHook({ event: "run_start", run_job: job.name ?? job.id, run_id: runId, message_summary: truncateSummary(`${job.name ?? job.id}: ${job.prompt}`) });
+				fireRunHook(runStartEvent(job, runId));
 			},
 			onCatchUp: (job, dueAt) => {
 				if (lastCtx?.hasUI && sameProject(job.cwd, session.cwd)) lastCtx.ui.notify(`cron ${job.name ?? job.id}: catching up the run missed at ${formatLocal(dueAt)}`, "info");
@@ -201,16 +200,7 @@ export default function piLoops(pi: ExtensionAPI) {
 			onRunFinished: ({ job, record, findings, result }) => {
 				auditCronFinish(triggers.store, job, record, result.stopReason === "aborted");
 				refreshBadge();
-				fireRunHook({
-					event: "run_end",
-					run_job: job.name ?? job.id,
-					run_id: record.runId,
-					run_ok: record.ok,
-					run_findings: record.findings,
-					run_error: record.error ? redact(record.error) : null,
-					run_cost_usd: record.usage?.cost ?? null,
-					message_summary: truncateSummary(record.ok ? `${job.name ?? job.id}: ok · ${record.findings} finding(s)` : `${job.name ?? job.id}: failed: ${record.error ?? "unknown error"}`),
-				});
+				fireRunHook(runEndEvent(job, record));
 				if (!lastCtx?.hasUI) return;
 				// Another project's findings and prompt previews do not belong in this transcript; the
 				// audit sink below and the inbox already carry them to where they do.
@@ -255,7 +245,7 @@ export default function piLoops(pi: ExtensionAPI) {
 				// message into the parent session). Only into a chat that belongs to the rule's project;
 				// a different project's chat gets nothing — the finding goes to the inbox instead.
 				if (trigger.cwd && !sameProject(trigger.cwd, session.cwd)) {
-					await scheduler.inbox.append({ source: `trigger:${trigger.sourceLabel}`, text: content.replace(/^\[Trigger [^\]]+\]\s*/, ""), runId: trigger.traceId, jobId: trigger.sourceLabel, cwd: trigger.cwd });
+					await scheduler.inbox.append({ source: `trigger:${trigger.sourceLabel}`, text: content.replace(/^\[Trigger [^\]]+\]\s*/, ""), run_id: trigger.traceId, job_id: trigger.sourceLabel, cwd: trigger.cwd });
 					refreshBadge();
 					return "inbox";
 				}
@@ -267,7 +257,7 @@ export default function piLoops(pi: ExtensionAPI) {
 			},
 			onInjectAndRun: async (prompt, trigger) => {
 				if (trigger.cwd && !sameProject(trigger.cwd, session.cwd)) {
-					await scheduler.inbox.append({ source: `trigger:${trigger.sourceLabel}`, text: prompt.replace(/^\[Trigger [^\]]+\]\s*/, ""), runId: trigger.traceId, jobId: trigger.sourceLabel, cwd: trigger.cwd });
+					await scheduler.inbox.append({ source: `trigger:${trigger.sourceLabel}`, text: prompt.replace(/^\[Trigger [^\]]+\]\s*/, ""), run_id: trigger.traceId, job_id: trigger.sourceLabel, cwd: trigger.cwd });
 					refreshBadge();
 					return "inbox";
 				}
@@ -661,7 +651,8 @@ export default function piLoops(pi: ExtensionAPI) {
 		if (!lastCtx?.hasUI) return;
 		const parts: string[] = [];
 		const n = scheduler.inbox.newCount();
-		if (n > 0) parts.push(`Inbox: ${n} new`);
+		const decisions = scheduler.inbox.decisionCount();
+		if (n > 0) parts.push(`Inbox: ${n} new${decisions ? ` (${decisions} decision${decisions === 1 ? "" : "s"})` : ""}`);
 		// Machine-wide like the inbox count and the running list above it: the clock is one per host,
 		// and a loop failing in another checkout is still this machine's automation going quiet.
 		const failing = failingSummary(scheduler.store.load());
@@ -731,6 +722,10 @@ export default function piLoops(pi: ExtensionAPI) {
 
 	function jobLines(jobs: LoopJob[]): string[] {
 		const now = Date.now();
+		// Read once for the whole listing: the run log and the inbox are each one file, and a
+		// project with a dozen loops would otherwise parse them a dozen times per `/cron`.
+		const allRuns = jobs.some((j) => j.stateful) ? scheduler.store.allRuns() : [];
+		const allInbox = jobs.some((j) => j.stateful) ? scheduler.inbox.list() : [];
 		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.
 			const next = job.enabled && runsIn(job, session.sessionId)
@@ -746,12 +741,18 @@ export default function piLoops(pi: ExtensionAPI) {
 			const asleepMark = asleepNote(job, session.sessionId);
 			const dormant = asleepMark ? `[${asleepMark}]` : undefined;
 			const orphan = job.stateful && !fs.existsSync(job.cwd) ? "[orphan: cwd missing]" : undefined;
-			const marks = [job.stateful ? "[stateful]" : undefined, job.verify ? "[verify]" : undefined, dormant, orphan, job.running ? `running ${job.running.runId}` : undefined, job.catchUp ? undefined : "[no-catchup]"]
+			// What the loop's runs came to (src/job-signal.ts): `quiet ×N` in the marks once N empty
+			// runs are the newest, and the findings line — filed, claimed, dismissed — over 30 days.
+			// A loop was, until now, judged by whether it ran; this is whether it was worth running.
+			const signal = job.stateful ? loopSignal(job.id, allRuns, allInbox, 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]"]
 				.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 action = `    action: ${previewRedacted(job.prompt, 120)}`;
-			const meta = `    next ${next ? formatLocal(next) : "—"} · runs ${job.runCount}${job.skippedOverlap ? ` · overlap skips ${job.skippedOverlap}` : ""} · ${homeRel(job.cwd)}`;
+			const worth = signal ? signalSummary(signal) : undefined;
+			const meta = `    next ${next ? formatLocal(next) : "—"} · runs ${job.runCount}${job.skippedOverlap ? ` · overlap skips ${job.skippedOverlap}` : ""}${worth ? ` · 30d: ${worth}` : ""} · ${homeRel(job.cwd)}`;
 			const err = job.lastError ? `    last error: ${previewRedacted(job.lastError, 100)}` : job.lastFiredAt ? `    last fired: ${job.lastFiredAt}` : undefined;
 			return [head, action, meta, err].filter((l): l is string => !!l);
 		}).flat();
@@ -810,7 +811,7 @@ export default function piLoops(pi: ExtensionAPI) {
 		"/cron host [start|stop]        the headless host that keeps the clock after the last pi quits; start = hand off on quit even with [host] auto = false",
 		"/inbox                         triage findings from stateful jobs (/inbox help)",
 		`/session-export [path] [--exclude-triggers]      transcript + this project's cron jobs, trigger rules and loop state as one ${ARCHIVE_EXT} archive`,
-		"/session-import <path> [--activate-triggers=on|off] [--cwd <dir>] [--resume]   restore it here (automation stays off unless activated)",
+		"/session-import <path> [--activate-triggers=off|ask|on] [--cwd <dir>] [--resume]   restore it here (automation stays off unless activated)",
 	];
 
 	const cronCompletions = (prefix: string) => {
@@ -825,7 +826,7 @@ export default function piLoops(pi: ExtensionAPI) {
 			// Numbers refer to the project-scoped list (/loop); ids and names resolve machine-wide.
 			const pick = (ref: string): LoopJob | undefined => {
 				const all = jobs();
-				const job = /^\d+$/.test(ref.trim()) ? resolveJobRef(all.filter((j) => sameProject(j.cwd, session.cwd)), ref) : resolveJobRef(all, ref);
+				const job = /^\d+$/.test(ref.trim()) ? resolveJobRef(all.filter((j) => sameProject(j.cwd, session.cwd)), ref, { ordinals: true }) : resolveJobRef(all, ref);
 				if (!job) ctx.ui.notify(ref ? `no cron job with id '${ref}'` : `usage: /cron ${sub} <id>`, "warning");
 				return job;
 			};
@@ -1025,10 +1026,19 @@ export default function piLoops(pi: ExtensionAPI) {
 						const byJob = [...spend.byJob.entries()].sort((a, b) => b[1].cost - a[1].cost);
 						const budget = scheduler.budgetState();
 						const label = window === "all" ? "since the run log was last rotated" : window === "today" ? "today" : `the last ${window}`;
+						// The price beside what it bought: a loop's findings in the same window, and what a
+						// person did with them. `$0.410  28 run(s)  pr-watch  —  6 findings · 6 dismissed` is
+						// a line that answers itself.
+						const runsInLog = scheduler.store.allRuns();
+						const inboxAll = scheduler.inbox.list();
+						const worthOf = (id: string) => signalSummary(loopSignal(id, runsInLog, inboxAll, since));
 						show(ctx, `Automation cost ${label}: $${spend.total.toFixed(3)} over ${spend.runs} run(s)`, [
 							...(spend.rotated > 0 ? [`  including $${spend.rotated.toFixed(3)} from runs the log has already rotated away`] : []),
 							...(budget.cap > 0 ? [`  today's budget: $${budget.spent.toFixed(2)} of $${budget.cap.toFixed(2)}${budget.over ? " — dispatching is paused" : ""}`] : ["  no budget cap set ([limits] daily_budget_usd)"]),
-							...byJob.slice(0, 12).map(([id, e]) => `  $${e.cost.toFixed(3)}  ${e.runs} run(s)  ${e.name ?? id}`),
+							...byJob.slice(0, 12).map(([id, e]) => {
+								const worth = worthOf(id);
+								return `  $${e.cost.toFixed(3)}  ${e.runs} run(s)  ${e.name ?? id}${worth ? `  —  ${worth}` : ""}`;
+							}),
 							...(byJob.length > 12 ? [`  (+${byJob.length - 12} more)`] : []),
 							...(spend.runs ? [] : ["  nothing has run in this window"]),
 						]);
@@ -1196,13 +1206,14 @@ export default function piLoops(pi: ExtensionAPI) {
 	pi.registerCommand("crontab", { description: "Alias of /cron", getArgumentCompletions: cronCompletions, handler: cronHandler });
 	pi.registerCommand("loop", { description: "Alias of /cron", getArgumentCompletions: cronCompletions, handler: cronHandler });
 
-	const INBOX_USAGE = "[list|all|claim <n>|dismiss <n>|clear|help] [--all]";
+	const INBOX_USAGE = "[list|all|claim <n>|dismiss <n> [reason]|clear|help] [--all]";
 
 	const INBOX_HELP = [
 		"/inbox                list new findings of this project    /inbox --all   every project on this machine",
 		"/inbox all [--all]    include claimed/dismissed history",
 		"/inbox claim <n|id>   mark claimed and hand it to the agent as a real turn",
-		"/inbox dismiss <n|id> mark dismissed        /inbox clear [--all]   dismiss the ones listed",
+		"/inbox dismiss <n|id> [reason]   mark dismissed; a reason is shown to the loop's next run",
+		"/inbox clear [--all]  dismiss the ones listed",
 	];
 
 	/** The project a finding came from, as `/cron` shows a job's: the directory name is enough to tell them apart. */
@@ -1215,18 +1226,23 @@ export default function piLoops(pi: ExtensionAPI) {
 			// time pi-loops puts on a screen. It used to be the stored string with the `Z` sliced
 			// off — a UTC time wearing the shape of a local one, eight hours from the `next` on the
 			// `/cron` line above it, with nothing on either to say which was which.
-			const when = formatLocal(Date.parse(e.createdAt));
-			const mark = e.verified ? "✓ " : "";
+			const when = formatLocal(Date.parse(e.created_at));
+			// ⚑ is a checkpoint — a decision the finding asks of a person; ✓ is the checker's mark.
+			const mark = `${e.kind === "checkpoint" ? "⚑ " : ""}${e.verified ? "✓ " : ""}`;
 			// The project comes first of the three: with loops running in several checkouts it is what
 			// decides whether a finding is this morning's problem, and claiming runs it in that cwd.
-			if (!numbered) return `  [${e.status}] ${mark}${redact(e.text)}  (${projectOf(e.cwd)}, ${e.source})`;
+			const why = e.dismiss_reason ? ` — dismissed: ${redact(e.dismiss_reason)}` : "";
+			if (!numbered) return `  [${e.status}] ${mark}${redact(e.text)}${why}  (${projectOf(e.cwd)}, ${e.source})`;
 			return `  ${i + 1}. [${e.id.slice(0, 12)}] ${mark}${redact(e.text)}  (${projectOf(e.cwd)}, ${e.source}, ${when})`;
 		});
 	}
 
 	function claimPrompt(e: InboxEntry): string {
-		const verified = e.verified ? `\n(An independent checker reviewed and kept this finding${e.verifiedReason ? `: ${e.verifiedReason}` : ""}.)` : "";
-		return `A recurring loop (${e.source}, running in ${e.cwd}) reported this finding — investigate and address it:\n${e.text}${verified}`;
+		const verified = e.verified ? `\n(An independent checker reviewed and kept this finding${e.verified_reason ? `: ${e.verified_reason}` : ""}.)` : "";
+		// A checkpoint is a decision the loop prepared and left to a person; the claim is that
+		// person's yes, so the turn carries the decision out rather than re-investigating it.
+		const checkpoint = e.kind === "checkpoint" ? "\nThis finding is a checkpoint: claiming it is the person's approval of the decision it recommends — carry that decision out, and stop where the finding says a person acts." : "";
+		return `A recurring loop (${e.source}, running in ${e.cwd}) reported this finding — investigate and address it:\n${e.text}${verified}${checkpoint}`;
 	}
 
 	/* ------------------------------------------------------------------ /goal */
@@ -1457,7 +1473,8 @@ export default function piLoops(pi: ExtensionAPI) {
 						const elsewhere = all.length - entries.length;
 						if (elsewhere) lines.push(`+ ${elsewhere} finding${elsewhere === 1 ? "" : "s"} in other projects — /inbox --all`);
 						lines.push("claim with /inbox claim <n>, dismiss with /inbox dismiss <n>");
-						show(ctx, `Inbox (${where}, ${entries.length} new, times ${localOffset(Date.now())}):`, lines);
+						const decisions = entries.filter((e) => e.kind === "checkpoint").length;
+						show(ctx, `Inbox (${where}, ${entries.length} new${decisions ? `, ${decisions} need${decisions === 1 ? "s" : ""} a decision` : ""}, times ${localOffset(Date.now())}):`, lines);
 						return;
 					}
 					case "all": {
@@ -1470,19 +1487,45 @@ export default function piLoops(pi: ExtensionAPI) {
 						return;
 					case "claim":
 					case "dismiss": {
+						// `/inbox dismiss 3 that file is generated`: the first word names the finding, the rest is
+						// why, and the reason goes to the loop that reported it, in its next run's prompt. A
+						// claim takes the whole argument as the ref, as it always has. For a dismiss, `--all`
+						// only counts before the reason starts (`dismiss --all 3 …`, `dismiss 3 --all …`): a
+						// reason that mentions `--all` in passing must not re-number the list the person is
+						// looking at and dismiss another project's finding.
+						let target = ref;
+						let reason = "";
+						let machineWide = everywhere;
+						if (sub === "dismiss") {
+							const words = rest.split(/\s+/).filter(Boolean);
+							machineWide = words[0] === "--all";
+							if (machineWide) words.shift();
+							target = words.shift() ?? "";
+							if (words[0] === "--all") {
+								machineWide = true;
+								words.shift();
+							}
+							reason = words.join(" ");
+						}
 						// Numbers are the numbers on screen — this project's list, as `/cron` does it; an id
 						// or a prefix still resolves machine-wide, so a finding can be claimed from anywhere.
-						const entries = /^\d+$/.test(ref) ? scoped(scheduler.inbox.listNew()) : scheduler.inbox.listNew();
-						const entry = resolveInboxRef(entries, ref);
+						const all = scheduler.inbox.listNew();
+						const entries = /^\d+$/.test(target) && !machineWide ? inProject(all, session.cwd, sameProject) : all;
+						const entry = resolveInboxRef(entries, target, { ordinals: true });
 						if (!entry) {
-							const n = Number(ref);
-							ctx.ui.notify(!ref ? "usage: /inbox claim|dismiss <n or inb-id>" : Number.isInteger(n) ? `no inbox entry #${n} in ${where} (have ${entries.length}; /inbox --all lists every project)` : `no new inbox entry matching '${ref}'`, "warning");
+							const n = Number(target);
+							ctx.ui.notify(!target ? "usage: /inbox claim <n or inb-id> | /inbox dismiss <n or inb-id> [reason]" : Number.isInteger(n) ? `no inbox entry #${n} in ${where} (have ${entries.length}; /inbox --all lists every project)` : `no new inbox entry matching '${target}'`, "warning");
 							return;
 						}
-						await scheduler.inbox.setStatus(entry.id, sub === "claim" ? "claimed" : "dismissed", sub === "claim" ? session.sessionId : undefined);
+						await scheduler.inbox.setStatus(entry.id, sub === "claim" ? "claimed" : "dismissed", sub === "claim" ? session.sessionId : undefined, reason || undefined);
 						refreshBadge();
 						if (sub === "dismiss") {
-							ctx.ui.notify(`dismissed: ${previewRedacted(entry.text, 80)}`, "info");
+							const loop = scheduler.store.load().find((j) => j.id === entry.job_id);
+							// A trigger's finding carries its source label where a loop's carries a job id; a
+							// trigger has no notes and no next run to tell.
+							const gone = entry.job_id?.startsWith("cron-") ? "the loop that reported it is gone, so nobody is told" : "a trigger reported it, and a trigger keeps no notes, so nobody is told";
+							const told = reason ? ` — ${loop ? `${loop.name ?? loop.id} is told why on its next run` : gone}` : "";
+							ctx.ui.notify(`dismissed: ${previewRedacted(entry.text, 80)}${told}`, "info");
 							return;
 						}
 						pi.sendUserMessage(claimPrompt(entry), ctx.isIdle() ? undefined : { deliverAs: "followUp" });
@@ -1553,7 +1596,7 @@ export default function piLoops(pi: ExtensionAPI) {
 			const store = triggers.store;
 			const pickRule = (ref: string) => {
 				const all = store.load();
-				const rule = /^\d+$/.test(ref.trim()) ? resolveRuleRef(all.filter((r) => sameProject(r.cwd, session.cwd)), ref) : resolveRuleRef(all, ref);
+				const rule = /^\d+$/.test(ref.trim()) ? resolveRuleRef(all.filter((r) => sameProject(r.cwd, session.cwd)), ref, { ordinals: true }) : resolveRuleRef(all, ref);
 				if (!rule) ctx.ui.notify(ref ? `no dynamic trigger rule with id '${ref}'` : `usage: /triggers ${sub} <id>${sub === "remove" || sub === "rm" || sub === "delete" ? "|--all" : ""}`, "warning");
 				return rule;
 			};
@@ -1841,7 +1884,7 @@ export default function piLoops(pi: ExtensionAPI) {
 
 	const RECIPE_HELP = [
 		"/recipe                    the packaged recipes, and which of them are installed here",
-		"/recipe show <name|path>   what one would install: playbooks, jobs, levels, setup script",
+		"/recipe show <name|path>   what one would install: playbooks, jobs, levels, what the runs may never do, setup script",
 		"/recipe add <name|path>    install it in this project: copies the playbooks to .agents/skills/<name>/,",
 		"                           runs the setup script after showing it, creates the jobs. --level report|propose|act skips the question",
 		"/recipe update <name>      merge the packaged playbooks into the installed copies; your edits are kept",
@@ -1858,6 +1901,44 @@ export default function piLoops(pi: ExtensionAPI) {
 		act: "also promote, close and merge — the terminal states",
 	};
 
+	/**
+	 * What the playbooks forbid, as `/recipe show` and the install confirmation print it: one
+	 * block per playbook that has a `## Never` section. It is the safety envelope of an unattended
+	 * run, and the one part of a playbook worth reading before saying yes to the install.
+	 */
+	/**
+	 * What the project has and lacks for this recipe's runs, checked now rather than found out by
+	 * the first run at three in the morning. Reported, never enforced: the install goes through
+	 * whatever the lines say, because a missing `gh` login is fixed in a minute and a job that is
+	 * not there is not.
+	 */
+	async function preflightLines(recipe: Recipe, project: string, level: AutonomyLevel): Promise<string[]> {
+		let tracker: string | undefined;
+		try {
+			tracker = fs.readFileSync(path.join(project, TRACKER_FILE), "utf8");
+		} catch {
+			tracker = undefined;
+		}
+		return renderPreflight(await runPreflight(preflightChecks(recipe.manifest, level, tracker), project));
+	}
+
+	function neverLines(recipe: Recipe): string[] {
+		const out: string[] = [];
+		for (const file of playbookFiles(recipe.manifest)) {
+			if (!file.endsWith(".md")) continue;
+			let text: string;
+			try {
+				text = fs.readFileSync(path.join(recipe.dir, file), "utf8");
+			} catch {
+				continue;
+			}
+			const never = neverSection(text);
+			if (!never.length) continue;
+			out.push(`  never (${file}):`, ...never.map((l) => `    ${l}`));
+		}
+		return out;
+	}
+
 
 	/** The prompt that hands the tracker description to the session; the text lives beside the recipes. */
 	function trackerSetupPrompt(recipe: Recipe, project: string): string {
@@ -1939,6 +2020,7 @@ export default function piLoops(pi: ExtensionAPI) {
 			return;
 		}
 		const plan = planInstall(recipe, project, level);
+		const preflight = await preflightLines(recipe, project, level);
 		let overwrite = false;
 		if (plan.changed.length) {
 			overwrite = await ctx.ui.confirm(`Overwrite ${plan.changed.length} edited file(s)?`, [...plan.changed.map((f) => `  ${f}`), "", "These differ from what would be written. Yes replaces them with the packaged version; No keeps your copies (the record is still written, and /recipe update merges later)."].join("\n"));
@@ -1960,10 +2042,12 @@ export default function piLoops(pi: ExtensionAPI) {
 			`Files → ${homeRel(plan.targetDir)}/ (listed in .git/info/exclude, so nothing enters the repository):`,
 			...plan.files.map((f) => `  ${f}${plan.changed.includes(f) ? (overwrite ? "  (overwritten)" : "  (kept as edited)") : ""}`),
 			...(setupText !== undefined ? ["", `Setup script ${m.setup} (${setupText.split("\n").length} lines, printed above and at ${path.join(recipe.dir, m.setup ?? "")}) runs once with this session's environment.`] : []),
+			...(neverLines(recipe).length ? ["", "What the playbooks forbid a run to do, at every level:", ...neverLines(recipe)] : []),
 			"",
 			"Jobs:",
 			...plan.addLines.map((l) => `  /cron add ${l}`),
 			...(m.budgetHintUsd ? ["", `Budget hint: about $${m.budgetHintUsd}/day — cap it with [limits] daily_budget_usd in config.toml`] : []),
+			...(preflight.length ? ["", "Before the first run (checked now; nothing here blocks the install):", ...preflight] : []),
 		];
 		const ok = await ctx.ui.confirm(`Install recipe ${m.name} at level "${level}"?`, body.join("\n"));
 		if (!ok) {
@@ -2021,11 +2105,20 @@ export default function piLoops(pi: ExtensionAPI) {
 						const packaged = listRecipes();
 						const installed = new Map(installedRecipes(project).map((r) => [r.recipe, r]));
 						const jobs = scheduler.store.load().filter((j) => j.recipe && sameProject(j.cwd, project));
-						const lines = packaged.map((r) => {
+						const line = (r: Recipe) => {
 							const rec = installed.get(r.manifest.name);
 							const n = jobs.filter((j) => j.recipe === r.manifest.name).length;
 							return `  ${r.manifest.name.padEnd(17)} ${(rec ? `installed: ${rec.level}, ${n} job(s)` : "—").padEnd(28)} ${r.manifest.summary}`;
-						});
+						};
+						// Starters first: they read and file findings, and are the ones to install before
+						// anything that writes to a tracker or opens a pull request.
+						const lines: string[] = [];
+						for (const tier of RECIPE_TIERS) {
+							const group = packaged.filter((r) => r.manifest.tier === tier);
+							if (!group.length) continue;
+							lines.push(tier === "starter" ? "  starter — reads, and files findings; install one of these first:" : "  advanced — writes to a worktree, a tracker or a pull request; read the playbooks first:");
+							lines.push(...group.map(line));
+						}
 						for (const rec of installed.values()) {
 							if (packaged.some((r) => r.manifest.name === rec.recipe)) continue;
 							lines.push(`  ${rec.recipe.padEnd(17)} installed from ${homeRel(rec.source)} (${rec.level})`);
@@ -2043,8 +2136,12 @@ export default function piLoops(pi: ExtensionAPI) {
 						const m = recipe.manifest;
 						const rel = path.join(INSTALL_ROOT, m.name);
 						const record = readRecord(installDirFor(project, m.name));
+						const topLevel = m.levels[m.levels.length - 1];
+						const showPreflight = await preflightLines(recipe, project, topLevel);
 						const lines = [
 							`  ${m.summary}`,
+							`  tier: ${m.tier}${m.tier === "starter" ? " (reads, and files findings)" : " (writes to a worktree, a tracker or a pull request)"}`,
+							...(m.usefulWhen.length ? ["  useful when:", ...m.usefulWhen.map((u) => `    ${u}`)] : []),
 							`  levels: ${m.levels.map((l) => `${l} (${LEVEL_TEXT[l]})`).join("; ")}`,
 							`  tracker: ${m.needsTracker ? `needs ${TRACKER_FILE} — ${fs.existsSync(path.join(project, TRACKER_FILE)) ? "present" : "missing here; /recipe add writes it with you"}` : "not needed"}`,
 							`  files → ${rel}/: ${playbookFiles(m).join(", ")}`,
@@ -2052,6 +2149,8 @@ export default function piLoops(pi: ExtensionAPI) {
 							...(m.budgetHintUsd ? [`  budget hint: about $${m.budgetHintUsd}/day at the default schedules — [limits] daily_budget_usd in config.toml`] : []),
 							"  jobs:",
 							...m.jobs.map((j) => `    /cron add ${addLineFor(j, rel)}`),
+							...neverLines(recipe),
+							...(showPreflight.length ? [`  before the first run (at ${topLevel}, checked now):`, ...showPreflight] : []),
 							...(record ? [`  installed here: ${record.level}, ${record.installedAt}, pi-loops ${record.version}`] : []),
 						];
 						show(ctx, `recipe ${m.name} (${homeRel(recipe.dir)})`, lines);
@@ -2233,12 +2332,7 @@ export default function piLoops(pi: ExtensionAPI) {
 			const outputPath = path.resolve(session.cwd, pathArgs[0] ?? defaultExportPath(session.cwd, sessionId));
 			ctx.ui.notify(ARCHIVE_WARNING, "warning"); // Printed before the attempt, success or not
 			try {
-				// The store is machine-global, so the session that
-				// created a job or rule is what scopes the archive; jobs from before `createdBy`
-				// existed fall back to the project.
-				const mine = (owner: { sessionId?: string } | undefined, cwd: string) => (owner?.sessionId ? owner.sessionId === sessionId : sameProject(cwd, session.cwd));
-				const jobs = scheduler.store.load().filter((j) => sameProject(j.cwd, session.cwd) && mine(j.createdBy, j.cwd));
-				const rules = triggers.store.load().filter((r) => sameProject(r.cwd, session.cwd) && mine(r.createdBy, r.cwd));
+				const { jobs, rules } = automationOf(scheduler.store.load(), triggers.store.load(), session.cwd, sessionId);
 				const states: Record<string, string> = {};
 				for (const job of jobs) {
 					const loopState = job.stateful ? scheduler.store.readState(job.id) : undefined;
@@ -2259,26 +2353,26 @@ export default function piLoops(pi: ExtensionAPI) {
 		handler: async (args, ctx) => {
 			lastCtx = ctx;
 			const parts = args.split(/\s+/).filter(Boolean);
-			let activate = false;
+			let mode: ActivateMode = "ask";
 			let resume = false;
 			let targetCwd = session.cwd;
 			const positional: string[] = [];
-			for (let i = 0; i < parts.length; i++) {
-				const arg = parts[i];
-				if (arg === "--resume") resume = true;
-				else if (arg.startsWith("--activate-triggers=")) {
-					const value = arg.slice("--activate-triggers=".length);
-					if (value === "on") activate = true;
-					else if (value === "off") activate = false;
-					else {
-						ctx.ui.notify(`--activate-triggers=${value} is not supported (use on|off)`, "warning");
-						return;
-					}
-				} else if (arg === "--cwd") targetCwd = path.resolve(session.cwd, parts[++i] ?? ".");
-				else positional.push(arg);
+			try {
+				for (let i = 0; i < parts.length; i++) {
+					const arg = parts[i];
+					if (arg === "--resume") resume = true;
+					// Both forms, as the command line takes them.
+					else if (arg.startsWith("--activate-triggers=")) mode = parseActivateMode(arg.slice("--activate-triggers=".length));
+					else if (arg === "--activate-triggers") mode = parseActivateMode(parts[++i]);
+					else if (arg === "--cwd") targetCwd = path.resolve(session.cwd, parts[++i] ?? ".");
+					else positional.push(arg);
+				}
+			} catch (err: any) {
+				ctx.ui.notify(err?.message ?? String(err), "warning");
+				return;
 			}
 			if (positional.length !== 1) {
-				ctx.ui.notify("usage: /session-import <path> [--activate-triggers=on|off] [--cwd <dir>] [--resume]", "warning");
+				ctx.ui.notify("usage: /session-import <path> [--activate-triggers=off|ask|on] [--cwd <dir>] [--resume]", "warning");
 				return;
 			}
 			const archivePath = path.resolve(session.cwd, positional[0]);
@@ -2289,32 +2383,13 @@ export default function piLoops(pi: ExtensionAPI) {
 					archivePath,
 					sessionDir: ctx.sessionManager.getSessionDir(),
 					targetCwd,
-					activate,
+					activate: mode === "on",
 					existingJobs: store.load(),
 					existingRules: triggers.store.load(),
 					existingJobIds: new Set(store.load().map((j) => j.id)),
 					existingRuleIds: new Set(triggers.store.load().map((r) => r.id)),
 				});
-				try {
-					if (imp.jobs.length) await store.mutate((jobs) => ({ jobs: [...jobs, ...imp.jobs], result: undefined }));
-					for (const [id, text] of Object.entries(imp.states)) store.writeState(id, text);
-					if (imp.rules.length) await triggers.store.mutate((rules) => rules.push(...imp.rules));
-				} catch (err) {
-					// Roll back, best effort and in this order: a half-imported archive must leave neither
-					// an orphan session nor a partial store, and the original error is what gets reported.
-					const ids = new Set(imp.jobs.map((j) => j.id));
-					const attempt = (fn: () => void) => {
-						try {
-							fn();
-						} catch {
-							/* best effort */
-						}
-					};
-					attempt(() => fs.rmSync(imp.sessionPath, { force: true }));
-					await store.mutate((jobs) => ({ jobs: jobs.filter((j) => !ids.has(j.id)), result: undefined })).catch(() => {});
-					for (const id of ids) attempt(() => fs.rmSync(store.statePath(id), { force: true }));
-					throw err;
-				}
+				await applyImport(imp, store, triggers.store);
 				for (const job of imp.jobs) cronControlAudit("add", "slash", undefined, job);
 				refreshBadge();
 				const skipped = (imp.skippedJobs ?? 0) + (imp.skippedRules ?? 0);
@@ -2324,22 +2399,12 @@ export default function piLoops(pi: ExtensionAPI) {
 					...(imp.notes ?? []).map((n: string) => `note: ${n}`),
 					`resume with: pi --session ${imp.sessionPath}`,
 				]);
-				// Offer to switch originally-enabled automation back on.
-				const pending = imp.originallyEnabledJobs.length + imp.originallyEnabledRules.length;
-				if (!activate && pending && ctx.hasUI) {
-					const ok = await ctx.ui.confirm("Enable imported automation?", `${imp.originallyEnabledJobs.length} cron job(s) and ${imp.originallyEnabledRules.length} trigger rule(s) were enabled in the source session. Enable them here now?`);
-					if (ok) {
-						for (const id of imp.originallyEnabledJobs) {
-							const before = store.load().find((j) => j.id === id);
-							const after = await store.update(id, (j) => {
-								j.enabled = true;
-							});
-							if (before && after) cronControlAudit("enable", "slash", before, after);
-						}
-						for (const id of imp.originallyEnabledRules) await triggers.store.setEnabled(id, true);
-						refreshBadge();
-						ctx.ui.notify(`enabled ${imp.originallyEnabledJobs.length} cron job(s) and ${imp.originallyEnabledRules.length} trigger rule(s)`, "info");
-					}
+				// Offer to switch originally-enabled automation back on. Nothing is asked with no UI to
+				// ask in, and `off` means nothing is asked at all.
+				const enabled = await offerToEnable(imp, store, triggers.store, mode === "ask" && ctx.hasUI ? (question, detail) => ctx.ui.confirm(question, detail) : undefined, (before, after) => cronControlAudit("enable", "slash", before, after));
+				if (enabled.jobs || enabled.rules) {
+					refreshBadge();
+					ctx.ui.notify(`enabled ${enabled.jobs} cron job(s) and ${enabled.rules} trigger rule(s)`, "info");
 				}
 				if (resume) await ctx.switchSession(imp.sessionPath);
 			} catch (err: any) {
@@ -2365,12 +2430,6 @@ export default function piLoops(pi: ExtensionAPI) {
 
 	/* ------------------------------------------------------------ tools */
 
-	/**
-	 * The same project, whichever path this pi was opened through: a worktree, a symlink or a
-	 * subdirectory of the project root all belong to the rule or job that names the root.
-	 */
-	const sameProject = (a: string, b: string): boolean => withinProject(b, a) || withinProject(a, b);
-
 	/**
 	 * Where a diagnostic goes: the log file always, and the chat as a warning — pi's `showStatus`
 	 * replaces the previous status line in place, so several info-level notices in one tick collapse
@@ -2506,7 +2565,16 @@ export default function piLoops(pi: ExtensionAPI) {
 		goalMessages = event.messages ?? [];
 		const last: any = (event.messages ?? []).at(-1);
 		lastTurnStopReason = typeof last?.stopReason === "string" ? last.stopReason : undefined;
-		if (lastTurnStopReason === "aborted") goalAbort?.abort();
+		if (lastTurnStopReason === "aborted") {
+			goalAbort?.abort();
+			// Esc pauses the goal, not only this turn's judgement: the person said stop, and a goal
+			// that went on pursuing would send them back to work on their next message.
+			const stopped = goal && abortedTurn(goal);
+			if (stopped) {
+				persistGoal(ctx, stopped.state);
+				notifyOrLog(ctx, `[goal] paused: ${stopped.action.kind === "pause" ? stopped.action.reason : ""}`, "warning");
+			}
+		}
 		await fireHook({ event: "agent_end" }, ctx);
 		refreshBadge();
 	});

package/src/presence.ts

@@ -107,6 +107,11 @@ export function withinProject(root: string, p: string): boolean {
 	return !!rel && !rel.startsWith("..") && !path.isAbsolute(rel);
 }
 
+/** A worktree, a symlinked path or a subdirectory is the same project, as the runtime treats it. */
+export function sameProject(a: string, b: string): boolean {
+	return withinProject(b, a) || withinProject(a, b);
+}
+
 /**
  * The process that should act for the project rooted at `cwd` on `host`: a live pi opened in it —
  * or in a subdirectory of it, or through a symlink to it — lowest pid as the tie-break so every

package/src/protocol.ts

@@ -21,6 +21,30 @@ export const FIRST_RUN_MARKER = "(first run)";
  */
 export const LOOP_STATE_CLOSE = "[/loop-state]";
 export const OUTPUT_PROTOCOL_HEADING = "Output protocol (mandatory):";
+/** The block between the notes and the job text that carries what a person said when dismissing (`/inbox dismiss <n> <reason>`). */
+export const DISMISSED_OPEN = "[dismissed]";
+export const DISMISSED_CLOSE = "[/dismissed]";
+/** How many dismissed-with-reason findings one run is shown; the newest survive. */
+export const DISMISSED_PER_RUN = 8;
+
+/** One finding a person dismissed with a reason, as the loop that reported it is told. */
+export interface DismissedFeedback {
+	text: string;
+	reason: string;
+}
+
+/**
+ * A checkpoint is a finding that asks a person to decide, and docs/recipes.md fixes its shape:
+ * `<the decision> · waits: <what waits on it> · if not: <what happens if nobody acts>`. The
+ * middle dot before `waits:` is the mark — the word alone is prose ("the deploy waits: on DNS"),
+ * and a loop that wants its finding read as a decision writes the shape the playbooks write.
+ * Everything else is news: a merged pull request, a red check, a digest line. Every finding is one
+ * of the two, so the answer is always a kind.
+ */
+export type FindingKind = "checkpoint" | "news";
+export function findingKind(text: string): FindingKind {
+	return /(^|\s)·\s*waits:/i.test(text) ? "checkpoint" : "news";
+}
 
 export function capChars(text: string, max: number): string {
 	const chars = Array.from(text.trim());
@@ -28,8 +52,23 @@ export function capChars(text: string, max: number): string {
 	return `${chars.slice(0, max).join("")}…`;
 }
 
-export function composeLoopPrompt(action: string, previousState: string | undefined, meta?: { name?: string; runAt?: string }): string {
+export function composeLoopPrompt(action: string, previousState: string | undefined, meta?: { name?: string; runAt?: string; dismissed?: DismissedFeedback[] }): string {
 	const state = previousState && previousState.trim() ? capChars(previousState, LOOP_STATE_MAX_CHARS) : FIRST_RUN_MARKER;
+	/**
+	 * Feedback, not permission. A reason is shown to the one run after it was given and then only
+	 * lives on in that run's notes: the person spoke once, and the notes are the only thing a loop
+	 * carries between runs — a second channel that the notes cap does not bound would be a memory the
+	 * loop could not edit or forget. Newest last, so the most recent word is nearest the task.
+	 */
+	const dismissed = (meta?.dismissed ?? []).slice(-DISMISSED_PER_RUN);
+	const feedback = dismissed.length
+		? [
+				`${DISMISSED_OPEN} (findings of yours a person dismissed since your previous run, and why — do not report these again unless what they describe has changed; put what you need to remember that in your notes)`,
+				...dismissed.map((d) => `- "${capChars(d.text.replace(/\s+/g, " "), INBOX_TEXT_MAX_CHARS)}" — ${capChars(d.reason.replace(/\s+/g, " "), INBOX_TEXT_MAX_CHARS)}`),
+				DISMISSED_CLOSE,
+				"",
+			]
+		: [];
 	const header = meta?.name ? `You are running the recurring loop "${meta.name}"` : "You are running a recurring loop";
 	/**
 	 * The run time, and how to write one.
@@ -50,6 +89,7 @@ export function composeLoopPrompt(action: string, previousState: string | undefi
 		state,
 		LOOP_STATE_CLOSE,
 		"",
+		...feedback,
 		action.trim(),
 		"",
 		OUTPUT_PROTOCOL_HEADING,
@@ -111,7 +151,10 @@ export function stripProtocolTags(text: string): string {
  * what a display wants — a prompt from somewhere else is still the best thing to show.
  */
 export function jobTextOf(prompt: string): string {
-	return prompt.split(LOOP_STATE_CLOSE).pop()?.split(OUTPUT_PROTOCOL_HEADING)[0] ?? prompt;
+	const afterState = prompt.split(LOOP_STATE_CLOSE).pop()?.split(OUTPUT_PROTOCOL_HEADING)[0] ?? prompt;
+	// The dismissed block sits between the notes and the job text; it is the person's words, not the job's.
+	const afterFeedback = afterState.trimStart().startsWith(DISMISSED_OPEN) ? afterState.split(DISMISSED_CLOSE).slice(1).join(DISMISSED_CLOSE) : afterState;
+	return afterFeedback;
 }
 
 /* ---------------------------------------------------------- maker/checker */