@alphacoder-v0/pi-loops 0.22.7 → 0.24.0

package/src/seen.ts

@@ -0,0 +1,278 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { withFileLockSync, writeFileAtomic } from "./lock.ts";
+import { Inbox, type InboxEntry } from "./inbox.ts";
+import { stamp } from "./schedule.ts";
+import { JobStore, type RunRecord } from "./store.ts";
+import { realpathish, sameProject } from "./paths.ts";
+
+/**
+ * When `/inbox` was last looked at, per project: the terminal's `/inbox`, and the page's Mark all
+ * seen. `"*"` is `/inbox --all`, which looks at every project. `sessions` holds the per-conversation
+ * cursors a v1 file had: read when folding, never written to, and pruned by the sweep.
+ */
+export interface SeenFile {
+	v: 2;
+	projects: Record<string, string>;
+	sessions: Record<string, string>;
+}
+
+/** The key `/inbox --all` marks: it looked at every project. */
+export const ALL_PROJECTS = "*";
+/** With no cursor (nobody looked yet, or an upgrade from a version without one), what is counted. */
+export const FIRST_WINDOW_MS = 24 * 60 * 60 * 1000;
+/** A cursor this far ahead of the clock is a clock that moved, not a look: it counts as none. */
+export const SKEW_MS = 5 * 60 * 1000;
+
+const fileIn = (dir: string): string => path.join(dir, "seen.json");
+const lockIn = (dir: string): string => path.join(dir, "seen.lock");
+const empty = (): SeenFile => ({ v: 2, projects: {}, sessions: {} });
+
+function stringsOf(value: unknown): Record<string, string> {
+	const out: Record<string, string> = {};
+	if (!value || typeof value !== "object" || Array.isArray(value)) return out;
+	for (const [k, at] of Object.entries(value)) if (typeof at === "string" && Number.isFinite(Date.parse(at))) out[k] = at;
+	return out;
+}
+
+/** The file as v2: a v1 file's per-conversation cursors become `sessions`; anything else is empty. */
+export function readSeen(dir: string): SeenFile {
+	let value: any;
+	try {
+		value = JSON.parse(fs.readFileSync(fileIn(dir), "utf8"));
+	} catch {
+		return empty(); // not written yet, or torn: the first window, never a flood
+	}
+	if (!value || typeof value !== "object") return empty();
+	if (value.v === 1) return { v: 2, projects: {}, sessions: stringsOf(value.seen) };
+	if (value.v === 2) return { v: 2, projects: stringsOf(value.projects), sessions: stringsOf(value.sessions) };
+	return empty();
+}
+
+const write = (dir: string, seen: SeenFile) => writeFileAtomic(fileIn(dir), `${JSON.stringify(seen, null, 2)}\n`);
+const later = (a: string | undefined, b: string) => (a !== undefined && Date.parse(a) >= Date.parse(b) ? a : b);
+
+/**
+ * Record a look at `cwd`'s project (or every project, `"*"`) at `at`. A cursor only moves forward,
+ * so two writers end in the same state whatever their order; `at` is never later than `now`, and a
+ * stored cursor in the future (a clock that moved) is replaced. Returns what is stored.
+ */
+export function markProjectSeen(dir: string, cwd: string, at: string, now = Date.now()): string {
+	const key = cwd === ALL_PROJECTS ? cwd : realpathish(cwd) || cwd;
+	const capped = Date.parse(at) > now ? stamp(now) : at;
+	return withFileLockSync(lockIn(dir), () => {
+		const seen = readSeen(dir);
+		const prev = seen.projects[key];
+		const stored = later(prev !== undefined && Date.parse(prev) <= now + SKEW_MS ? prev : undefined, capped);
+		if (stored !== prev) {
+			seen.projects[key] = stored;
+			write(dir, seen);
+		}
+		return stored;
+	});
+}
+
+/**
+ * The sweep: forget v1 cursors of conversations nothing refers to any more, and project cursors
+ * whose directory is gone. Returns how many were forgotten.
+ */
+export function pruneSeen(dir: string, keepSession: (sessionId: string) => boolean, exists: (p: string) => boolean = fs.existsSync): number {
+	return withFileLockSync(lockIn(dir), () => {
+		const seen = readSeen(dir);
+		const sessions = Object.keys(seen.sessions).filter((id) => !keepSession(id));
+		const projects = Object.keys(seen.projects).filter((k) => k !== ALL_PROJECTS && !exists(k));
+		if (!sessions.length && !projects.length) return 0;
+		for (const id of sessions) delete seen.sessions[id];
+		for (const k of projects) delete seen.projects[k];
+		write(dir, seen);
+		return sessions.length + projects.length;
+	});
+}
+
+/** Where "since" starts for a project; `looked: false` is the first window. */
+export interface Cursor {
+	sinceMs: number;
+	looked: boolean;
+}
+
+/**
+ * The latest look at `cwd`'s project: every project key `inProject` matches (a project's
+ * subdirectory is a key of its own), `"*"`, and the v1 cursor of every conversation whose records
+ * are in the project. A cursor in the future is ignored; none at all is the first window.
+ */
+export function cursorFor(seen: SeenFile, cwd: string, ctx: { inProject: (entryCwd: string, cwd: string) => boolean; sessionsHere: ReadonlySet<string>; now: number }): Cursor {
+	const times: string[] = [];
+	for (const [k, at] of Object.entries(seen.projects)) if (k === ALL_PROJECTS || ctx.inProject(k, cwd)) times.push(at);
+	for (const [id, at] of Object.entries(seen.sessions)) if (ctx.sessionsHere.has(id)) times.push(at);
+	const valid = times.map((t) => Date.parse(t)).filter((ms) => Number.isFinite(ms) && ms <= ctx.now + SKEW_MS);
+	// A loop, not Math.max(...valid): a hand-made file with many keys would overflow the stack.
+	const latest = valid.reduce((a, b) => (b > a ? b : a), Number.NEGATIVE_INFINITY);
+	return valid.length ? { sinceMs: latest, looked: true } : { sinceMs: ctx.now - FIRST_WINDOW_MS, looked: false };
+}
+
+/**
+ * What happened in one project while nobody looked: the page's away card and the terminal's
+ * session-start line both say this (docs/loops.md).
+ */
+export interface AwaySummary {
+	cwd: string;
+	/** The cursor as an ISO time; null for the first window ("In the last day"). */
+	since: string | null;
+	/** When this was counted, the end of its window: what Mark all seen sends back. */
+	asOf: string;
+	runs: number;
+	failedRuns: number;
+	/** New findings, a rule check's once; `decisions` of them are checkpoints. */
+	findings: number;
+	decisions: number;
+	fromThisConversation: number;
+	costUsd: number;
+}
+
+export interface AwayInput {
+	seen: SeenFile;
+	runs: readonly RunRecord[];
+	findings: readonly InboxEntry[];
+	cwd: string;
+	sessionId?: string;
+	now: number;
+	inProject: (entryCwd: string, cwd: string) => boolean;
+}
+
+/** Whether a path is in `cwd`'s project, asked once per distinct path: matching resolves paths on disk. */
+function matcher(cwd: string, inProject: (entryCwd: string, cwd: string) => boolean): (entryCwd: unknown) => boolean {
+	const known = new Map<string, boolean>();
+	return (entryCwd) => {
+		if (typeof entryCwd !== "string") return false;
+		let yes = known.get(entryCwd);
+		if (yes === undefined) known.set(entryCwd, (yes = inProject(entryCwd, cwd)));
+		return yes;
+	};
+}
+
+/** The one function behind the away card and the session-start line. Pure: the caller reads the files. */
+export function awayFor(input: AwayInput): AwaySummary {
+	const here = matcher(input.cwd, input.inProject);
+	// A finding with no cwd is in every project, as `/inbox` lists it (inbox.ts belongsToProject).
+	const findingHere = (f: InboxEntry) => !f.cwd || here(f.cwd);
+	// Lines another process wrote: one that is not an object (`null`, a number) is no record.
+	const runs = input.runs.filter((r) => !!r && typeof r === "object");
+	const findings = input.findings.filter((f) => !!f && typeof f === "object");
+	// The v1 fold: a conversation's old cursor counts for the project its records are in.
+	const sessionsHere = new Set<string>();
+	if (Object.keys(input.seen.sessions).length) {
+		for (const r of runs) if (typeof r.forSession === "string" && here(r.cwd)) sessionsHere.add(r.forSession);
+		for (const f of findings) if (typeof f.session_id === "string" && f.cwd && here(f.cwd)) sessionsHere.add(f.session_id);
+	}
+	const cursor = cursorFor(input.seen, input.cwd, { inProject: input.inProject, sessionsHere, now: input.now });
+	// The window is (cursor, now]: Mark all seen sends `now` back as asOf, and the page refuses a time
+	// ahead of its clock, so a record stamped a little ahead is counted once its time has come.
+	const after = (at: unknown) => {
+		const ms = typeof at === "string" ? Date.parse(at) : NaN;
+		return ms > cursor.sinceMs && ms <= input.now;
+	};
+	let runCount = 0;
+	let failedRuns = 0;
+	let costUsd = 0;
+	for (const r of runs) {
+		if (!r.stateful || !here(r.cwd) || !after(r.finishedAt)) continue;
+		runCount++;
+		if (!r.ok && !r.aborted) failedRuns++;
+		costUsd += (typeof r.usage?.cost === "number" ? r.usage.cost : 0) + (typeof r.checker?.cost === "number" ? r.checker.cost : 0);
+	}
+	// A rule check files one finding per conversation it was for (src/trigger-runtime.ts): one result.
+	const groups = new Map<string, InboxEntry[]>();
+	for (const f of findings) {
+		if (f.status !== "new" || !findingHere(f) || !after(f.created_at)) continue;
+		const key = typeof f.source === "string" && f.source.startsWith("trigger:") && f.run_id ? `rule:${f.run_id}` : `id:${f.id}`;
+		groups.set(key, [...(groups.get(key) ?? []), f]);
+	}
+	const results = [...groups.values()];
+	return {
+		cwd: input.cwd,
+		since: cursor.looked ? stamp(cursor.sinceMs) : null,
+		asOf: stamp(input.now),
+		runs: runCount,
+		failedRuns,
+		findings: results.length,
+		decisions: results.filter((g) => g.some((f) => f.kind === "checkpoint")).length,
+		fromThisConversation: input.sessionId ? results.filter((g) => g.some((f) => f.session_id === input.sessionId)).length : 0,
+		costUsd: Math.round(costUsd * 100) / 100,
+	};
+}
+
+/**
+ * The summary from the loops directory's files: the whole run log (halved past 1 MB, so it is
+ * bounded), the inbox and `seen.json`. What the terminal's session-start line and the page's
+ * `GET /inbox` both call, so the two cannot count differently.
+ */
+export function awayIn(dir: string, cwd: string, sessionId?: string, now = Date.now()): AwaySummary {
+	return awayFor({ seen: readSeen(dir), runs: new JobStore(dir).allRuns(), findings: new Inbox(dir).list(), cwd, sessionId, now, inProject: sameProject });
+}
+
+const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
+const DAYS = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"];
+const pad = (n: number) => String(n).padStart(2, "0");
+
+/**
+ * When `sinceMs` was, said from `nowMs`, in local time: "09:14", "yesterday 23:10", "Mon 23:10",
+ * "Oct 28 23:10", "Oct 28 2025 23:10". Days are calendar dates, not 24-hour steps, so a night with
+ * a clock change is still one day. The page has a copy of this (src/web.mjs `sinceWords`).
+ */
+export function sinceWords(sinceMs: number, nowMs: number): string {
+	const a = new Date(sinceMs);
+	const b = new Date(nowMs);
+	const day = (d: Date) => Math.round(Date.UTC(d.getFullYear(), d.getMonth(), d.getDate()) / 86_400_000);
+	const days = day(b) - day(a);
+	const time = `${pad(a.getHours())}:${pad(a.getMinutes())}`;
+	if (days <= 0) return time;
+	if (days === 1) return `yesterday ${time}`;
+	if (days < 7) return `${DAYS[a.getDay()]} ${time}`;
+	const date = `${MONTHS[a.getMonth()]} ${a.getDate()}`;
+	return a.getFullYear() === b.getFullYear() ? `${date} ${time}` : `${date} ${a.getFullYear()} ${time}`;
+}
+
+const plural = (n: number, one: string, many = `${one}s`) => `${n} ${n === 1 ? one : many}`;
+
+/** How many findings came from this conversation, worth saying only when that is not all of them. */
+const fromHere = (s: AwaySummary): number => (s.fromThisConversation !== s.findings ? s.fromThisConversation : 0);
+
+/** Nothing to say: no run and no finding since the cursor. */
+export const awayEmpty = (s: AwaySummary): boolean => s.runs === 0 && s.findings === 0;
+
+/**
+ * The away card's sentence (the page draws it from its own copy, part by part, and
+ * test/web-page.test.ts holds the two to one sentence); runs are the
+ * activity strip's to count, so a card is about findings:
+ * "Since yesterday 23:10 · 3 findings, 1 from this conversation · 1 needs you · $0.41".
+ */
+export function awaySentence(s: AwaySummary): string | undefined {
+	if (!s.findings) return undefined;
+	const parts = [s.since === null ? "In the last day" : `Since ${sinceWords(Date.parse(s.since), Date.parse(s.asOf))}`];
+	if (s.findings) parts.push(`${plural(s.findings, "finding")}${fromHere(s) ? `, ${fromHere(s)} from this conversation` : ""}`);
+	if (s.decisions) parts.push(`${s.decisions} need${s.decisions === 1 ? "s" : ""} you`);
+	if (s.costUsd > 0) parts.push(`$${s.costUsd.toFixed(2)}`);
+	return parts.join(" · ");
+}
+
+/**
+ * The terminal's session-start line, from the same summary:
+ * "[inbox] since you last looked (yesterday 23:10): 41 loop runs (3 failed), 3 new findings (1 from this conversation) — /inbox".
+ */
+export function awayLine(s: AwaySummary): string | undefined {
+	if (awayEmpty(s)) return undefined;
+	const when = s.since === null ? "in the last day" : sinceWords(Date.parse(s.since), Date.parse(s.asOf));
+	const parts: string[] = [];
+	if (s.runs) parts.push(`${plural(s.runs, "loop run")}${s.failedRuns ? ` (${s.failedRuns} failed)` : ""}`);
+	if (s.findings) parts.push(`${plural(s.findings, "new finding")}${fromHere(s) ? ` (${fromHere(s)} from this conversation)` : ""}`);
+	return `[inbox] since you last looked (${when}): ${parts.join(", ")} — /inbox`;
+}
+
+/** The Background view's column for one conversation: its project's counts. */
+export interface SinceYouLooked {
+	runs: number;
+	failed: number;
+	findings: number;
+	mine: number;
+}
+export const sinceCounts = (s: AwaySummary): SinceYouLooked => ({ runs: s.runs, failed: s.failedRuns, findings: s.findings, mine: s.fromThisConversation });

package/src/session-head.ts

@@ -84,6 +84,27 @@ export function previewText(text: string, max = 80): string {
 	return chars.length > max ? `${chars.slice(0, max).join("")}…` : flat;
 }
 
+/** What tells a conversation apart from another started the same minute: its name, else the first thing said. */
+export function sessionTitle(file: string): string | undefined {
+	const head = readSessionHead(file);
+	const title = head?.name ?? head?.first;
+	return title ? previewText(title, 40) : undefined;
+}
+
+/**
+ * A conversation's short form on every surface: its id's first 13 characters (`01a1c183-7467`).
+ * The 12 hex digits hold a uuidv7's whole millisecond stamp, so two collide only when they start in
+ * the same millisecond; the first 8 collided about every 65 s. A prefix, so `--session` takes it.
+ */
+export function shortSessionId(sessionId: string): string {
+	return sessionId.slice(0, 13);
+}
+
+/** A conversation in a listing: its short form, and its title when one is known. */
+export function conversationLabel(sessionId: string, title?: string): string {
+	return title ? `${shortSessionId(sessionId)} "${title}"` : shortSessionId(sessionId);
+}
+
 /**
  * The automation badge of a session listing: the plain jobs bound to this session (`sessionId`)
  * and the jobs and rules it created. `2 cron, 1 trigger`; `automation off` when everything

package/src/share.ts

@@ -9,6 +9,7 @@
  * taken back, so the summary comes first and the confirmation after it.
  */
 import { redact } from "./redact.ts";
+import { plural } from "./job-lines.ts";
 import { stamp } from "./schedule.ts";
 
 export interface ShareMessage {
@@ -49,6 +50,15 @@ function contentText(content: unknown): string {
 	return "";
 }
 
+/**
+ * The messages a share carries: pi's own message entries of the context, and nothing an extension
+ * wrote beside them. A run card (`pi-loops:view`), a promoted rule result (`custom_message`) and the
+ * trigger audit (`custom`) are pi-loops' records of the conversation, not the conversation.
+ */
+export function shareableMessages(entries: ReadonlyArray<{ type?: string; message?: ShareMessage }>): ShareMessage[] {
+	return entries.flatMap((e) => (e.type === "message" && e.message ? [e.message] : []));
+}
+
 /**
  * Render the messages of a session as Markdown. Pure: the caller decides where it goes, which is
  * what makes the redaction counting testable without a session, a model or a network.
@@ -113,8 +123,8 @@ export function renderShare(messages: ShareMessage[], meta: { model?: string; se
  */
 export function shareSummary(rendered: RenderedShare, opts: { public: boolean }): string[] {
 	return [
-		`  ${rendered.messages} message(s), ${rendered.toolResults} tool result(s), ${(rendered.bytes / 1024).toFixed(1)} KB`,
-		`  ${rendered.redactions} secret(s) masked — the redactor knows common shapes, not every shape`,
+		`  ${plural(rendered.messages, "message")}, ${plural(rendered.toolResults, "tool result")}, ${(rendered.bytes / 1024).toFixed(1)} KB`,
+		`  ${plural(rendered.redactions, "secret")} masked — the redactor knows common shapes, not every shape`,
 		opts.public ? "  visibility: PUBLIC — anyone can find it" : "  visibility: secret gist — unlisted, but anyone with the link can read it",
 		"  it contains every file the agent read and every command it ran in this session",
 	];

package/src/snapshot.ts

@@ -11,7 +11,7 @@ export const SNAPSHOT_MIN_GAP_MS = 60_000;
 
 /**
  * What counts as a change worth an entry: which servers are connected and what they exposed, who
- * owns the clock, the tools, the hooks, how many jobs and rules there are. Deliberately not the
+ * the host runs, the tools, the hooks, how many jobs and rules there are. Deliberately not the
  * counters — a server pushing every ten seconds moves `queued` constantly, and writing the session
  * file four times a minute to record that is not observability, it is noise. The counters are still
  * in the entry; they just do not trigger one, and `/cron snapshot` forces a fresh entry whenever a
@@ -19,7 +19,8 @@ export const SNAPSHOT_MIN_GAP_MS = 60_000;
  */
 export function snapshotFingerprint(data: any): string {
 	return JSON.stringify({
-		scheduler: { running: data.scheduler?.running, leader: data.scheduler?.leader },
+		scheduler: { running: data.scheduler?.running, host: data.scheduler?.host?.running },
+		paused: data.paused,
 		counts: data.counts,
 		mcp: (data.mcp ?? []).map((m: any) => ({ name: m.name, state: m.state, tools: m.tools, attention: m.attention, lastError: m.lastError })),
 		mcpConfigError: data.mcpConfigError,

package/src/store.ts

@@ -7,7 +7,8 @@
  *   state/<job-id>.md    loop state — the "state spine", human-readable
  *   inbox.jsonl          the triage inbox (see inbox.ts)
  *   runs.jsonl           run log, bounded
- *   scheduler.json         which process on this machine currently owns the timer
+ *   scheduler.json         the host's fence for pi-loops 0.22 windows, during an upgrade only
+ *   leases/, requests/     which process holds a conversation, and what is queued for it (lease.ts, requests.ts)
  *   *.lock               mkdir locks
  */
 import * as fs from "node:fs";
@@ -41,18 +42,29 @@ export interface LoopJob {
 	model?: string;
 	thinking?: string;
 	tools?: string[];
+	/**
+	 * The built-in tools (read, bash, edit, …) of the chat it was made in, when no `tools` were given:
+	 * it runs in the background, which has no `--tools` of its own, and must not get more than that chat.
+	 */
+	builtinTools?: string[];
 	enabled: boolean;
 	/** Maker/checker: a second sub-agent reviews findings before they enter the inbox. */
 	verify?: boolean;
 	/** "provider/model-id" for the checker; undefined → same as the maker. */
 	checkerModel?: string;
-	/** Fire once on startup if a tick was missed while no pi was running (default true). */
+	/** Fire once when its scheduler starts if a tick was missed while it was not running (default true). */
 	catchUp: boolean;
 	timeoutMs?: number;
 	/** The recipe that created this job (`/recipe add`), so `/recipe list|remove` can find it. */
 	recipe?: string;
 	createdAt: string;
 	createdBy?: { sessionId?: string; cwd: string };
+	/**
+	 * `"project"`: the loop belongs to its project, not a conversation (made where no saved
+	 * conversation was, recipe.ts installScope), and has no `createdBy`. A job with neither is from
+	 * before `createdBy` existed.
+	 */
+	owner?: "project";
 	/** non-stateful jobs only: the session that receives the message. */
 	sessionId?: string;
 	lastDueAt?: string;
@@ -64,6 +76,19 @@ export interface LoopJob {
 	skippedOverlap: number;
 	/** Failures in a row. Cleared by a success; drives the backoff in the scheduler. */
 	consecutiveFailures?: number;
+	/**
+	 * A slot handed back unrun: the host's turn in a closed conversation was taken back by a window,
+	 * or stopped by the host itself (a stop, an upgrade, the budget), or its process died before a
+	 * record was written. The next dispatch runs it at once instead of calling it missed — the
+	 * catch-up rule is for slots nobody tried, and this one was tried. Cleared by the next claim.
+	 */
+	owedSlot?: string;
+	/**
+	 * Runs in a row that started and never finished: the process running them died mid-run. Three
+	 * park the job (disabled, with why) rather than letting one that takes its process down with it
+	 * do so on every start. Cleared by a run that finishes, and by enabling the job again.
+	 */
+	interruptions?: number;
 	/**
 	 * When this job's `cwd` was first found missing, if it still is.
 	 *
@@ -75,6 +100,16 @@ export interface LoopJob {
 	 * next write, and the only consequence is that the grace period starts again.
 	 */
 	cwdMissingSince?: string;
+	/**
+	 * The page's suggestion for this loop that a person answered with Keep (src/job-tune.ts): the
+	 * same one is not offered again. Its key names the schedule, so a schedule change makes a new one.
+	 */
+	tuneKept?: string;
+}
+
+/** Who asked for a run by hand: the conversation the request came from. */
+export interface RunRequester {
+	sessionId: string;
 }
 
 export interface RunRecord {
@@ -105,6 +140,27 @@ export interface RunRecord {
 	sessionFile?: string;
 	/** Present when the job has verify=true and the maker reported findings. */
 	checker?: CheckerRecord;
+	/** The session that created this run's job (job.createdBy.sessionId), so its results can be counted for that conversation. */
+	forSession?: string;
+	/**
+	 * Which run of its loop this was: the job's `runCount + 1` when the record was written. A stopped
+	 * run does not raise `runCount`, so the run after it has the same ordinal. Absent on a record
+	 * written before 0.24, and on a plain job's turn. The run log is halved as it grows, so counting
+	 * records cannot tell run 3 from run 300.
+	 */
+	ordinal?: number;
+	/**
+	 * The conversation a person asked for this run from (`/cron run`, the page's run button). Its card
+	 * goes there, whatever the run's number. Absent on a scheduled run and on a record written before
+	 * 0.24.0 had it.
+	 */
+	requestedBy?: RunRequester;
+	/** The run was stopped (a person, a quit, a restart), not failed: it gets no card and is no failure. */
+	aborted?: true;
+	/** Set beside `aborted` when a person stopped it (the page's Stop, `pi-loops abort`, `/triggers abort`), which `aborted` alone cannot tell from a quit. */
+	stoppedBy?: "person";
+	/** Where that person stopped it: the browser page, or a terminal (`pi-loops abort`, `/triggers abort`). */
+	stoppedFrom?: "page" | "cli";
 }
 
 export interface CheckerRecord {
@@ -124,10 +180,20 @@ export interface CheckerRecord {
 
 /** Transcripts kept per loop; older ones are deleted when a run completes. */
 export const SESSIONS_KEPT_PER_JOB = 20;
+export const PINNED_TRANSCRIPTS_MAX = 100;
 
 /** Past this the run log is halved (docs/configuration.md). */
 export const RUNS_ROTATE_BYTES = 1_000_000;
 
+/**
+ * The loops directory pi-loops uses when nobody moved it: `loops` under pi's agent directory, even
+ * when `PI_LOOPS_DIR` points elsewhere. Only that one gets the host's fixed page port and a login
+ * unit; a moved directory is a test run or a second setup.
+ */
+export function homeLoopsDir(agentDir: string): string {
+	return path.join(agentDir, "loops");
+}
+
 export function defaultLoopsDir(agentDir?: string): string {
 	if (process.env.PI_LOOPS_DIR) return process.env.PI_LOOPS_DIR;
 	const base = agentDir ?? process.env.PI_CODING_AGENT_DIR ?? path.join(os.homedir(), ".pi", "agent");
@@ -192,7 +258,7 @@ function sessionIdOf(file: string): string | undefined {
 	try {
 		// A regular file, checked before it is opened. Anything else in this directory is not a
 		// session — and a fifo named like one never returns from `openSync`, which would hang the
-		// scan this is called from, on the leader's tick, for ever.
+		// scan this is called from, on the scheduler's tick, for ever.
 		if (!fs.statSync(file).isFile()) return undefined;
 		const fd = fs.openSync(file, "r");
 		try {
@@ -261,16 +327,18 @@ export class JobStore {
 		return dir;
 	}
 
-	/** Keep only the newest `keep` transcripts of a job. Best effort. */
-	pruneSessions(jobId: string, keep = SESSIONS_KEPT_PER_JOB): void {
+	/** Keep the newest `keep` transcripts and up to `PINNED_TRANSCRIPTS_MAX` pinned files. Best effort. */
+	pruneSessions(jobId: string, keep = SESSIONS_KEPT_PER_JOB, pinned?: ReadonlySet<string>): void {
 		const dir = path.join(this.sessionsDir, jobId);
 		try {
 			const files = fs
 				.readdirSync(dir)
 				.filter((f) => f.endsWith(".jsonl"))
-				.map((f) => ({ f, mtime: fs.statSync(path.join(dir, f)).mtimeMs }))
+				.map((f) => ({ file: path.join(dir, f), mtime: fs.statSync(path.join(dir, f)).mtimeMs }))
 				.sort((a, b) => b.mtime - a.mtime);
-			for (const { f } of files.slice(keep)) fs.rmSync(path.join(dir, f), { force: true });
+			const protectedFiles = new Set(files.filter(({ file }) => pinned?.has(path.resolve(file))).slice(0, PINNED_TRANSCRIPTS_MAX).map(({ file }) => file));
+			const newest = new Set(files.slice(0, keep).map(({ file }) => file));
+			for (const { file } of files) if (!protectedFiles.has(file) && !newest.has(file)) fs.rmSync(file, { force: true });
 		} catch {
 			/* nothing to prune */
 		}
@@ -296,7 +364,12 @@ export class JobStore {
 		// An existing but empty file is damage (a torn write, an external truncation), not "no jobs".
 		// Returning [] here would let the next tick's write erase every job with no error anywhere.
 		if (!text.trim()) throw new Error(`${this.jobsFile} is empty; restore it from ${this.jobsFile}.bak or delete it to start over`);
-		const parsed = JSON.parse(text) as JobsFile;
+		let parsed: JobsFile;
+		try {
+			parsed = JSON.parse(text) as JobsFile;
+		} catch (err: any) {
+			throw new Error(`${this.jobsFile}: ${err?.message ?? err}`);
+		}
 		// A file stamped by a newer pi-loops may carry fields this build does not know and would
 		// drop on its next write. Refuse it instead: two versions sharing a $HOME must not silently
 		// downgrade each other's jobs.