@alphacoder-v0/pi-loops 0.22.3 → 0.22.5

package/src/pi-loops.ts

@@ -25,7 +25,7 @@ import { sameProject } from "./presence.ts";
 import { isExactlyTrusted, sessionTrustCovers } from "./trust.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 { 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 +38,8 @@ import { execFile } from "node:child_process";
 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 { jobLines as cronJobLines } from "./job-lines.ts";
+import { runsIn } from "./job-owner.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";
@@ -49,8 +50,8 @@ import { askHost, renderHostSnapshot } from "./host-control-channel.ts";
 import { waitForHost, HOST_LOG, crashedHost, hostPushWork, liveHost, piPackageDir, shouldHandOff, spawnHost, stopHost } from "./host-control.ts";
 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 { auditArgs, auditCronFinish, auditCronStart, TriggerStore, buildPeriodicCheckTrigger, controlPlanePreflight, resolveRuleRef } from "./triggers.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 +198,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 +655,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))];
@@ -721,41 +724,12 @@ 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)
-				? computeNext(
-						{
-							schedule: job.schedule,
-							createdAt: Date.parse(job.createdAt),
-							lastFiredAt: job.lastFiredAt ? Date.parse(job.lastFiredAt) : undefined,
-						},
-						now,
-					)
-				: undefined;
-			const asleepMark = asleepNote(job, session.sessionId);
-			const dormant = asleepMark ? `[${asleepMark}]` : undefined;
-			const orphan = job.stateful && !fs.existsSync(job.cwd) ? "[orphan: cwd missing]" : undefined;
-			// What the loop's runs came to (src/job-signal.ts): `quiet ×N` in the marks once N empty
-			// 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 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();
+		// project with a dozen loops would otherwise parse them a dozen times per `/cron`. The shape
+		// of the lines is src/job-lines.ts, where a test can see a marker go.
+		const runs = jobs.some((j) => j.stateful) ? scheduler.store.allRuns() : [];
+		const inbox = jobs.some((j) => j.stateful) ? scheduler.inbox.list() : [];
+		return cronJobLines(jobs, { runs, inbox, sessionId: session.sessionId, now: Date.now(), home: process.env.HOME ?? "", cwdExists: (cwd) => fs.existsSync(cwd) });
 	}
 
 	/* --------------------------------------------------------- creation */
@@ -766,7 +740,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 +926,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 +1044,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;
@@ -1786,10 +1774,13 @@ export default function piLoops(pi: ExtensionAPI) {
 						return;
 					}
 					case "audit": {
-						const all = /\s--all\b|^--all\b/.test(rest);
-						const limit = Number.parseInt(rest.replace("--all", ""), 10) || 10;
+						const args = auditArgs(rest);
+						if ("usage" in args) {
+							ctx.ui.notify(args.usage, "warning");
+							return;
+						}
 						// This project's rows by default (rows without a cwd predate 0.1.3 and are shown too).
-						const rows = store.listAudit(limit, all ? undefined : (r) => !r.cwd || sameProject(r.cwd, session.cwd));
+						const rows = store.listAudit(args.limit, args.all ? undefined : (r) => !r.cwd || sameProject(r.cwd, session.cwd));
 						show(
 							ctx,
 							rows.length ? `Recent trigger audit (${rows.length}):` : "(no trigger audit entries)",
@@ -2205,19 +2196,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 +2222,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/session-head.ts

@@ -27,11 +27,15 @@ const HEAD_BYTES = 64 * 1024;
 
 export function readSessionHead(file: string, bytes: number = HEAD_BYTES): SessionHead | undefined {
 	let text: string;
+	let readBytes = 0;
 	try {
 		const fd = fs.openSync(file, "r");
 		try {
 			const buf = Buffer.alloc(bytes);
-			text = buf.toString("utf8", 0, fs.readSync(fd, buf, 0, bytes, 0));
+			// `bytes` is a byte window, so the decision to cut is the byte count read, not the
+			// decoded string's length: a multi-byte character makes those differ.
+			readBytes = fs.readSync(fd, buf, 0, bytes, 0);
+			text = buf.toString("utf8", 0, readBytes);
 		} finally {
 			fs.closeSync(fd);
 		}
@@ -46,7 +50,7 @@ export function readSessionHead(file: string, bytes: number = HEAD_BYTES): Sessi
 		return undefined;
 	}
 	if (header?.type !== "session" || typeof header.id !== "string") return undefined;
-	const truncated = text.length >= bytes;
+	const truncated = readBytes >= bytes;
 	let name: string | undefined;
 	let first: string | undefined;
 	let messages = 0;

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/triggers.ts

@@ -406,6 +406,30 @@ export class TriggerStore {
 	}
 }
 
+export const AUDIT_USAGE = "usage: /triggers audit [N] [--all]   (N is the number of rows, default 10)";
+
+/**
+ * `/triggers audit [N] [--all]`, parsed where it can be tested: `src/pi-loops.ts` is the extension's
+ * default export, so nothing can import the handler. A limit the command cannot read is refused
+ * rather than silently replaced with the default, and a negative one is refused rather than handed
+ * to `listAudit`, where `slice(-limit)` stops meaning "limit" and prints the file from the top.
+ * `--all` lifts the project filter and may sit before or after the number.
+ */
+export function auditArgs(rest: string): { limit: number; all: boolean } | { usage: string } {
+	let limit = 10;
+	let all = false;
+	let numbered = false;
+	for (const part of rest.split(/\s+/).filter(Boolean)) {
+		if (part === "--all") all = true;
+		else if (!numbered && /^\d+$/.test(part)) {
+			limit = Number(part);
+			numbered = true;
+		} else return { usage: AUDIT_USAGE };
+	}
+	if (limit < 1) return { usage: AUDIT_USAGE };
+	return { limit, all };
+}
+
 /**
  * The control-plane prompt gate, pre-flight part. Prompt-class tool calls (create or remove
  * a trigger, re-enable a trigger or a cron job) need a human. Sub-agents have no prompt channel