@alphacoder-v0/pi-loops 0.20.0 → 0.22.0

package/recipes/issue-loop/implement.md

@@ -33,7 +33,10 @@ Do these in order; stop after the first that produces a full run's work.
    review state is `CHANGES_REQUESTED`, or that has a comment by a person newer than the
    timestamp in your notes: check out its worktree, address every point (reply to each comment
    saying what you did, or why not), run the project's checks, push, and re-request review.
-   Report: `#<n> review feedback addressed — PR <url>`.
+   Report: `#<n> review feedback addressed — PR <url>`. With a local Markdown tracker there is no
+   pull request: the feedback is a comment under the item's `## Comments` newer than your notes'
+   timestamp, and the person has set the item back to `agent-working`; address it on the branch
+   and set `in-review` again.
 3. **One new issue.** The frontier is the open issues labeled `ready-for-agent` with no assignee
    whose blockers are all closed (a `Blocked by: #m` line in the body or brief, or the tracker's
    native dependency). Take the **oldest one**. One per run — a second one waits for the next run.
@@ -95,8 +98,9 @@ branch and worktree path to your notes **now**, before any implementation, so a
   gh issue edit <n> --add-label in-review --remove-label agent-working
   ```
 
-  Report: `#<n> PR opened — <url> (<k> commits, checks green)`. The maintainer merges; the
-  `Closes` line closes the issue.
+  Report: `#<n> PR opened — <url> (<k> commits, checks green) · waits: your review · if not:
+  stays in-review; I address review comments and re-request, and do not nudge`. The maintainer
+  merges; the `Closes` line closes the issue.
 
 ## Blocked
 
@@ -108,7 +112,8 @@ gh issue edit <n> --add-label agent-blocked --remove-label agent-working
 ```
 
 Comment with the specific question or the specific failure (command and output), the branch, and
-what you would do next given an answer. Report: `#<n> blocked — <one-line reason>`. The
+what you would do next given an answer. Report: `#<n> blocked — <one-line reason> · waits: your
+answer on the issue · if not: untouched; other ready-for-agent issues still get built`. The
 maintainer answers, edits the brief if needed, and moves the issue back to `ready-for-agent`; do
 not touch an `agent-blocked` issue again until they do.
 
@@ -133,3 +138,11 @@ tracker has the rest.
 
 One line per state change you made, in the shapes above. Housekeeping produces no inbox lines. A
 run that only resumed and is still working produces none either.
+
+## Never
+
+Never push to the default branch, never force-push, never rebase a branch someone has reviewed.
+Never merge: the pull request — or, with a local tracker, the branch — waits for a person at
+every level. Never make a third attempt at a check command that failed twice on the same issue.
+Never touch an `agent-blocked` issue until a person has moved it back to `ready-for-agent`.
+Never post a comment without the line saying it was generated by AI.

package/recipes/issue-loop/labels.sh

@@ -2,8 +2,26 @@
 # The labels the issue loop moves issues through. Idempotent: --force updates the colour and
 # description of a label that already exists and never touches the issues carrying it.
 # Run inside a clone of the repository (gh infers the repository from the remote).
+#
+# Labels are GitHub's: a local Markdown tracker (docs/agents/issue-tracker.md naming
+# .scratch/issues/) has none to create, and a GitHub tracker without a working `gh` gets its
+# labels later — the first run reports the missing CLI as a finding. Neither stops the install.
 set -e
 
+tracker="docs/agents/issue-tracker.md"
+if [ -f "$tracker" ] && grep -q '\.scratch/issues' "$tracker"; then
+  echo "local Markdown tracker ($tracker): no labels to create"
+  exit 0
+fi
+if ! command -v gh >/dev/null 2>&1; then
+  echo "gh is not on the PATH: no labels created; install the GitHub CLI and run this script by hand, or let the first run report it"
+  exit 0
+fi
+if ! gh auth status >/dev/null 2>&1; then
+  echo "gh is not logged in: no labels created; run 'gh auth login' and this script by hand, or let the first run report it"
+  exit 0
+fi
+
 lab() { gh label create "$1" --description "$2" --color "$3" --force >/dev/null && echo "  $1"; }
 
 echo "category labels"

package/recipes/issue-loop/recipe.toml

@@ -1,6 +1,8 @@
 # The issue loop: the tracker as a state machine that three loops turn. docs/recipes.md explains it.
 name = "issue-loop"
 summary = "Triage new issues into agent briefs, build the accepted ones in a worktree, open pull requests; a person promotes and merges."
+tier = "advanced"
+useful_when = ["Issues arrive faster than you read them, and most are buildable once someone writes the brief.", "You want the tracker to be the state machine, and your part to be two clicks: accept the brief, merge the pull request."]
 needs_tracker = true
 levels = ["propose", "act"]
 setup = "labels.sh"

package/recipes/issue-loop/triage.md

@@ -74,9 +74,12 @@ instead (the states and the checkpoints are the same).
 4. **Apply the outcome.**
    - **Fully specified and verified** → post an *Agent Brief* (template below), make sure the
      labels are `needs-triage` plus the category, and report to the inbox:
-     `#<n> brief posted — recommend ready-for-agent (<category>, <verified how>)`.
+     `#<n> brief posted — recommend ready-for-agent (<category>, <verified how>) · waits: the
+     implement loop skips it until labeled · if not: stays needs-triage, no reminder`.
    - **Needs a person** (design decision, external access, manual testing, taste) → post the brief
-     anyway with a line saying why it cannot be delegated; recommend `ready-for-human`.
+     anyway with a line saying why it cannot be delegated; recommend `ready-for-human`:
+     `#<n> brief posted — recommend ready-for-human (<why>) · waits: a person · if not: stays
+     needs-triage`.
    - **Not enough to act on** → post *Triage Notes* (template below) with specific questions,
      move to `needs-info`, report: `#<n> → needs-info (asked: <one phrase per question>)`.
    - **Already implemented** → say where it lives in a comment; recommend `wontfix (already
@@ -86,6 +89,10 @@ instead (the states and the checkpoints are the same).
    - **Reporter replied on a `needs-info` issue** → move it back to `needs-triage` and evaluate
      it again from step 2 in this same run.
 
+   Every recommendation you report is a checkpoint, and the shape is fixed: the recommendation,
+   then ` · waits: <what the label unblocks> · if not: <what stays as it is>`. Under `act`, the
+   moves you make yourself are reported as news, without the two clauses.
+
    Labels: `gh issue edit <n> --add-label "<state>" --remove-label "<old state>"`. Never leave an
    issue with two state labels. Under `propose`, never close an issue.
 
@@ -145,3 +152,10 @@ the oldest `needs-info` lines; the tracker still has everything.
 
 One line per issue you acted on, in the shapes above. No issues needing attention → no inbox
 lines. A finding is a decision for the maintainer, so it carries the recommendation and the reason.
+
+## Never
+
+Never edit code, open a branch or a worktree, or touch an issue in `ready-for-agent`,
+`agent-working`, `in-review` or `agent-blocked`. Never leave an issue with two state labels.
+Never close an issue under `propose`; under `act`, never close anything but an already-implemented
+request or a duplicate. Never post a comment without the line saying it was generated by AI.

package/recipes/pr-watch/recipe.toml

@@ -1,8 +1,11 @@
 # pr-watch: the open pull requests, and only what changed about them. docs/recipes.md.
 name = "pr-watch"
 summary = "Watches the open pull requests for what stalls them — a red check, a conflict, a review nobody answered — and reports only what changed since last time."
+tier = "starter"
+useful_when = ["Pull requests stall for days before anyone notices the red check or the unanswered review.", "You want to hear what changed about them, not what they are."]
 needs_tracker = true
 levels = ["report", "propose"]
+needs = ["gh", "tracker-github"]
 budget_hint_usd = 2
 
 [[job]]

package/skills/pi-loops/SKILL.md

@@ -17,7 +17,7 @@ The user's pi has pi-loops installed. Prefer its tools over ad-hoc `sleep` loops
 | the findings must be double-checked before the user sees them | `cron_create` with `stateful: true, verify: true` (a second adversarial sub-agent reviews each finding) |
 | "when <condition> happens, do <action>" (a file appears, a PR merges, a build finishes) | `new_trigger` — condition + action, fires once unless the user asks for repeating |
 | a reminder in N minutes | `cron_create` with schedule `in 10m` |
-| run the project's issue tracker as a standing process (triage, build, review), or an experiment loop against a research contract | tell the user to run `/recipe list` and `/recipe add <name>` — a packaged set of loops installed with one confirmation; do not recreate it with `cron_create` |
+| run the project's issue tracker as a standing process (triage, build, review), an experiment loop against a research contract, a CI or dependency sweeper, a PR watch, a daily digest | tell the user to run `/recipe list` and `/recipe add <name>` — a packaged set of loops installed with one confirmation; do not recreate it with `cron_create` |
 
 Never use `new_trigger` for time-based schedules; never use `cron_create` for conditions.
 
@@ -42,7 +42,8 @@ reported in your notes; report only new or newly closed issues". Findings should
 
 ## Triage
 
-`/inbox` lists findings; `/inbox claim <n>` hands one to you as a real turn; `/inbox dismiss <n>`.
+`/inbox` lists findings; `/inbox claim <n>` hands one to you as a real turn; `/inbox dismiss <n> [reason]`
+(a reason is shown to the loop's next run, so a finding the user calls noise can say why).
 `/cron` lists jobs, `/cron runs`, `/cron trace <job> [k]` shows what a run did. `/triggers rules`,
 `/triggers audit` for dynamic triggers.
 

package/src/archive.ts

@@ -17,11 +17,12 @@ import { createHash, randomUUID } from "node:crypto";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
+import { sameProject } from "./presence.ts";
 import { LOOP_STATE_MAX_CHARS, capChars } from "./protocol.ts";
 import { previewRedacted } from "./redact.ts";
 import { computeNext, formatSchedule, isValidSchedule, stamp } from "./schedule.ts";
-import { newId, type LoopJob } from "./store.ts";
-import { type DynamicTriggerRule, newRuleId } from "./triggers.ts";
+import { type JobStore, newId, type LoopJob } from "./store.ts";
+import { type DynamicTriggerRule, type TriggerStore, newRuleId } from "./triggers.ts";
 
 export const ARCHIVE_SCHEMA = "pi-loops.session_export.v1";
 export const ARCHIVE_EXT = ".pisession";
@@ -182,6 +183,24 @@ export function defaultExportPath(cwd: string, sessionId: string): string {
 	return path.join(cwd, `pi-session-${sessionId.slice(0, 16)}${ARCHIVE_EXT}`);
 }
 
+/**
+ * What an export of `sessionId` in `cwd` carries: this project's automation, narrowed to what that
+ * session created.
+ *
+ * The store is machine-global, so the project alone would sweep in a colleague's loops — or your
+ * own from another window — and the session that created a job or rule is what scopes the archive.
+ * A job or rule from before `createdBy` existed has no owner to ask, and counts as this session's
+ * when it is in this project. "This project" is `sameProject`, not a string comparison: a worktree
+ * or a symlinked path is the same project and its loops belong in the same archive.
+ */
+export function automationOf(jobs: LoopJob[], rules: DynamicTriggerRule[], cwd: string, sessionId?: string): { jobs: LoopJob[]; rules: DynamicTriggerRule[] } {
+	const mine = (owner: { sessionId?: string } | undefined, ownerCwd: string): boolean => (owner?.sessionId ? owner.sessionId === sessionId : sameProject(ownerCwd, cwd));
+	return {
+		jobs: jobs.filter((j) => sameProject(j.cwd, cwd) && mine(j.createdBy, j.cwd)),
+		rules: rules.filter((r) => sameProject(r.cwd, cwd) && mine(r.createdBy, r.cwd)),
+	};
+}
+
 export function exportSession(input: ExportInput): ExportSummary {
 	const sessionBytes = fs.readFileSync(input.sessionFile);
 	if (sessionBytes.length > MAX_SESSION_BYTES) throw new Error("session file exceeds the 50 MiB archive cap");
@@ -437,6 +456,82 @@ export function importSession(input: ImportInput): ImportSummary {
 	};
 }
 
+/**
+ * What `--activate-triggers` says about the automation an archive carries: leave it off and say
+ * nothing (`off`), ask once after the import whether to switch back on what the source had on
+ * (`ask`, the default), or activate it as part of the import (`on`).
+ */
+export type ActivateMode = "off" | "ask" | "on";
+
+/** `--activate-triggers=X` and `--activate-triggers X`, wherever either is typed. */
+export function parseActivateMode(value: string | undefined): ActivateMode {
+	if (value === undefined) return "ask";
+	if (value === "off" || value === "ask" || value === "on") return value;
+	throw new Error(`--activate-triggers must be off, ask or on (got ${value})`);
+}
+
+/**
+ * Commit an import to the stores: jobs, then their loop state, then rules.
+ *
+ * A write that fails part way is rolled back — the imported session file, the imported jobs and
+ * their state files go, and the original error is rethrown — because the alternative is a store
+ * holding half an archive: jobs whose rules never arrived, or a session file nothing points at.
+ * The rollback is best effort by construction; the failure it is undoing is usually a store that
+ * cannot be written.
+ */
+export async function applyImport(imp: ImportSummary, jobStore: JobStore, triggerStore: TriggerStore): Promise<void> {
+	try {
+		if (imp.jobs.length) await jobStore.mutate((jobs) => ({ jobs: [...jobs, ...imp.jobs], result: undefined }));
+		for (const [id, text] of Object.entries(imp.states)) jobStore.writeState(id, text);
+		if (imp.rules.length) await triggerStore.mutate((rules) => rules.push(...imp.rules));
+	} catch (err) {
+		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 jobStore.mutate((jobs) => ({ jobs: jobs.filter((j) => !ids.has(j.id)), result: undefined })).catch(() => {});
+		for (const id of ids) attempt(() => fs.rmSync(jobStore.statePath(id), { force: true }));
+		throw err;
+	}
+}
+
+/**
+ * What `ask` means: after an import that did not activate, offer once to switch back on what the
+ * source session had on, and do it if the answer is yes. Returns what was enabled.
+ *
+ * `confirm` is the caller's way of asking — a TUI dialog, a terminal prompt — and a caller with
+ * nobody to ask passes nothing, which is the same as no. `onJobEnabled` is the hook the extension
+ * uses to keep its cron audit trail; nothing else needs it.
+ */
+export async function offerToEnable(
+	imp: ImportSummary,
+	jobStore: JobStore,
+	triggerStore: TriggerStore,
+	confirm?: (question: string, detail: string) => boolean | Promise<boolean>,
+	onJobEnabled?: (before: LoopJob, after: LoopJob) => void,
+): Promise<{ jobs: number; rules: number }> {
+	const none = { jobs: 0, rules: 0 };
+	if (imp.automationEnabled) return none;
+	const pending = imp.originallyEnabledJobs.length + imp.originallyEnabledRules.length;
+	if (!pending || !confirm) return none;
+	const ok = await 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) return none;
+	for (const id of imp.originallyEnabledJobs) {
+		const before = jobStore.load().find((j) => j.id === id);
+		const after = await jobStore.update(id, (j) => {
+			j.enabled = true;
+		});
+		if (before && after) onJobEnabled?.(before, after);
+	}
+	for (const id of imp.originallyEnabledRules) await triggerStore.setEnabled(id, true);
+	return { jobs: imp.originallyEnabledJobs.length, rules: imp.originallyEnabledRules.length };
+}
+
 /**
  * Recognises automation this store already imported from the same archive. Without it, importing an
  * archive twice leaves two live copies of every job and rule, each running and each billing.

package/src/cli.ts

@@ -15,8 +15,11 @@ import * as path from "node:path";
 import * as readline from "node:readline";
 import { fileURLToPath } from "node:url";
 import { SessionManager, getAgentDir } from "@earendil-works/pi-coding-agent";
-import { exportSession, defaultExportPath, importSession, inspectArchive } from "./archive.ts";
+import { applyImport, automationOf, exportSession, defaultExportPath, importSession, inspectArchive, offerToEnable, parseActivateMode } from "./archive.ts";
 import { askHost, renderHostSnapshot } from "./host-control-channel.ts";
+import { FINDING_FIELDS, Inbox, type InboxEntry, inProject, resolveInboxRef } from "./inbox.ts";
+import { sameProject } from "./presence.ts";
+import { redact } from "./redact.ts";
 import { liveHost, stopHost } from "./host-control.ts";
 import { type UiPrefs, readUiPrefs } from "./ui-prefs.ts";
 import { JobStore, defaultLoopsDir } from "./store.ts";
@@ -96,7 +99,7 @@ export const CLI_USAGE = [
 	"",
 	"pi-loops import <file> [--cwd <dir>] [--activate-triggers=off|ask|on]",
 	"    Restore an archive into --cwd (default: the current directory).",
-	"    Imported automation stays disabled unless --activate-triggers=on (ask: prompt on a terminal).",
+	"    --activate-triggers: off never asks, on activates, ask (the default) prompts after the import.",
 	"",
 	"pi-loops sessions [--all] [--limit <n>]",
 	"    List sessions, newest first: short id, when it started, its automation, what was first said in it.",
@@ -110,6 +113,10 @@ export const CLI_USAGE = [
 	"pi-loops recipe list | show <name|path> | add <name|path> [--cwd <dir>] [--level report|propose|act] [--overwrite]",
 	"    The packaged recipes; what one installs; copy its playbooks into a project (.agents/skills/<name>/).",
 	"    The setup script and the jobs need a pi open in the project: /recipe add <name> finds the copies and finishes.",
+	"",
+	"pi-loops inbox list [--all] [--cwd <dir>] | claim <id> | dismiss <id> [--reason <text>]   [--json]",
+	"    The triage inbox with no pi open: what /inbox lists, and the two things it does to a finding.",
+	"    --json prints the shape docs/downstream.md fixes for programs.",
 ].join("\n");
 
 /**
@@ -188,6 +195,12 @@ interface Parsed {
 	flags: Map<string, string | true>;
 }
 
+/**
+ * Flags that never take a value, so the word after them is a positional: `inbox claim --json <id>`
+ * must not read the id as the value of `--json`.
+ */
+const BOOLEAN_FLAGS = new Set(["all", "json", "check", "overwrite", "exclude-triggers", "help"]);
+
 export function parseCliArgs(argv: string[]): Parsed {
 	const [command = "", ...rest] = argv;
 	const positional: string[] = [];
@@ -200,7 +213,7 @@ export function parseCliArgs(argv: string[]): Parsed {
 		}
 		const eq = arg.indexOf("=");
 		if (eq > 0) flags.set(arg.slice(2, eq), arg.slice(eq + 1));
-		else if (rest[i + 1] !== undefined && !rest[i + 1].startsWith("--")) flags.set(arg.slice(2), rest[++i]);
+		else if (!BOOLEAN_FLAGS.has(arg.slice(2)) && rest[i + 1] !== undefined && !rest[i + 1].startsWith("--")) flags.set(arg.slice(2), rest[++i]);
 		else flags.set(arg.slice(2), true);
 	}
 	return { command, positional, flags };
@@ -250,6 +263,7 @@ export async function runCli(argv: string[], out: (line: string) => void = conso
 	if (command === "upgrade") return upgrade(flags.has("check"), out);
 	if (command === "install-launcher") return installLauncher(str("dir"), out);
 	if (command === "recipe") return recipeCommand(positional, { level: str("level"), overwrite: flags.has("overwrite") }, cwd, loopsDir, out);
+	if (command === "inbox") return inboxCommand(positional, { all: flags.has("all"), json: flags.has("json"), reason: flags.get("reason") }, cwd, loopsDir, out);
 
 	if (command === "sessions") {
 		// `pickSession` refuses an unknown id, and there was no way to discover one.
@@ -287,9 +301,9 @@ export async function runCli(argv: string[], out: (line: string) => void = conso
 		const sessions = listSessions(path.join(agentDir, "sessions"));
 		const picked = pickSession(sessions, { id: str("session"), cwd });
 		const jobStore = new JobStore(loopsDir);
-		// The archive carries this project's automation, the way the slash command does.
-		const jobs = jobStore.load().filter((job) => job.cwd === picked.cwd);
-		const rules = new TriggerStore(loopsDir).load().filter((rule) => rule.cwd === picked.cwd);
+		// The archive carries what the picked session created in its project — the one rule
+		// `/session-export` follows too, in `automationOf`.
+		const { jobs, rules } = automationOf(jobStore.load(), new TriggerStore(loopsDir).load(), picked.cwd, picked.id);
 		const states: Record<string, string> = {};
 		for (const job of jobs) {
 			const loopState = job.stateful ? jobStore.readState(job.id) : undefined;
@@ -305,28 +319,31 @@ export async function runCli(argv: string[], out: (line: string) => void = conso
 	if (command === "import") {
 		const file = positional[0];
 		if (!file) throw new Error("import needs an archive path");
-		const mode = str("activate-triggers") ?? "off";
-		if (!["off", "ask", "on"].includes(mode)) throw new Error(`--activate-triggers must be off, ask or on (got ${mode})`);
+		const mode = parseActivateMode(str("activate-triggers"));
 		const jobStore = new JobStore(loopsDir);
 		const triggerStore = new TriggerStore(loopsDir);
 		// pi encodes a project as `--home-u-proj--` and `SessionManager.list()` reads only that one
 		// directory, with no fallback — a hand-rolled name here would restore a session pi never sees.
 		const sessionDir = SessionManager.create(cwd).getSessionDir();
-		const activate = mode === "on" || (mode === "ask" && (await askYesNo("Activate the imported automation now?")));
 		const existingJobs = jobStore.load();
 		const existingRules = triggerStore.load();
-		const summary = importSession({ archivePath: path.resolve(file), sessionDir, targetCwd: cwd, activate, existingJobs, existingRules, existingJobIds: new Set(existingJobs.map((j) => j.id)), existingRuleIds: new Set(existingRules.map((r) => r.id)) });
-		// The same order the slash command uses, so a half-import leaves neither store inconsistent.
-		if (summary.jobs.length) await jobStore.mutate((jobs) => ({ jobs: [...jobs, ...summary.jobs], result: undefined }));
-		for (const [id, text] of Object.entries(summary.states)) jobStore.writeState(id, text);
-		if (summary.rules.length) await triggerStore.mutate((rules) => rules.push(...summary.rules));
+		const summary = importSession({ archivePath: path.resolve(file), sessionDir, targetCwd: cwd, activate: mode === "on", existingJobs, existingRules, existingJobIds: new Set(existingJobs.map((j) => j.id)), existingRuleIds: new Set(existingRules.map((r) => r.id)) });
+		// The writes and the rollback the slash command does, in `applyImport`.
+		await applyImport(summary, jobStore, triggerStore);
 		const skipped = (summary.skippedJobs ?? 0) + (summary.skippedRules ?? 0);
 		// The id and the notes come out of the archive's own header, like everything `inspect` prints.
 		out(`imported ${plain(summary.originalSessionId)} → ${summary.sessionId}`);
 		out(`entries=${plain(String(summary.entryCount))} cron=${summary.jobs.length} triggers=${summary.rules.length} automation=${summary.automationEnabled ? "enabled" : "disabled"}${skipped ? ` skipped=${skipped} (already imported)` : ""}`);
 		for (const note of summary.notes ?? []) out(`note: ${plain(note)}`);
 		out(`session: ${summary.sessionPath}`);
-		if (!summary.automationEnabled && (summary.jobs.length || summary.rules.length)) out("automation is disabled; enable it with /cron enable <id> or re-import with --activate-triggers=on");
+		// `ask` is the default: the same question the slash command asks, once, after the import.
+		// `askYesNo` already answers no with no terminal to ask at.
+		const enabled = await offerToEnable(summary, jobStore, triggerStore, mode === "ask" ? (question, detail) => {
+			if (process.stdin.isTTY) out(detail); // what the dialog shows above the question
+			return askYesNo(question);
+		} : undefined);
+		if (enabled.jobs || enabled.rules) out(`enabled ${enabled.jobs} cron job(s) and ${enabled.rules} trigger rule(s)`);
+		else if (!summary.automationEnabled && (summary.jobs.length || summary.rules.length)) out("automation is disabled; enable it with /cron enable <id> or re-import with --activate-triggers=on");
 		return 0;
 	}
 
@@ -393,7 +410,77 @@ export async function runCli(argv: string[], out: (line: string) => void = conso
 	return asked ? 2 : 0;
 }
 
-const SUBCOMMANDS = new Set(["export", "import", "sessions", "inspect", "host", "recipe", "web", "upgrade", "install-launcher", "help"]);
+const SUBCOMMANDS = new Set(["export", "import", "sessions", "inspect", "host", "recipe", "inbox", "web", "upgrade", "install-launcher", "help"]);
+
+/**
+ * `pi-loops inbox`: `/inbox list|claim|dismiss` for a shell with no pi open, and — with `--json` —
+ * for a program. The JSON is the contract in docs/downstream.md: the fields, their names and their
+ * types are fixed there, and `test/downstream/inbox.sh` reads them back with jq. What is not fixed:
+ * the plain text, which is for a person at a prompt. A claim here marks the finding and stops,
+ * since there is no session to hand it to; the caller is the one who acts on it.
+ */
+async function inboxCommand(positional: string[], opts: { all: boolean; json: boolean; reason?: string | true }, cwd: string, loopsDir: string, out: (line: string) => void): Promise<number> {
+	const fail = (why: string): number => {
+		out(opts.json ? JSON.stringify({ error: why }) : why);
+		return 1;
+	};
+	try {
+		return await inboxCommandBody(positional, opts, cwd, loopsDir, out, fail);
+	} catch (err: any) {
+		// A program reads one object either way: an unreadable file or a lock that timed out is an
+		// `error` on stdout, not a usage dump on stderr.
+		return fail(err?.message ?? String(err));
+	}
+}
+
+async function inboxCommandBody(positional: string[], opts: { all: boolean; json: boolean; reason?: string | true }, cwd: string, loopsDir: string, out: (line: string) => void, fail: (why: string) => number): Promise<number> {
+	const sub = positional[0] ?? "list";
+	const inbox = new Inbox(loopsDir);
+	if (sub === "list") {
+		const entries = opts.all ? inbox.listNew() : inProject(inbox.listNew(), cwd, sameProject);
+		if (opts.json) {
+			out(JSON.stringify({ findings: entries.map(findingJson) }));
+			return 0;
+		}
+		if (!entries.length) out(opts.all ? "inbox: nothing new on this machine" : `inbox: nothing new in ${cwd} (--all lists every project)`);
+		for (const e of entries) out(findingLine(e));
+		return 0;
+	}
+	if (sub === "claim" || sub === "dismiss") {
+		const ref = positional[1];
+		if (!ref) return fail(`inbox ${sub} needs a finding id`);
+		if (opts.reason === true) return fail("--reason needs a text (--reason=<text> when it starts with --)");
+		// An id or a prefix resolves machine-wide, as it does in /inbox, and only among what is new:
+		// a finding already claimed or dismissed is not decided twice. A number resolves to nothing
+		// here — `/inbox claim 3` is the number on a screen, and this command printed none — and the
+		// digits only pick the wording, since "no entry matching '1'" reads like a missing finding.
+		const entry = resolveInboxRef(inbox.listNew(), ref);
+		if (!entry) return fail(/^\d+$/.test(ref.trim()) ? `inbox ${sub} takes a finding id (inb-…) or a prefix of one, not a number` : `no new inbox entry matching '${ref}'`);
+		const updated = await inbox.setStatus(entry.id, sub === "claim" ? "claimed" : "dismissed", sub === "claim" ? "cli" : undefined, opts.reason);
+		if (!updated) return fail(`inbox entry ${entry.id} is gone`);
+		out(opts.json ? JSON.stringify({ finding: findingJson(updated) }) : `${updated.status} ${updated.id}`);
+		return 0;
+	}
+	return fail(`unknown inbox command ${JSON.stringify(sub)} (list | claim <id> | dismiss <id> [--reason <text>])`);
+}
+
+/**
+ * One finding as docs/downstream.md fixes it: the contract's fields of the entry and nothing else,
+ * in their order, with what a person may read redacted. Fields are added at the end, never renamed.
+ */
+function findingJson(e: InboxEntry): Record<string, unknown> {
+	const out: Record<string, unknown> = {};
+	for (const field of FINDING_FIELDS) out[field] = e[field];
+	out.text = redact(e.text);
+	out.dismiss_reason = e.dismiss_reason === null ? null : redact(e.dismiss_reason);
+	return out;
+}
+
+/** A person's line: the full id (it is what `claim` takes), the finding, where and when it came from. */
+function findingLine(e: InboxEntry): string {
+	const mark = `${e.kind === "checkpoint" ? "⚑ " : ""}${e.verified ? "✓ " : ""}`;
+	return `${e.id}  ${mark}${plain(redact(e.text))}  (${path.basename(e.cwd) || e.cwd || "—"}, ${e.source}, ${e.created_at})`;
+}
 
 /**
  * `pi-loops recipe`: the deterministic part of `/recipe`, for a shell with no pi open. `add` copies

package/src/goal.ts

@@ -171,6 +171,17 @@ export function pauseFor(state: GoalState, reason: string, now = new Date()): {
 	return { state: { ...state, status: "paused", lastReason: reason, updatedAt: stamp(now.getTime()) }, action: { kind: "pause", reason } };
 }
 
+/**
+ * Esc on a turn is a person saying stop. The goal it was pursuing pauses — appended to the session,
+ * so a `--resume` finds it paused — until `/goal resume`. Without this the turn was merely not
+ * judged, and the next message the person sent brought the evaluator back to send them to work.
+ * Only a pursued goal changes; a paused, achieved or budget-limited one has nothing to stop.
+ */
+export function abortedTurn(state: GoalState, now = new Date()): { state: GoalState; action: GoalAction } | undefined {
+	if (state.status !== "pursuing") return undefined;
+	return pauseFor(state, "you stopped the turn (Esc); /goal resume to continue", now);
+}
+
 /** One line for `/goal` and the panel. */
 export function goalLine(state: GoalState): string {
 	const iter = `${state.iterations}/${MAX_CONTINUATIONS}`;

package/src/hooks.ts

@@ -12,7 +12,8 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { envFlag } from "./config.ts";
-import { previewRedacted } from "./redact.ts";
+import { previewRedacted, redact } from "./redact.ts";
+import type { LoopJob, RunRecord } from "./store.ts";
 import { parseToml } from "./toml.ts";
 import { PI_LOOPS_VERSION } from "./version.ts";
 
@@ -82,6 +83,29 @@ export interface HookPayload {
 /** Event-specific fields; the runner fills in the session-level ones. */
 export type HookEventData = Pick<HookPayload, "event" | "message_kind" | "message_summary" | "assistant_event" | "tool_call_id" | "tool_name" | "tool_is_error" | "tool_args" | "tool_result_summary" | "compaction_trigger" | "compaction_tokens_before" | "compaction_summary" | "compaction_failed" | "run_job" | "run_id" | "run_ok" | "run_findings" | "run_error" | "run_cost_usd">;
 
+/**
+ * The same two events the interactive extension and the headless host fire. 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 —
+ * so both processes fire the object these two return.
+ */
+export function runStartEvent(job: LoopJob, runId: string): HookEventData {
+	return { event: "run_start", run_job: job.name ?? job.id, run_id: runId, message_summary: truncateSummary(`${job.name ?? job.id}: ${job.prompt}`) };
+}
+
+export function runEndEvent(job: LoopJob, record: RunRecord): HookEventData {
+	const label = job.name ?? job.id;
+	return {
+		event: "run_end",
+		run_job: label,
+		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 ? `${label}: ok · ${record.findings} finding(s)` : `${label}: failed: ${record.error ?? "unknown error"}`),
+	};
+}
+
 export interface ParsedHooksFile {
 	allowProjectHooks: boolean;
 	hooks: HookConfig[];

package/src/host-runtime.ts

@@ -7,7 +7,7 @@
 import type { ToolDefinition } from "@earendil-works/pi-coding-agent";
 import * as path from "node:path";
 import type { LoopsConfig } from "./config.ts";
-import { HookRunner, truncateSummary } from "./hooks.ts";
+import { HookRunner, runEndEvent, runStartEvent } from "./hooks.ts";
 import { PI_BUILTIN_TOOL_NAMES } from "./mcp.ts";
 import { redact } from "./redact.ts";
 import type { SubagentRequest, SubagentRunner } from "./runner.ts";
@@ -119,7 +119,7 @@ export function createHostRuntime(deps: HostRuntimeDeps): HostRuntime {
 				// scheduler calls this synchronously). `.catch` because a rejection nobody owns takes
 				// the host down — hooks warn per rule, so there is nothing else to do with one.
 				const hooks = hookRunnerFor(job, runId);
-				if (hooks) void hooks.fire({ event: "run_start", run_job: job.name ?? job.id, run_id: runId, message_summary: truncateSummary(`${job.name ?? job.id}: ${job.prompt}`) }).catch((err: any) => log(`hooks: ${redact(err?.message ?? String(err))}`));
+				if (hooks) void hooks.fire(runStartEvent(job, runId)).catch((err: any) => log(`hooks: ${redact(err?.message ?? String(err))}`));
 			},
 			onCatchUp: (job) => log(`loop ${job.name ?? job.id}: catching up a missed tick`),
 			onRunFinished: ({ job, record, result }) => {
@@ -129,14 +129,10 @@ export function createHostRuntime(deps: HostRuntimeDeps): HostRuntime {
 				if (!hooks) return;
 				// `$PI_RUN_OK` alone answers "did last night's loop fail" — the thing the host exists to
 				// be able to tell someone.
-				const label = job.name ?? job.id;
-				const summary = record.ok ? `${label}: ok · ${record.findings} finding(s)` : `${label}: failed: ${record.error ?? "unknown error"}`;
 				// Its own hooks are the last thing a run does; the runner is dropped once they have run
 				// (until then `stop()` still has to drain it).
 				const forget = () => void runHooks.delete(record.runId);
-				void hooks
-					.fire({ event: "run_end", run_job: label, 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(summary) })
-					.then(forget, forget);
+				void hooks.fire(runEndEvent(job, record)).then(forget, forget);
 			},
 			onTick: async (now, leader) => {
 				if (!leader) {
@@ -153,7 +149,7 @@ export function createHostRuntime(deps: HostRuntimeDeps): HostRuntime {
 	});
 
 	const toInbox = async (content: string, trigger: { sourceLabel: string; traceId: string; cwd?: string }) => {
-		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 ?? "" });
 		return "inbox" as const;
 	};
 	triggers = new TriggerRuntime({