@alphacoder-v0/pi-loops 0.22.3 → 0.22.4

package/CHANGELOG.md

@@ -5,6 +5,54 @@ All notable changes to pi-loops are documented here. The format follows
 
 ## [Unreleased]
 
+## [0.22.4] - 2026-09-20
+
+### Fixed
+- **Removing a running job aborts the run, and the run leaves nothing behind.** `/cron remove`,
+  `cron_remove` and `/recipe remove` deleted the job and left its sub-agent going; the run then
+  wrote its state, filed a finding for a job that no longer existed and recreated `sessions/<id>/`.
+  Removal now aborts an in-flight run and gives it up to two seconds to write its record — enough for
+  a normal abort, not a wait that outlasts a wedged sub-agent — and a run that finds its job gone
+  writes the record only, discarding the state and the findings.
+- **`/cron gc --purge` also collects the transcripts of jobs that are gone.** A removed job that
+  never wrote state but left `sessions/<id>/` behind was invisible to `orphanStates()`, so its
+  transcripts stayed for ever. The orphan scan now unions the state files with the transcript
+  directories and counts both in the size it reports.
+- **`/recipe remove --purge` keeps a playbook you edited.** `purgeInstall` deleted every file in the
+  record without comparing it with its untouched copy under `.orig/`, so an edit that `/recipe
+  update` would have preserved was destroyed without a word. It now removes a file only while it
+  still matches its untouched copy, keeps and names the edited ones, and leaves the directory in
+  place when one remains.
+- **A run whose `jobs.json` is torn mid-flight no longer disappears.** A run re-read the store to ask
+  whether its job was still there, and an empty or too-new file made that read throw: the record, the
+  findings and the run-finished callback were all skipped, so a run that had completed left no trace.
+  A store that cannot be read now counts as "the job is still there" — the record and the findings are
+  written, and only the job's own bookkeeping is skipped.
+- **`/recipe remove --purge` keeps a setup script you edited.** The install copied the setup script
+  but kept no untouched copy of it, and purge deleted it unconditionally, so an edited script was
+  destroyed without a word. The install now writes the `.orig` copy and purge compares it like any
+  other file, keeping and naming the edited one.
+- **The collection of a removed job's leftovers says what it does, and counts all of it.**
+  `removeWhere` deleted state and transcripts with no flag, so the next caller would have thrown away
+  a loop's notes unasked; it now keeps them unless the caller passes `purge`, which is what gc does.
+  The orphan scan also walks the whole transcript tree, so a nested file that `purgeState` deletes is
+  counted in the size `/cron gc` reports.
+- **The command line finds a project's sessions and recipe jobs from a subdirectory.** Three listings
+  compared the recorded directory with `===`, so run from a subdirectory of the project they answered
+  "nothing here" or "0 job(s)". They now use the same realpath-and-containment match the rest of
+  pi-loops uses.
+- **The docs say the command line does not delete.** There is no `cron remove`, `recipe remove` or
+  `inbox clear` on it: removal asks a person to confirm and records what it did in the session's
+  control-plane audit, so it stays in the slash commands.
+- **`/cron remove <name>` no longer reaches into another project.** A name resolved machine-wide, so
+  a name this project does not have deleted another checkout's job and said so in the same words as
+  any other removal. It now follows the rule `cron_remove` already had — a name resolves here, and
+  another project's job needs its exact id — and a removal that did reach outside names the project
+  it reached into.
+- **A one-shot that retires itself leaves a control-plane audit entry.** A one-shot was removed after
+  it fired or failed for the second time with nothing in the trail; the self-removal now goes through
+  the same audit as a removal a person asked for.
+
 ## [0.22.3] - 2026-09-16
 
 ### Changed

package/README.md

@@ -38,7 +38,7 @@ the first sign of credentials that do not work should not be an empty inbox tomo
 
 ```bash
 pi install npm:@alphacoder-v0/pi-loops                      # from npm, following new releases
-pi install git:github.com/alphacoder-v0/pi-loops@v0.22.3    # or from GitHub, at a pinned tag
+pi install git:github.com/alphacoder-v0/pi-loops@v0.22.4    # or from GitHub, at a pinned tag
 pi install /path/to/pi-loops                                # or a local checkout — `pi install .` in this repo
 pi -e /path/to/pi-loops                                     # or none of them: try it for one run, installing nothing
 ```

package/README.zh-CN.md

@@ -45,7 +45,7 @@ pi-loops 自己没有任何运行时依赖。
 
 ```bash
 pi install npm:@alphacoder-v0/pi-loops                      # 从 npm 装，跟着新版本走
-pi install git:github.com/alphacoder-v0/pi-loops@v0.22.3    # 或者从 GitHub 装，钉住一个 tag
+pi install git:github.com/alphacoder-v0/pi-loops@v0.22.4    # 或者从 GitHub 装，钉住一个 tag
 pi install /path/to/pi-loops                                # 或者本地检出；本仓库里就是 pi install .
 ```
 

package/docs/cli.md

@@ -227,6 +227,11 @@ pi-loops recipe list | show <name|path> | add <name|path> [--cwd <dir>] [--level
 pi-loops inbox list [--all] [--cwd <dir>] | claim <id> | dismiss <id> [--reason <text>]   [--json]
 ```
 
+The command line reads, triages one finding at a time and moves sessions. It never creates or
+removes: there is no `cron remove`, no `recipe remove` and no `inbox clear`. Creating and removing
+jobs, rules and recipes are slash commands, because each asks a person first and records what it did
+in the session's control-plane audit.
+
 ## sessions, inspect
 
 `sessions` lists this project's sessions newest first, one line each: the first sixteen

package/docs/configuration.md

@@ -16,6 +16,7 @@ Everything lives under `~/.pi/agent/loops/` (override: `PI_LOOPS_DIR`).
 | `spend.json` | per-day totals of what rotation dropped from the run log, so a daily budget still counts it |
 | `sessions/<job-id>/`, `sessions/triggers-<project>-<hash>/` | sub-agent transcripts (20 per job, 40 per project's checks; the hash of the project's path keeps two projects named alike apart) |
 | `scheduler.json` | timer owner on this machine: pid, heartbeat |
+| `next-runs.json` | job id → when it runs next, as the timer owner computed it (`{ at, next }`). Written only when an answer changes, so it can be older than the last tick; the browser panel reads it rather than parsing schedules a second time |
 | `presence/` | one file per live pi process: pid, session, cwd (who acts for which project) |
 | `host.json`, `host.log` | the headless host that keeps the clock while no pi is open: pid, and its log |
 | `polls.json` | last dynamic check per project (shared, so a hand-over never double-checks) |

package/docs/loops.md

@@ -240,7 +240,8 @@ cron job's clock restarts at the edit, so slots that only exist retroactively un
 expression are not owed. An `every <dur>` job is still measured from its last run — if it last ran
 longer ago than the new interval, it is genuinely overdue and the confirmation says `due now`
 instead of promising a later time. One-shots (`in 10m`, `at <ISO>`) are refused here: the scheduler
-deletes a `once` job after it fires, notes included.
+deletes a `once` job after it fires, notes included, and records the removal in the control-plane
+audit like any other.
 
 `/cron run <ref>` fires a job now instead of at its next due time, and that run counts as a run: a
 `once` job is fired and then removed (an enabled job with nothing left to fire is worse than none),
@@ -300,9 +301,14 @@ anything, so this is how you actually go quiet.
 If a loop is stuck showing `running` after a process was killed and its pid reused, `/cron clear
 <ref>` releases the marker (it asks first).
 
+`/cron remove` takes a name of this project, a number from its listing, or the exact id of a job
+anywhere — the rule `cron_remove` follows, because a removal cannot be undone and a name this
+project does not have should not reach another checkout. A job removed by its exact id from outside
+this project is named with the project it was in.
+
 `/cron remove` keeps the loop's notes (to change a prompt or a schedule, edit the job in place with
 `/cron set` instead); `--purge` deletes them. `/cron gc` collects this project's jobs whose session
-is gone — `--all` every project's, `--purge` also the loop state left behind by jobs that are gone.
+is gone — `--all` every project's, `--purge` also the loop state and transcripts left behind by jobs that are gone.
 
 A job that fails three times in a row is retried on a widening gap (5 minutes, doubling, up to six
 hours) instead of at every due tick, and says so; one success clears the streak.

package/docs/recipes.md

@@ -141,7 +141,8 @@ A playbook installed by hand, with no untouched copy, is left alone and named.
 
 `/recipe remove <name>` removes the recipe's jobs and keeps the files and the loops' notes;
 `--purge` deletes both — of the files, only what the install wrote, since `.agents/skills/` may
-hold the project's own. `/cron` shows recipe jobs like any other, and `/cron set` edits them like
+hold the project's own, and only a file that still matches its untouched copy: a playbook you
+edited is kept and named. `/cron` shows recipe jobs like any other, and `/cron set` edits them like
 any other — a recipe is how they were made, not what they are.
 
 ## Writing a recipe

package/docs/web-ui-parity.md

@@ -25,13 +25,15 @@ weaker, and worth converting whenever one of them breaks.
 - [x] Busy, queued count, and "pi exited" are all visible without opening a terminal.
       `test/web-page.test.ts`: *a tool call and a dead pi both reach the page*.
 - [x] Prompt history: ArrowUp and ArrowDown, but only while the caret is on the first or last line,
-      so they still navigate a multi-line draft.
+      so they still navigate a multi-line draft. `test/web-page.test.ts`: *prompt history recalls what
+      was sent, and steps aside on a middle line*.
 
 ## Composing
 
 - [x] `/` completes slash commands; `@` completes paths, and the mention is expanded before the
       prompt is sent — the expansion is anchored to the session's directory, not to anything the
-      browser supplies.
+      browser supplies. `test/web.test.ts`: *an @ mention is expanded from the session's directory,
+      and one outside it is skipped*.
 - [x] A command with an argument can be typed straight through. The completion list closes on the
       space, and an answer still in flight does not put it back — which it did, so Enter accepted
       the completion instead of sending the line and anything taking an argument was mouse-only.
@@ -85,6 +87,8 @@ weaker, and worth converting whenever one of them breaks.
       `test/web-page.test.ts`: *a gap in the event stream reloads the conversation*.
 - [x] While you are reading back through the conversation, an update never yanks the page — and
       never arrives silently either: there is a way back to the newest.
+      `test/web-page.test.ts`: *an update while you are reading back does not yank the page, and the
+      pill is the way back*.
 - [x] Every block says when it happened.
 - [x] Every message, tool call and result can be copied, including over plain http where the
       clipboard API is unavailable. The button waits for a hover on a mouse and is simply always
@@ -92,7 +96,9 @@ weaker, and worth converting whenever one of them breaks.
 - [x] Tool results, an extension's messages and pi's dying words are capped, and every cap says how
       much was dropped — one helper for the three of them, because they used to report it three
       different ways and one of them not at all, so a result that stopped at 8000 characters looked
-      like a result that ended there.
+      like a result that ended there. The count and the cut are characters, not UTF-16 code units, so
+      an astral character is counted once and a cut cannot end on half of one. `test/web-page.test.ts`:
+      *a capped result counts characters, not the units a string is counted in*.
 - [x] **You can see what the session made, not only read about it.** A picture in a reply is a
       picture — including one named in ordinary prose rather than as a link; a path is something to
       open; a page written into the reply has a preview; an image a tool returned is shown rather
@@ -192,7 +198,9 @@ weaker, and worth converting whenever one of them breaks.
 - [x] A confirmation shows what is about to happen apart from the reasoning about it, so it cannot
       be read as prose and waved through. `test/web-page.test.ts`: *a confirmation shows what is
       about to run*.
-- [x] Enter does not approve: the focus starts on cancel.
+- [x] Enter does not approve: the focus starts on cancel, which is written before approve so the
+      first menu button is the one Enter hits. `test/web-page.test.ts`: *Enter in a confirmation
+      dialog hits cancel, not approve*.
 - [x] **A tab in the background does not hold one of the browser's six connections.** Every tab
       used to keep an event stream open for as long as it existed, so the sixth tab — or a few
       forgotten behind the first — left nothing for the request that sends what you typed, and the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alphacoder-v0/pi-loops",
-  "version": "0.22.3",
+  "version": "0.22.4",
   "description": "An automation layer for pi: cron + stateful loops with a triage inbox, maker/checker verification, dynamic triggers, MCP notifications and tools, lifecycle hooks, session archives. A non-invasive pi extension.",
   "type": "module",
   "license": "MIT",

package/src/cli.ts

@@ -184,7 +184,7 @@ export function pickSession(sessions: SessionFile[], opts: { id?: string; cwd: s
 		if (byPrefix.length > 1) throw new Error(`session id ${opts.id} is ambiguous (${byPrefix.length} matches)`);
 		throw new Error(`no session with id ${opts.id}`);
 	}
-	const here = sessions.filter((s) => s.cwd === opts.cwd);
+	const here = sessions.filter((s) => sameProject(s.cwd, opts.cwd));
 	if (!here.length) throw new Error(`no sessions recorded for ${opts.cwd}; pass --session <id>`);
 	return here[0];
 }
@@ -268,7 +268,7 @@ export async function runCli(argv: string[], out: (line: string) => void = conso
 	if (command === "sessions") {
 		// `pickSession` refuses an unknown id, and there was no way to discover one.
 		const sessions = listSessions(path.join(agentDir, "sessions"));
-		const here = flags.has("all") ? sessions : sessions.filter((s) => s.cwd === cwd);
+		const here = flags.has("all") ? sessions : sessions.filter((s) => sameProject(s.cwd, cwd));
 		if (!here.length) {
 			out(flags.has("all") ? "no sessions recorded" : `no sessions recorded for ${cwd} (use --all)`);
 			return 1;
@@ -493,7 +493,7 @@ async function recipeCommand(positional: string[], opts: { level?: string; overw
 	if (sub === "list") {
 		const packaged = listRecipes();
 		const installed = new Map(installedRecipes(cwd).map((r) => [r.recipe, r]));
-		const jobs = new JobStore(loopsDir).load().filter((j) => j.recipe && j.cwd === cwd);
+		const jobs = new JobStore(loopsDir).load().filter((j) => j.recipe && sameProject(j.cwd, cwd));
 		for (const r of packaged) {
 			const rec = installed.get(r.manifest.name);
 			const n = jobs.filter((j) => j.recipe === r.manifest.name).length;

package/src/pi-loops.ts

@@ -50,7 +50,7 @@ import { waitForHost, HOST_LOG, crashedHost, hostPushWork, liveHost, piPackageDi
 import { summarizeSessionFile } from "./transcript.ts";
 import { TriggerRuntime, type TriggerOutcome } from "./trigger-runtime.ts";
 import { auditCronFinish, auditCronStart, TriggerStore, buildPeriodicCheckTrigger, controlPlanePreflight, resolveRuleRef } from "./triggers.ts";
-import { type ControlPlaneRequest, type CreateJobInput, type JobScope, type ToolHost, automationTools, checkJobName, createLoopJob } from "./tools.ts";
+import { type ControlPlaneRequest, type CreateJobInput, type JobScope, type ToolHost, automationTools, checkJobName, createLoopJob, resolveJobRefScoped } from "./tools.ts";
 import { panelEnabled, readUiPrefs, writeUiPref } from "./ui-prefs.ts";
 import * as fs from "node:fs";
 import * as os from "node:os";
@@ -197,6 +197,7 @@ export default function piLoops(pi: ExtensionAPI) {
 			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");
 			},
+			onJobRetired: (job) => cronControlAudit("remove", "scheduler", job, undefined),
 			onRunFinished: ({ job, record, findings, result }) => {
 				auditCronFinish(triggers.store, job, record, result.stopReason === "aborted");
 				refreshBadge();
@@ -653,8 +654,9 @@ export default function piLoops(pi: ExtensionAPI) {
 		const n = scheduler.inbox.newCount();
 		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.
+		// Machine-wide like the inbox count and the running list above it: one process owns the
+		// machine's clock, and a loop failing in another checkout is still this machine's automation
+		// going quiet.
 		const failing = failingSummary(scheduler.store.load());
 		if (failing) parts.push(failing);
 		const running = [...scheduler.runningLabels(), ...triggers.runningList().map((r) => (r.sourceLabel === "local:dynamic" ? "trigger-check" : r.sourceLabel))];
@@ -766,7 +768,7 @@ export default function piLoops(pi: ExtensionAPI) {
 	 * The `cron_control_plane` audit: every add / enable / disable / remove, from a slash
 	 * command or a tool, leaves a custom entry in the session (never in LLM context).
 	 */
-	function cronControlAudit(op: "add" | "enable" | "disable" | "remove", actor: "slash" | "tool" | "sub-agent", before?: LoopJob, after?: LoopJob): string {
+	function cronControlAudit(op: "add" | "enable" | "disable" | "remove", actor: "slash" | "tool" | "sub-agent" | "scheduler", before?: LoopJob, after?: LoopJob): string {
 		const job = after ?? before;
 		const next = after?.enabled ? computeNext({ schedule: after.schedule, createdAt: Date.parse(after.createdAt), lastFiredAt: after.lastFiredAt ? Date.parse(after.lastFiredAt) : undefined }, Date.now()) : undefined;
 		// pi.appendEntry returns no id; mint one so tool results can point at the entry.
@@ -952,12 +954,26 @@ export default function piLoops(pi: ExtensionAPI) {
 						// remove-and-re-add is how a schedule or prompt gets changed, and that must not
 						// throw away months of accumulated state.
 						const purge = /(^|\s)--purge(\s|$)/.test(rest);
-						const job = pick(rest.replace(/(^|\s)--purge(\s|$)/, " ").trim());
-						if (!job) return;
-						await scheduler.store.remove(job.id, { purge });
+						// `pick` resolves a name machine-wide, which is right for `/cron run ci` and wrong
+						// here: a removal cannot be undone, and a name this project does not have would
+						// reach into a checkout nobody was looking at and delete its job with a message
+						// that never says so. `resolveJobRefScoped` is the rule `cron_remove` already
+						// follows — a name resolves in this project, another project's job needs its
+						// exact id — so the two faces of the same deletion agree.
+						const ref = rest.replace(/(^|\s)--purge(\s|$)/, " ").trim();
+						const all = jobs();
+						const job = /^\d+$/.test(ref) ? resolveJobRef(all.filter((j) => sameProject(j.cwd, session.cwd)), ref, { ordinals: true }) : resolveJobRefScoped(all, ref, session.cwd);
+						if (!job) {
+							ctx.ui.notify(ref ? `no cron job with id '${ref}' in ${homeRel(session.cwd)} (another project's job needs its exact id)` : "usage: /cron remove <id> [--purge]", "warning");
+							return;
+						}
+						const { aborted } = await scheduler.removeJob(job.id, { purge });
 						cronControlAudit("remove", "slash", job, undefined);
 						const kept = job.stateful && !purge ? `; its loop state is kept (${homeRel(scheduler.store.statePath(job.id))}) — /cron gc --purge clears orphaned state` : purge && job.stateful ? " and its loop state" : "";
-						ctx.ui.notify(`removed cron job ${job.id}${job.name ? ` "${job.name}"` : ""}${kept}`, "info");
+						// An exact id may still name another project's job. Say which, so a removal that
+						// reached outside this checkout is never a line that looks like any other.
+						const elsewhere = sameProject(job.cwd, session.cwd) ? "" : ` in ${homeRel(job.cwd)}`;
+						ctx.ui.notify(`removed cron job ${job.id}${job.name ? ` "${job.name}"` : ""}${elsewhere}${kept}${aborted > 0 ? "; aborted its running run" : ""}`, "info");
 						return;
 					}
 					case "host": {
@@ -1056,9 +1072,9 @@ export default function piLoops(pi: ExtensionAPI) {
 						if (purge && orphans.length) for (const o of orphans) scheduler.store.purgeState(o.id);
 						show(ctx, `removed ${removed.length} job(s) whose session no longer exists${all ? " (every project)" : " in this project"}`, [
 							...removed.map((j) => `  - ${j.id}${j.name ? ` "${j.name}"` : ""}  (session ${(j.sessionId ?? "?").slice(0, 8)})`),
-							...(orphans.length && !purge ? [`  ${orphans.length} loop state file(s) belong to jobs that are gone (${Math.round(orphans.reduce((n, o) => n + o.bytes, 0) / 1024)} KB) — /cron gc --purge deletes them`] : []),
+							...(orphans.length && !purge ? [`  ${orphans.length} job(s) that are gone left loop state or transcripts behind (${Math.round(orphans.reduce((n, o) => n + o.bytes, 0) / 1024)} KB) — /cron gc --purge deletes them`] : []),
 							...(all ? [] : ["  --all also collects other projects' dead jobs"]),
-							...(purge && orphans.length ? [`  deleted ${orphans.length} orphaned loop state file(s)`] : []),
+							...(purge && orphans.length ? [`  deleted the loop state and transcripts of ${orphans.length} job(s) that are gone`] : []),
 						]);
 						refreshBadge();
 						return;
@@ -2205,19 +2221,24 @@ export default function piLoops(pi: ExtensionAPI) {
 						}
 						const ok = await ctx.ui.confirm(`Remove recipe ${name}?`, [
 							jobs.length ? `${jobs.length} job(s): ${jobs.map((j) => j.name ?? j.id).join(", ")}` : "no jobs of its own here",
-							purge ? `and delete what the install wrote in ${homeRel(dir)}/ (${record ? `${record.files.length} file(s), their untouched copies, the record` : "no record: only the directory if it is empty"}) and the loops' notes` : `the files in ${homeRel(dir)}/ and the loops' notes are kept (--purge deletes both)`,
+							purge ? `and delete what the install wrote in ${homeRel(dir)}/ (${record ? `${record.files.length} file(s) as installed — an edited one is kept — their untouched copies, the record` : "no record: only the directory if it is empty"}) and the loops' notes` : `the files in ${homeRel(dir)}/ and the loops' notes are kept (--purge deletes both)`,
 						].join("\n"));
 						if (!ok) {
 							ctx.ui.notify("not removed", "info");
 							return;
 						}
+						let aborted = 0;
+						let keptNote = "";
 						for (const job of jobs) {
-							await scheduler.store.remove(job.id, { purge });
+							const r = await scheduler.removeJob(job.id, { purge });
+							aborted += r.aborted;
 							cronControlAudit("remove", "slash", job, undefined);
 						}
 						if (purge) {
-							if (record) purgeInstall(dir, record, listRecipes().find((r) => r.manifest.name === name)?.manifest.setup);
-							else {
+							if (record) {
+								const { kept } = purgeInstall(dir, record, listRecipes().find((r) => r.manifest.name === name)?.manifest.setup);
+								if (kept.length > 0) keptNote = `; kept ${kept.length} edited file(s): ${kept.join(", ")}`;
+							} else {
 								try {
 									fs.rmdirSync(dir);
 								} catch {
@@ -2226,7 +2247,10 @@ export default function piLoops(pi: ExtensionAPI) {
 							}
 						}
 						refreshBadge();
-						ctx.ui.notify(`removed recipe ${name}: ${jobs.length} job(s)${purge ? ", its files and notes" : `; files kept in ${homeRel(dir)}/`}`, "info");
+						ctx.ui.notify(
+							`removed recipe ${name}: ${jobs.length} job(s)${purge ? ", its files and notes" : `; files kept in ${homeRel(dir)}/`}${aborted > 0 ? `; aborted ${aborted} running run(s)` : ""}${keptNote}`,
+							"info",
+						);
 						return;
 					}
 					case "help":

package/src/recipe.ts

@@ -576,10 +576,12 @@ export function installFiles(recipe: Recipe, projectDir: string, level: Autonomy
 		fs.writeFileSync(origPath(targetDir, f), content);
 	}
 	if (recipe.manifest.setup) {
-		// The setup script is copied too, so what ran is what is there to read afterwards.
+		// The setup script is copied too, so what ran is what is there to read afterwards — and its
+		// untouched copy is kept the way a playbook's is, so `--purge` can tell an edit from the original.
 		const dest = path.join(targetDir, recipe.manifest.setup);
 		fs.mkdirSync(path.dirname(dest), { recursive: true });
 		fs.copyFileSync(path.join(recipe.dir, recipe.manifest.setup), dest);
+		fs.writeFileSync(origPath(targetDir, recipe.manifest.setup), fs.readFileSync(dest));
 	}
 	const record: InstallRecord = { recipe: recipe.manifest.name, version: VERSION, level, installedAt: stamp(), files, source: opts.source };
 	fs.writeFileSync(path.join(targetDir, RECORD_FILE), `${JSON.stringify(record, null, 2)}\n`);
@@ -610,13 +612,30 @@ export function requireRecipeName(name: string): string {
 }
 
 /**
- * `--purge`: only what the install wrote — the recorded files, their untouched copies, the setup
- * script and the record — then the directory if that emptied it. `.agents/skills/<name>/` may also
- * hold a project's own files, and those are not ours to delete.
+ * `--purge`: only what the install wrote — a recorded file or the setup script, and each only while
+ * it still matches its untouched copy, plus the untouched copies and the record — then the directory
+ * if that emptied it. A file the person edited, or one with no `.orig` to compare against, is kept
+ * and named. `.agents/skills/<name>/` may also hold a project's own files, and those are not ours to
+ * delete.
  */
-export function purgeInstall(targetDir: string, record: InstallRecord, setup?: string): void {
+export function purgeInstall(targetDir: string, record: InstallRecord, setup?: string): { removed: string[]; kept: string[] } {
+	const removed: string[] = [];
+	const kept: string[] = [];
 	for (const f of [...record.files, ...(setup ? [setup] : [])]) {
-		fs.rmSync(path.join(targetDir, f), { force: true });
+		const dest = path.join(targetDir, f);
+		if (!fs.existsSync(dest)) continue;
+		let untouched = false;
+		try {
+			untouched = fs.readFileSync(path.join(targetDir, ".orig", f)).equals(fs.readFileSync(dest));
+		} catch {
+			untouched = false; // no untouched copy: leave the file alone
+		}
+		if (untouched) {
+			fs.rmSync(dest, { force: true });
+			removed.push(f);
+		} else {
+			kept.push(f);
+		}
 	}
 	fs.rmSync(path.join(targetDir, ".orig"), { recursive: true, force: true });
 	fs.rmSync(path.join(targetDir, RECORD_FILE), { force: true });
@@ -634,6 +653,7 @@ export function purgeInstall(targetDir: string, record: InstallRecord, setup?: s
 	} catch {
 		// something else lives here; leave it
 	}
+	return { removed, kept };
 }
 
 /** Every recipe installed in a project: the directories under `.agents/skills/` that carry a record. */

package/src/scheduler.ts

@@ -33,6 +33,12 @@ export const FAILURE_BACKOFF_MAX_MS = 6 * 60 * 60_000;
 export const FOREIGN_RUN_STALE_MS = 24 * 60 * 60 * 1000;
 export const DEFAULT_RUN_TIMEOUT_MS = 15 * 60_000;
 export const MAX_CONCURRENT_RUNS = 3;
+/**
+ * How long `removeJob` waits for an aborted run to write its record before removing the job anyway.
+ * Two seconds is enough: the drain exists to let a normal abort write its record first, not to
+ * outlast a wedged sub-agent — the job is removed regardless, and `runOnce` discards its state.
+ */
+export const REMOVE_DRAIN_MS = 2_000;
 
 export interface SessionSnapshot {
 	sessionId?: string;
@@ -69,6 +75,8 @@ export interface SchedulerHooks {
 	/** A run is being fired for a tick that was missed while no pi was open. */
 	onCatchUp?: (job: LoopJob, dueAt: number) => void;
 	onRunFinished?: (outcome: RunOutcome) => void;
+	/** A one-shot removed itself: the control plane records it the way a person's removal is recorded. */
+	onJobRetired?: (job: LoopJob, reason: string) => void;
 	onInboxChanged?: () => void;
 	/** Every tick, after leadership is settled. Other subsystems (dynamic triggers) piggyback on it. */
 	onTick?: (now: number, leader: boolean) => void | Promise<void>;
@@ -172,12 +180,14 @@ export class LoopScheduler {
 		this.dir = opts.dir;
 		this.store = new JobStore(opts.dir);
 		this.inbox = new Inbox(opts.dir);
-		// One leader per host: machines sharing a $HOME must not elect each other.
+		// One leader at a time, for the machine: every process here elects through this one file. Two
+		// machines sharing a $HOME contend for it and both end up running every job, which is not
+		// supported (docs/design.md §19).
 		this.leaderFile = path.join(opts.dir, "scheduler.json");
-		// Per host, like the leader record beside it, and for the same reason. Leadership is per
-		// host; two machines sharing a `$HOME` are both leaders, and a cron expression is matched
-		// against local time — so one file would be two machines writing different answers over each
-		// other, and a panel showing whichever wrote last.
+		// One plain file beside the leader record. A cron expression is matched against local time, so
+		// if two machines sharing a `$HOME` both ran, they would write different answers over one
+		// another and the panel would show whichever wrote last — which is why that arrangement is
+		// unsupported rather than handled (docs/design.md §19).
 		this.nextRunsFile = path.join(opts.dir, "next-runs.json");
 		this.leaderLock = path.join(opts.dir, "scheduler.lock");
 		this.getSession = opts.getSession;
@@ -226,6 +236,26 @@ export class LoopScheduler {
 		return true;
 	}
 
+	/**
+	 * Remove a job. A run of it that is in flight is aborted first and given up to
+	 * REMOVE_DRAIN_MS to write its record, so the removal does not race the run's end.
+	 * Returns the removed job (undefined when there was none) and how many runs were aborted.
+	 */
+	async removeJob(id: string, opts: { purge?: boolean } = {}): Promise<{ job: LoopJob | undefined; aborted: number }> {
+		const runIds = [...this.inflight.entries()].filter(([, r]) => r.jobId === id).map(([runId]) => runId);
+		for (const runId of runIds) this.inflight.get(runId)?.ctrl.abort();
+		// The wall clock, not `this.now()`: this is a real wait, and a test that moved its injected
+		// clock must not be able to hold the removal open for ever.
+		const deadline = Date.now() + REMOVE_DRAIN_MS;
+		while (runIds.some((runId) => this.inflight.has(runId)) && Date.now() < deadline) {
+			await new Promise((r) => setTimeout(r, 25));
+		}
+		// If a run is still there past the drain the job is removed anyway; `runOnce` re-reads the
+		// store before it writes anything, so a late run leaves nothing behind.
+		const job = await this.store.remove(id, opts);
+		return { job, aborted: runIds.length };
+	}
+
 	/** Idempotent. Starts the tick timer and takes leadership if free. */
 	start(): void {
 		if (this.timer) return;
@@ -500,9 +530,13 @@ export class LoopScheduler {
 		}
 	}
 
-	/** Remove the jobs `disableDeadSessionJobs` parked; returns them. */
+	/**
+	 * Remove the jobs `disableDeadSessionJobs` parked; returns them. These are plain jobs of deleted
+	 * sessions with nothing left to run, so gc says yes to `purge`: their leftover state and
+	 * transcripts go with them.
+	 */
 	async gc(inScope: (job: LoopJob) => boolean = () => true): Promise<LoopJob[]> {
-		return this.store.removeWhere((j) => inScope(j) && !j.enabled && !!j.lastError?.endsWith(DEAD_SESSION_MARKER));
+		return this.store.removeWhere((j) => inScope(j) && !j.enabled && !!j.lastError?.endsWith(DEAD_SESSION_MARKER), { purge: true });
 	}
 
 	/** Clear running markers left behind by processes that are gone. Mutates `jobs` in place. */
@@ -668,7 +702,14 @@ export class LoopScheduler {
 		// here, and the caller used to read it back out of the string this just formatted.
 		const runId = newId("run");
 		await this.hooks.onInject?.(job, `[Trigger ${runId}] ${job.prompt}${note}`, runId);
-		if (job.schedule.kind === "once") await this.store.remove(job.id);
+		if (job.schedule.kind === "once") {
+			await this.store.remove(job.id);
+			try {
+				this.hooks.onJobRetired?.(job, "one-shot fired");
+			} catch (err: any) {
+				this.log(`onJobRetired hook failed: ${err?.message ?? err}`);
+			}
+		}
 		return true;
 	}
 
@@ -811,10 +852,24 @@ export class LoopScheduler {
 		// make `clearStaleRunning` see "my pid, not in flight", clear the running marker, roll the
 		// schedule back and re-fire the same job while its checker is still working.
 
+		// The job may have been removed while the run was in flight — by `/cron remove` here, by the
+		// tool, or by another pi window. Its state and findings belong to a job that is gone, so they
+		// are discarded; the run record is still written below, because the run did happen.
+		// A store that cannot be read (a torn write, a file from a newer build) must not cost a run its
+		// record and its findings: the question here is only whether the job was removed, and the safe
+		// answer to "cannot tell" is no.
+		let stillThere = true;
+		try {
+			stillThere = this.store.load().some((j) => j.id === job.id);
+		} catch (err: any) {
+			this.log(`loop ${job.id}: could not read the store after the run (${err?.message ?? err}); keeping its state and findings`);
+		}
+		if (!stillThere) this.log(`loop ${job.id}: removed during the run; its state and findings are discarded`);
+
 		// Tag extraction never fails a run: malformed/missing tags leave the state untouched.
 		const parsed = parseRunOutput(result.text);
 		let stateUpdated = false;
-		if (result.ok && parsed.state !== undefined) {
+		if (stillThere && result.ok && parsed.state !== undefined) {
 			try {
 				this.store.writeState(job.id, parsed.state);
 				stateUpdated = true;
@@ -827,13 +882,13 @@ export class LoopScheduler {
 		// still enter the inbox, but marked unverified — a broken checker must not silence the loop.
 		let checker: CheckerRecord | undefined;
 		let reviewed: Array<{ text: string; verified?: boolean; reason?: string }> = parsed.findings.map((text) => ({ text }));
-		if (result.ok && job.verify && parsed.findings.length && !ctrl.signal.aborted) {
+		if (stillThere && result.ok && job.verify && parsed.findings.length && !ctrl.signal.aborted) {
 			const outcome = await this.runChecker(job, runId, parsed.state ?? previousState, parsed.findings, ctrl.signal, job.checkerModel ?? model, thinking);
 			checker = outcome.record;
 			reviewed = outcome.reviewed;
 		}
 		const findings: string[] = [];
-		if (result.ok) {
+		if (stillThere && result.ok) {
 			// cron:<name>, else cron:<id prefix> — "cron-" plus 8 hex, the width /inbox shows.
 			const source = `cron:${job.name ?? job.id.slice(0, "cron-".length + 8)}`;
 			for (const f of reviewed) {
@@ -882,20 +937,28 @@ export class LoopScheduler {
 		// slot it claimed is given back and the next tick re-fires it (a tick is never lost this
 		// way because its runs die with the session that owned them).
 		const aborted = !result.ok && (result.stopReason === "aborted" || ctrl.signal.aborted);
-		const updated = await this.store.update(job.id, (j) => {
-			if (j.running?.runId === runId) j.running = undefined;
-			j.lastCompletedAt = finishedAt;
-			j.lastError = result.ok ? undefined : record.error;
-			if (aborted) {
-				j.lastDueAt = prior.dueAt;
-				j.lastFiredAt = prior.firedAt;
-			} else {
-				j.runCount++;
-				// A job that fails every time costs money every time. Count the streak so `dispatch`
-				// can back off, and clear it the moment one run works.
-				j.consecutiveFailures = result.ok ? undefined : (j.consecutiveFailures ?? 0) + 1;
-			}
-		});
+		// The same unreadable store that was tolerated above must not cost the run its `onRunFinished`
+		// either: the record is already written, and the job's own bookkeeping is the one part that
+		// can be skipped when the file cannot be read.
+		let updated: LoopJob | undefined;
+		try {
+			updated = await this.store.update(job.id, (j) => {
+				if (j.running?.runId === runId) j.running = undefined;
+				j.lastCompletedAt = finishedAt;
+				j.lastError = result.ok ? undefined : record.error;
+				if (aborted) {
+					j.lastDueAt = prior.dueAt;
+					j.lastFiredAt = prior.firedAt;
+				} else {
+					j.runCount++;
+					// A job that fails every time costs money every time. Count the streak so `dispatch`
+					// can back off, and clear it the moment one run works.
+					j.consecutiveFailures = result.ok ? undefined : (j.consecutiveFailures ?? 0) + 1;
+				}
+			});
+		} catch (err: any) {
+			this.log(`loop ${job.id}: could not write the store after the run (${err?.message ?? err})`);
+		}
 		if (updated && !result.ok && (updated.consecutiveFailures ?? 0) >= FAILURE_BACKOFF_AFTER) {
 			this.hooks.onSchedulerError?.(`${updated.name ?? updated.id} has failed ${updated.consecutiveFailures} times in a row; backing off (last: ${record.error ?? "unknown"})`);
 		}
@@ -907,13 +970,20 @@ export class LoopScheduler {
 		// not for a job — and is then retired too, with the error kept in the run log and reported by
 		// `onRunFinished`. Anything else leaves a failed `in 10m` enabled forever with no next run.
 		if (updated && job.schedule.kind === "once" && !aborted) {
-			if (result.ok || updated.runCount >= 2) await this.store.remove(job.id);
-			else
+			if (result.ok || updated.runCount >= 2) {
+				await this.store.remove(job.id);
+				try {
+					this.hooks.onJobRetired?.(job, result.ok ? "one-shot finished" : "one-shot failed twice");
+				} catch (err: any) {
+					this.log(`onJobRetired hook failed: ${err?.message ?? err}`);
+				}
+			} else {
 				await this.store.update(job.id, (j) => {
 					j.lastDueAt = undefined;
 					j.lastFiredAt = undefined;
 					j.lastError = `${record.error ?? "run failed"} (one-shot: retrying once)`;
 				});
+			}
 		}
 
 		try {

package/src/store.ts

@@ -359,9 +359,14 @@ export class JobStore {
 		return this.mutate((jobs) => ({ jobs: [...jobs, job], result: job }));
 	}
 
-	/** Remove every job matching `pred` (state files and transcripts included); returns them. */
-	async removeWhere(pred: (job: LoopJob) => boolean): Promise<LoopJob[]> {
+	/**
+	 * Remove every job matching `pred`; returns them. Its state and transcripts are kept unless
+	 * `purge` is set — the caller decides, as with `remove` — because the usual way to change a job
+	 * is to remove it and add it again, and a stateful loop's notes are what it accumulated.
+	 */
+	async removeWhere(pred: (job: LoopJob) => boolean, opts: { purge?: boolean } = {}): Promise<LoopJob[]> {
 		const removed = await this.mutate((jobs) => ({ jobs: jobs.filter((j) => !pred(j)), result: jobs.filter(pred) }));
+		if (!opts.purge) return removed;
 		for (const job of removed) {
 			try {
 				fs.rmSync(this.statePath(job.id), { force: true });
@@ -405,17 +410,59 @@ export class JobStore {
 		}
 	}
 
-	/** Loop state left behind by removed jobs, so `/cron gc` can offer to clear it. */
+	/**
+	 * Loop state and transcripts left behind by removed jobs, so `/cron gc` can offer to clear both.
+	 * An id qualifies if a `state/<id>.md` or a `sessions/<id>/` directory is there and no job claims
+	 * it; `bytes` is the state file plus the whole transcript tree, since that is what `purgeState` deletes.
+	 */
 	orphanStates(): Array<{ id: string; bytes: number }> {
 		const live = new Set(this.load().map((j) => j.id));
+		const bytes = new Map<string, number>();
+		const add = (id: string, n: number) => {
+			if (!live.has(id)) bytes.set(id, (bytes.get(id) ?? 0) + n);
+		};
+		let states: string[] = [];
 		try {
-			return fs
-				.readdirSync(path.join(this.dir, "state"))
-				.filter((f) => f.endsWith(".md") && !live.has(f.slice(0, -3)))
-				.map((f) => ({ id: f.slice(0, -3), bytes: fs.statSync(path.join(this.dir, "state", f)).size }));
+			states = fs.readdirSync(this.stateDir);
 		} catch {
-			return [];
+			/* no state directory yet */
+		}
+		for (const f of states) {
+			if (!f.endsWith(".md")) continue;
+			let size = 0;
+			try {
+				size = fs.statSync(path.join(this.stateDir, f)).size;
+			} catch {
+				/* a file that vanished between the read and the stat counts 0 */
+			}
+			add(f.slice(0, -3), size);
+		}
+		let transcripts: fs.Dirent[] = [];
+		try {
+			transcripts = fs.readdirSync(this.sessionsDir, { withFileTypes: true });
+		} catch {
+			/* no transcript directory yet */
+		}
+		for (const e of transcripts) {
+			if (!e.isDirectory()) continue;
+			let size = 0;
+			try {
+				// The whole tree: `purgeState` deletes the directory recursively, so counting only the
+				// files directly under it understated what `/cron gc` is about to remove.
+				for (const f of fs.readdirSync(path.join(this.sessionsDir, e.name), { recursive: true, withFileTypes: true })) {
+					if (!f.isFile()) continue;
+					try {
+						size += fs.statSync(path.join(f.parentPath, f.name)).size;
+					} catch {
+						/* a file that vanished between the read and the stat counts 0 */
+					}
+				}
+			} catch {
+				size = 0; // an unreadable directory counts 0
+			}
+			add(e.name, size);
 		}
+		return [...bytes.entries()].map(([id, n]) => ({ id, bytes: n }));
 	}
 
 	/* ---------------------------------------------------- loop state */

package/src/tools.ts

@@ -416,15 +416,16 @@ export function automationTools(scope: ToolScope, host: ToolHost): ToolDefinitio
 			// free: it is what the user is shown before deciding.
 			const denied = await host.confirmTool(ctx, { label: `remove cron job ${label}`, tool: "cron_remove", reason: "remove a scheduled job", preview: `${formatSchedule(job.schedule)} · ${previewRedacted(job.prompt, 120)}`, args: params }, scope.hop);
 			if (denied) return { content: [{ type: "text", text: denied }], isError: true, details: { id: undefined as string | undefined, removed_count: 0, confirmation_required: false, audit_entry_id: undefined as string | undefined } };
-			await host.scheduler.store.remove(job.id);
+			const { aborted } = await host.scheduler.removeJob(job.id);
 			const auditEntryId = host.cronControlAudit("remove", scope.actor, job, undefined);
 			// The slash command says where a loop's notes went; a tool-driven removal has to say it too,
 			// or the person who asked the agent to delete a job is the only one left guessing. The prose
 			// carries the fact and `details` carries the path, which is the division this tool already
 			// uses elsewhere (`cron_list` reports `storage_path` the same way).
 			const kept = job.stateful ? "\nits loop state and run transcripts are kept; /cron gc --purge clears them" : "";
+			const abortedNote = aborted > 0 ? "\naborted its running run" : "";
 			const statePath = job.stateful ? host.scheduler.store.statePath(job.id) : undefined;
-			return { content: [{ type: "text", text: `removed cron job ${label}\nschedule: ${formatSchedule(job.schedule)}\naction: ${previewRedacted(job.prompt, 120)}${kept}` }], details: { id: job.id as string | undefined, removed_count: 1, confirmation_required: false, audit_entry_id: auditEntryId, state_path: statePath } };
+			return { content: [{ type: "text", text: `removed cron job ${label}\nschedule: ${formatSchedule(job.schedule)}\naction: ${previewRedacted(job.prompt, 120)}${kept}${abortedNote}` }], details: { id: job.id as string | undefined, removed_count: 1, confirmation_required: false, audit_entry_id: auditEntryId, state_path: statePath } };
 		},
 	});
 

package/src/web.mjs

@@ -464,9 +464,9 @@ function formatSchedule(s) {
  * Missing file, older pi-loops, no leader yet: no next run shown, which is what was shown before.
  */
 function nextRuns() {
-	// This machine's file. Leadership is per host, and so is the clock a cron expression is matched
-	// against, so on a shared `$HOME` each machine keeps its own answers rather than overwriting the
-	// other's with times computed in a different timezone.
+	// The scheduler's one file. If two machines shared a `$HOME` they would both run every job and
+	// overwrite one another's answers here; that is unsupported rather than handled
+	// (docs/design.md §19).
 	const doc = readJson(path.join(LOOPS_DIR, "next-runs.json"), { next: {} });
 	return doc?.next && typeof doc.next === "object" ? doc.next : {};
 }
@@ -3038,10 +3038,15 @@ function copyBtn(getText) {
  * they reported the drop three different ways, one of them not at all: a result that stopped at 8000
  * characters looked like a result that ended there. A cap that hides its own existence is a lie
  * about the output.
+ *
+ * Counted and cut in characters, which is what the message says and what capChars in src/protocol.ts
+ * and previewText in src/session-head.ts have always counted. String.length is code units, so an
+ * emoji is two of them: the count came out larger than what was shown, and a cut between the two
+ * halves of one left half a character, which a browser draws as a replacement glyph.
  */
 function capped(text, n) {
-  const s = String(text ?? "");
-  return s.length > n ? s.slice(0, n) + "\n… (" + s.length + " chars)" : s;
+  const chars = Array.from(String(text ?? ""));
+  return chars.length > n ? chars.slice(0, n).join("") + "\n… (" + chars.length + " chars)" : chars.join("");
 }
 
 /** Replace a row's plain text with its rendered Markdown, keeping the source for the copy button. */