@alphacoder-v0/pi-loops 0.22.7 → 0.24.0

package/src/window-executor.ts

@@ -0,0 +1,459 @@
+/**
+ * The engine's executor in a window: the pi this extension runs in, holding its conversation's
+ * lease. An `append` row goes into the chat through `pi.sendMessage`: inserted at once while idle,
+ * with no turn; as a follow-up during a turn, which runs one when the current one ends
+ * (docs/design.md decision 9). A `turn` row goes through `pi.sendUserMessage`, and only while pi is
+ * idle (the engine decides that), so Esc has nothing of ours to drop. `handedOver` remembers what
+ * pi was given and has not written yet, so a second drain does not hand it over twice; `settled()`
+ * forgets what pi dropped (Esc clears its queues), so the next drain offers it again.
+ */
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { CEILING, type ConversationView, type Executor, type ExecutorView, type Producer, carriesPrefix, conversationView, landed, modeOf, personTextMatches, queuedTriggeredTurn, requestFingerprint, sameProducer } from "./engine.ts";
+import { type LeaseBinding, type ProcessProbe, systemProbe } from "./lease.ts";
+import type { ImageContent, RequestMode, SessionRequest } from "./requests.ts";
+import { stamp } from "./schedule.ts";
+
+/**
+ * Once pi has settled, a row it was handed and never wrote was dropped: Esc clears pi's queues, a
+ * follow-up with them. Forget those, so the next drain offers them again instead of waiting for
+ * them for as long as the window lives. Returns the ids forgotten.
+ */
+export function forgetDropped(handedOver: Set<string>, alreadyDelivered: (id: string) => boolean): string[] {
+	const dropped = [...handedOver].filter((id) => !alreadyDelivered(id));
+	for (const id of dropped) handedOver.delete(id);
+	return dropped;
+}
+
+/**
+ * Whose turn the agent is in, and under what cap (design §4.4, §6.3): a pi-loops row, with the mode
+ * and the declared tools its turn runs under, or a message the person typed or queued, which is
+ * theirs and capped by nothing of ours. Known from the user message that starts the turn, and in
+ * force until the turn settles: pi's retries and follow-ups start runs with no user message, and a
+ * cap that ended with the run would end at the first provider error. A message the person queues
+ * into a scheduled run makes what follows theirs.
+ */
+export type CurrentTurn = { kind: "row"; id: string; mode: RequestMode; tools?: readonly string[]; builtinTools?: readonly string[] } | { kind: "person" };
+
+/** Whether a call made now is a scheduled turn's, which the window caps (`src/window-guard.ts`). */
+export function unattendedTurn(current: CurrentTurn | undefined): current is CurrentTurn & { kind: "row" } {
+	return current?.kind === "row" && current.mode === "unattended";
+}
+
+/** The `[Trigger <id>] ` id a message starts with, when it does. */
+export function triggerIdOf(message: unknown): string | undefined {
+	const value = message as { role?: unknown; content?: unknown } | undefined;
+	if (!value || value.role !== "user") return undefined;
+	const content = value.content;
+	const text = typeof content === "string" ? content : Array.isArray(content) ? (content.find((part) => part?.type === "text") as { text?: string } | undefined)?.text : undefined;
+	const match = text?.match(/^\[Trigger ([^\]]+)\] /);
+	return match?.[1];
+}
+
+/**
+ * The system line when a triggered turn starts (or is queued behind the current one). The id is a
+ * rule's trace for a trigger and a run id for a plain job, which has no trace; the line calls it a
+ * trace either way, because that is the word people have learned to look for.
+ */
+export function triggeredTurnLine(ctx: Pick<ExtensionContext, "hasUI" | "ui"> | undefined, runId: string, idle: boolean): void {
+	if (!ctx?.hasUI) return;
+	ctx.ui.notify(idle ? `running triggered turn (trace ${runId.slice(0, 8)})` : queuedTriggeredTurn(runId), "info");
+}
+
+/**
+ * Whether the process that wrote a row is still that process, on that conversation, by the rule a
+ * lease holder is judged by (src/lease.ts holderAlive): the pid lives; a known start time that
+ * differs is a reused pid; with either start time unknown, a row older than this boot is a
+ * previous boot's. A producer that left the conversation said so in `created_by.left`.
+ */
+export function producerAlive(row: Pick<SessionRequest, "created_by" | "created_at">, probe: ProcessProbe = systemProbe): boolean {
+	const by = row.created_by;
+	if (by.left !== undefined || !probe.alive(by.pid)) return false;
+	const start = probe.startTime(by.pid);
+	if (by.procStart !== undefined && start !== undefined && start !== by.procStart) return false;
+	if ((by.procStart === undefined || start === undefined) && Date.parse(row.created_at) < probe.bootedAt() - 60_000) return false;
+	return true;
+}
+
+/**
+ * Which turn rows announce themselves with that line: the ones that arrive out of the clock or a
+ * server, which the person did not ask for just now. A claim, a recipe hand-off, `/new-trigger` and a
+ * goal continuation keep the notices they print themselves.
+ */
+export function showsTriggeredTurnLine(source: SessionRequest["source"]): boolean {
+	return source.startsWith("cron:") || source.startsWith("cron-run:") || source.startsWith("push:");
+}
+
+type WindowCtx = Pick<ExtensionContext, "isIdle" | "mode" | "sessionManager" | "hasUI" | "ui" | "abort">;
+
+/** What the executor asks the lease binding: the session bound and whether it is held, and whether another process holding it delivers person rows. */
+type WindowBinding = Pick<LeaseBinding, "here"> & Partial<Pick<LeaseBinding, "otherHolderDelivers">>;
+
+/** The default image reader: a window wired without one cannot send a row's images, and says so rather than sending the text without them. */
+const noImages = (row: SessionRequest): ImageContent[] => {
+	throw new Error(`request ${row.id} has images and this window has no way to read them`);
+};
+
+/** The text of a user message, as `landed` matches a person row against it. */
+function userTextOf(message: unknown): string | undefined {
+	const value = message as { role?: unknown; content?: unknown } | undefined;
+	if (!value || value.role !== "user") return undefined;
+	const content = value.content;
+	return typeof content === "string" ? content : Array.isArray(content) ? ((content.find((part) => part?.type === "text") as { text?: string } | undefined)?.text ?? "") : undefined;
+}
+
+export class WindowExecutor implements Executor {
+	private readonly pi: Pick<ExtensionAPI, "sendMessage" | "sendUserMessage">;
+	private readonly binding: WindowBinding;
+	private readonly ctx: () => WindowCtx | undefined;
+	/** Rows this process has handed pi and pi has not written yet. */
+	readonly handedOver = new Set<string>();
+	/** What the turn rows in `handedOver` run under, until each one's turn starts and takes it as `current`. */
+	private readonly caps = new Map<string, CurrentTurn & { kind: "row" }>();
+	/**
+	 * The text-proved rows in `handedOver` (a person's message, a claim, a recipe hand-off,
+	 * `/new-trigger`, a goal continuation), oldest first, with the text each one's user message will
+	 * carry: such a row has no `[Trigger]` prefix, so its turn is known by its text at `message_start`.
+	 */
+	private readonly personCaps: Array<{ cap: CurrentTurn & { kind: "row" }; text: string }> = [];
+	/**
+	 * Caps of person rows pi was judged to have refused, moved aside when the next person row is
+	 * handed over: a message that is one of these, sent late by pi, still runs under it. Claimed only
+	 * when no row handed over since matches, so "fix" cannot take the turn of "fix it and push".
+	 */
+	private readonly lateCaps: Array<{ cap: CurrentTurn & { kind: "row" }; text: string }> = [];
+	/** When each turn row in `handedOver` was handed to pi, while pi has started no run since (`ExecutorView.inFlightSince`). */
+	private readonly handedIdle = new Map<string, number>();
+	/** Rows pi was handed and had not written when it settled (`ExecutorView.dropped`), until the engine counts the attempt or hands them over again. */
+	private readonly dropped = new Set<string>();
+	/** The run pi is in, and the row it started from when a `[Trigger <id>]` message began it. */
+	private running: ExecutorView["running"];
+	/** The rows still in the request file: the cap of a turn this instance did not hand over itself, and the person rows a proof is matched among. */
+	private readonly rows: () => SessionRequest[];
+	/**
+	 * The rows this instance wrote (`produced`), by id, with what they said. An attended source is
+	 * trusted only on one of these, and only while the row in the file still says it: a row somebody
+	 * else wrote with `recipe:` or `inbox:` on it, or one of ours a capped turn rewrote in the file,
+	 * runs as unattended with no declared tools, so the person is asked before anything dangerous.
+	 */
+	private readonly producedRows = new Map<string, string>();
+	/** Whose turn pi is in now: set at a user `message_start`, cleared when the turn settles. */
+	private current: CurrentTurn | undefined;
+	/**
+	 * Submissions the person made (pi's `input` event) whose user message has not started yet. A user
+	 * message without a row of ours behind it is the person's only while one of these is pending;
+	 * otherwise it is another extension's, and the cap in force stays.
+	 */
+	private personPending = 0;
+	/**
+	 * Rows a stop named while pi held them unstarted: each is aborted at the `message_start` that
+	 * begins its turn. One pi dropped instead (Esc) moves to `stopped`, and the next drain removes it
+	 * as cancelled rather than offering it again: the stop was for that row.
+	 */
+	private readonly abortOnStart = new Set<string>();
+	private readonly stopped = new Set<string>();
+	/**
+	 * Rows whose turn started with a message that does not carry their prefix (another extension
+	 * rewrote it): they ran, so they are done, though the file will never prove it. Offered again they
+	 * would run a second time, which 0.22 never did.
+	 */
+	private readonly ranUnproved = new Set<string>();
+	private readonly self: Producer;
+	private readonly alive: (row: SessionRequest) => boolean;
+	/** The bytes of a person row's images (`RequestStore.images`): read as the row is handed over, not kept with the row. */
+	private readonly images: (row: SessionRequest) => ImageContent[];
+
+	constructor(pi: Pick<ExtensionAPI, "sendMessage" | "sendUserMessage">, binding: WindowBinding, ctx: () => WindowCtx | undefined, self: Producer, alive: (row: SessionRequest) => boolean = producerAlive, rows: () => SessionRequest[] = () => [], images: (row: SessionRequest) => ImageContent[] = noImages) {
+		this.rows = rows;
+		this.pi = pi;
+		this.binding = binding;
+		this.ctx = ctx;
+		this.self = self;
+		this.alive = alive;
+		this.images = images;
+	}
+
+	/**
+	 * This window holds `sessionId`, and is a place a result should land: a one-shot `pi -p` / json
+	 * run holds its conversation but would swallow a result into a turn that is about to exit, so the
+	 * background process appends it after, and a turn row waits for a window. The rows this process
+	 * produced itself (what the person typed here, its goal's continuations) are run here in any
+	 * mode, lease or not: `mine`, which `drain` asks beside this.
+	 */
+	holds(sessionId: string): boolean {
+		const here = this.binding.here();
+		const ctx = this.ctx();
+		return !!ctx && here.sessionId === sessionId && here.holds && (ctx.mode === "tui" || ctx.mode === "rpc");
+	}
+
+	entries(_sessionId: string): ConversationView {
+		const ctx = this.ctx();
+		return conversationView(() => ctx?.sessionManager.getEntries() ?? []);
+	}
+
+	/**
+	 * Whether row `id`'s delivery is in this conversation: by its prefix, or by its text since its
+	 * hand-over stamp (src/engine.ts `landed`), read off the row in the request file. A row gone from
+	 * the file is nobody's to wait for; what is left to ask is whether its prefix is in the conversation.
+	 */
+	delivered(id: string): boolean {
+		const row = this.rows().find((r) => r.id === id);
+		return row ? landed(row, this.entries("")) : this.entries("").has(id);
+	}
+
+	view(sessionId: string): ExecutorView {
+		// What pi has written is in the conversation, not in flight any more.
+		for (const id of [...this.handedOver]) {
+			if (!this.delivered(id)) continue;
+			this.handedOver.delete(id);
+			this.handedIdle.delete(id);
+		}
+		// A person row's cap lives as long as the row: one pi refused keeps it, since pi may yet run
+		// the send late (see `refused`); one gone from the file has nothing left to start.
+		const queued = new Set(this.rows().map((row) => row.id));
+		for (let at = this.personCaps.length - 1; at >= 0; at--) if (!queued.has(this.personCaps[at].cap.id) && !this.handedOver.has(this.personCaps[at].cap.id)) this.personCaps.splice(at, 1);
+		for (let at = this.lateCaps.length - 1; at >= 0; at--) if (!queued.has(this.lateCaps[at].cap.id)) this.lateCaps.splice(at, 1);
+		// What this window produced is remembered for as long as the row can still start a turn: a
+		// window open for weeks produces a row per slot, and the file is where the rows that matter are.
+		for (const id of [...this.producedRows.keys()]) if (!queued.has(id) && !this.handedOver.has(id)) this.producedRows.delete(id);
+		for (const id of [...this.dropped]) if (!queued.has(id)) this.dropped.delete(id);
+		for (const id of [...this.ranUnproved]) if (!queued.has(id)) this.ranUnproved.delete(id);
+		return {
+			kind: "window",
+			ceiling: CEILING.window,
+			admits: () => true,
+			idle: this.ctx()?.isIdle() ?? true,
+			running: this.running,
+			inFlight: this.handedOver,
+			stopped: this.stopped,
+			ran: this.ranUnproved,
+			inFlightSince: this.handedIdle,
+			dropped: this.dropped,
+			believed: (row) => this.producedRows.get(row.id) === requestFingerprint(row),
+			connected: () => true,
+			producerAlive: (row) => this.alive(row),
+			// A page's row this window was rung for is this window's as a local row is: the ring that
+			// makes it the person's also names the pi it was typed into.
+			mine: (row) => this.binding.here().sessionId === row.session_id && row.created_by.left === undefined && (sameProducer(row.created_by, this.self) || (row.source === "person" && this.producedRows.get(row.id) === requestFingerprint(row))),
+			holderDelivers: this.binding.otherHolderDelivers?.(),
+		};
+	}
+
+	/** A row this window just produced: remembered, so its source is believed when its turn starts. */
+	produced(row: SessionRequest): void {
+		this.producedRows.set(row.id, requestFingerprint(row));
+		// A ring that arrives after the hand-over (the page rang while pi was emitting agent_settled,
+		// and the drain in that handler went first): the row is the page's all the same, so its turn,
+		// started or not, runs under the cap the ring vouches for.
+		const pending = this.personCaps.find((p) => p.cap.id === row.id);
+		if (pending) pending.cap = this.capOf(row);
+		if (this.current?.kind === "row" && this.current.id === row.id) this.current = this.capOf(row);
+	}
+
+	/**
+	 * The cap a row's turn runs under here. The mode is recomputed from the source, never read from
+	 * the file; and an attended source is believed only on a row this instance wrote itself. Any other
+	 * attended row (one written into the file by hand, or by a capped turn; a local row the holder runs
+	 * once its producer left) runs as unattended with nothing declared: the danger check alone, which
+	 * asks the person in the window.
+	 */
+	private capOf(row: SessionRequest): CurrentTurn & { kind: "row" } {
+		const mode = modeOf(row.kind, row.source, row.wake);
+		if (mode === "attended" && this.producedRows.get(row.id) !== requestFingerprint(row)) return { kind: "row", id: row.id, mode: "unattended" };
+		return { kind: "row", id: row.id, mode, tools: row.payload?.tools, builtinTools: row.payload?.builtin_tools };
+	}
+
+	append(row: SessionRequest, wakeAgent: boolean): void {
+		const content = row.payload?.text ?? "";
+		if (wakeAgent) this.pi.sendMessage({ customType: "pi-loops:trigger", content, display: true }, { triggerTurn: true, deliverAs: "followUp" });
+		else this.pi.sendMessage({ customType: "pi-loops:trigger", content, display: true }, { triggerTurn: false });
+		this.handedOver.add(row.id);
+	}
+
+	/**
+	 * Handed over only while pi is idle, so `followUp` matters in one case: the person started a run
+	 * between the engine's idle check and this call, and pi then queues the row behind that run. A
+	 * row proved by its text (a person's message, a claim, a recipe hand-off, `/new-trigger`, a goal
+	 * continuation) goes in its own words, a person's images with it; its cap is taken by the next
+	 * user message with its text (`messageStarted`), there being no prefix to name it by. A person row
+	 * this window was not rung for (`produced`), one a terminal runs for a page or a forged one, is
+	 * capped as unattended by `capOf`, so the window asks before a dangerous command.
+	 */
+	turn(row: SessionRequest, now = Date.now()): void {
+		const text = row.payload?.text ?? "";
+		// Read before anything is handed over: images that cannot be read, or are not the row's, fail
+		// the hand-over (the engine records the error on the row) instead of sending the text alone.
+		const images = row.payload?.images?.length ? this.images(row) : undefined;
+		if (carriesPrefix(row.source)) {
+			this.pi.sendUserMessage(text, { deliverAs: "followUp" });
+			this.caps.set(row.id, this.capOf(row));
+		} else {
+			// A cap kept for a row pi refused (`refused`) ends here: a later text-proved row is handed
+			// over, and a message that starts with the refused row's words is more likely that one's.
+			for (let at = this.personCaps.length - 1; at >= 0; at--) if (!this.handedOver.has(this.personCaps[at].cap.id)) this.lateCaps.push(...this.personCaps.splice(at, 1));
+			this.pi.sendUserMessage(images?.length ? [{ type: "text", text }, ...images] : text, { deliverAs: "followUp" });
+			this.personCaps.push({ cap: this.capOf(row), text });
+		}
+		this.handedOver.add(row.id);
+		this.handedIdle.set(row.id, now);
+		this.dropped.delete(row.id);
+		if (showsTriggeredTurnLine(row.source)) triggeredTurnLine(this.ctx(), row.id, true);
+	}
+
+	/** Whose turn pi is in now, for the `tool_call` cap: a row's, the person's, or none. */
+	currentTurn(): CurrentTurn | undefined {
+		return this.current;
+	}
+
+	/** pi's own abort, as Esc is: it stops the current turn and nothing else; what is queued runs once pi is idle. */
+	abort(): void {
+		this.ctx()?.abort();
+	}
+
+	abortWhenStarted(id: string): void {
+		this.abortOnStart.add(id);
+	}
+
+	/**
+	 * pi did not write the row (a `fail` action): not in flight any more, and the attempt is counted.
+	 * A person row's cap stays (`view` drops it with the row): a send pi runs late still runs under
+	 * it. A pi-loops row's turn, started late, takes its cap from the row in the file (`messageStarted`).
+	 */
+	refused(id: string): void {
+		this.handedOver.delete(id);
+		this.handedIdle.delete(id);
+		this.caps.delete(id);
+		this.dropped.delete(id);
+	}
+
+	private forgetPersonCap(id: string): void {
+		const at = this.personCaps.findIndex((p) => p.cap.id === id);
+		if (at >= 0) this.personCaps.splice(at, 1);
+	}
+
+	/**
+	 * At `agent_settled`: the turn is over, with its retries and follow-ups, so the cap in force ends
+	 * here and nowhere earlier. What pi dropped is offered again by the next drain, unless a stop
+	 * named it. A person submission still pending was dropped with pi's queue. Returns the ids forgotten.
+	 */
+	settled(): string[] {
+		this.current = undefined;
+		this.personPending = 0;
+		const dropped = forgetDropped(this.handedOver, (id) => this.delivered(id));
+		for (const id of dropped) {
+			this.caps.delete(id);
+			this.handedIdle.delete(id);
+			this.forgetPersonCap(id);
+			if (this.abortOnStart.delete(id)) this.stopped.add(id);
+			else this.dropped.add(id);
+		}
+		return dropped;
+	}
+
+	/**
+	 * At `agent_start`: a run is on; which row began it is known at its first user message. A retry
+	 * starts one too, under the cap in force. Whatever rows were handed over, pi took something since:
+	 * none of them was refused, and a dropped one is found at `settled`.
+	 */
+	agentStarted(now: number): void {
+		this.running = { startedAt: stamp(now) };
+		this.handedIdle.clear();
+	}
+
+	/**
+	 * pi emitted `input` (ours or anyone's) or began a message: it is in its pre-run phase for
+	 * something, so what was handed over is not refused yet. The grace counts again from here.
+	 */
+	inputSeen(now: number): void {
+		for (const id of this.handedIdle.keys()) this.handedIdle.set(id, now);
+	}
+
+	/**
+	 * At `message_start`, for a user message (a custom one changes nothing). One that starts with
+	 * `[Trigger <id>] ` names a row: the one this instance handed over, else the one still in the
+	 * request file (an earlier instance in this process handed it over, before a /reload), and that
+	 * row's cap is the turn's from here. Any other user message is the person's when they submitted
+	 * one that has not started yet (pi's `input` event, counted in `personInput`); otherwise it is
+	 * another extension's and changes nothing while a row's cap is in force; with none in force it is
+	 * the person's, or nobody's, and uncapped. A row a stop named is aborted here; pi still writes the
+	 * message at `message_end` (its agent loop emits the two back to back), so the proof lands and the
+	 * row is done, not offered again.
+	 */
+	messageStarted(message: unknown, now = Date.now()): void {
+		const text = userTextOf(message);
+		if (text === undefined) return;
+		this.inputSeen(now);
+		const id = triggerIdOf(message);
+		if (id !== undefined) {
+			if (this.running) this.running = { ...this.running, requestId: id };
+			if (this.abortOnStart.delete(id)) this.ctx()?.abort();
+			const cap = this.caps.get(id);
+			this.caps.delete(id);
+			const row = cap ? undefined : this.rows().find((r) => r.id === id);
+			if (cap || row) {
+				// A row's turn starting: a submission counted before it that never became a message (an
+				// input another extension handled, a prompt pi refused) is not what follows. Reset
+				// whatever cycle this is: at worst the person's next message is asked about once.
+				this.personPending = 0;
+				this.current = cap ?? this.capOf(row!);
+				return;
+			}
+		}
+		// A person row's turn: of the rows handed over whose text this message is (`personTextMatches`:
+		// pi appends a note when it resizes or converts an image), the one with the longest text, the
+		// most recently handed over on a tie, so "fix" does not take the turn of "fix it and push
+		// --force". Before a submission pending from the terminal, since the row was handed over first.
+		const claim = (caps: typeof this.personCaps) => {
+			let person = -1;
+			for (let at = 0; at < caps.length; at++) {
+				if (!personTextMatches(text, caps[at].text)) continue;
+				if (person < 0 || caps[at].text.length >= caps[person].text.length) person = at;
+			}
+			return person < 0 ? undefined : caps.splice(person, 1)[0];
+		};
+		// What the person submitted comes before a refused row's kept cap; a send pi runs late is
+		// claimed only by a message nobody else accounts for.
+		const claimed = claim(this.personCaps) ?? (this.personPending > 0 ? undefined : claim(this.lateCaps));
+		if (claimed) {
+			const { cap } = claimed;
+			if (this.running) this.running = { ...this.running, requestId: cap.id };
+			if (this.abortOnStart.delete(cap.id)) this.ctx()?.abort();
+			this.personPending = 0;
+			this.current = cap;
+			return;
+		}
+		// A message with no prefix at all while a pi-loops row is handed over and unstarted: another
+		// extension's `input` handler rewrote the text. pi runs what it was given in order, so the
+		// oldest handed over is the turn starting now, and it runs under its cap. The person's own
+		// pending submission wins; a message with a prefix that names no row of ours is somebody else's.
+		const oldest = this.caps.entries().next();
+		if (id === undefined && this.personPending === 0 && !oldest.done) {
+			const [handedId, cap] = oldest.value;
+			this.caps.delete(handedId);
+			this.handedOver.delete(handedId);
+			this.handedIdle.delete(handedId);
+			this.ranUnproved.add(handedId);
+			if (this.running) this.running = { ...this.running, requestId: handedId };
+			if (this.abortOnStart.delete(handedId)) this.ctx()?.abort();
+			this.current = cap;
+			return;
+		}
+		if (this.personPending > 0) {
+			this.personPending--;
+			this.current = { kind: "person" };
+		} else if (this.current?.kind !== "row") this.current = { kind: "person" };
+	}
+
+	/**
+	 * At `agent_end`: no run is on. An aborted run (Esc, Stop) is over like any other: what is queued
+	 * runs when pi is idle, as messages queued in a chat do (owner decision, 2026-11-02; the queue is
+	 * visible and cancellable instead, `/cron queue`). The cap in force outlives the run (`settled`).
+	 */
+	agentEnded(): void {
+		this.running = undefined;
+	}
+
+	/** The person submitted something (pi's `input` event, not from an extension): the next user message is theirs. */
+	personInput(): void {
+		this.personPending++;
+	}
+}

package/src/window-guard.ts

@@ -0,0 +1,158 @@
+/**
+ * The cap on a scheduled turn in an open window (design §6.3, owner decision O1). A plain job's
+ * prompt runs under the job's declared tools and the dangerous-command policy wherever it runs: in
+ * the background the sub-agent guard (src/subagent-guard.ts) refuses outright, since nobody is there;
+ * in a window the person is, so the same call asks them, with a countdown, and is refused when
+ * nobody answers. `guardDecision` is the whole decision as a function; `windowGuard` is the
+ * `tool_call` handler that applies it, built here so a test can drive it without the extension.
+ */
+import type { ExtensionContext, ToolCallEventResult } from "@earendil-works/pi-coding-agent";
+import { dangerousCommandReason } from "./danger.ts";
+import { PI_BUILTIN_TOOL_NAMES } from "./mcp.ts";
+import { capRedacted } from "./redact.ts";
+import { type CurrentTurn, unattendedTurn } from "./window-executor.ts";
+
+/** How long the person has to answer before an unanswered question refuses the call. */
+export const WINDOW_GUARD_CONFIRM_MS = 60_000;
+
+/**
+ * The two answers to the guard's question, the refusing one first: pi's selector starts on the
+ * first option and Enter picks it, so a reflexive Enter refuses. pi's confirm starts on Yes.
+ */
+export const GUARD_CHOICES = { refuse: "No, refuse it", allow: "Yes, run it once" } as const;
+
+/** Pure. Only the allowing answer allows: no answer (the timeout), Escape and anything else refuse. */
+export function allows(choice: string | undefined): boolean {
+	return choice === GUARD_CHOICES.allow;
+}
+
+/** What the question came to: the allowing answer, the person's refusal, or no answer (the timeout, Escape, no UI). */
+export type GuardAnswer = "yes" | "no" | "none";
+/** How close to its timeout a false confirm counts as the timeout: timers fire slightly early. */
+const TIMEOUT_SLACK_MS = 50;
+
+/**
+ * The question, put so that the reflexive answer refuses. In a terminal pi draws a confirm with the
+ * cursor on Yes, so it is a select with the refusal first. The browser draws a select's title as one
+ * heading line, and its confirm already puts cancel first, so there it stays a confirm. No answer
+ * within `timeout` is a refusal either way; the model is told which it was, so a person's No is not
+ * reported as nobody being there. pi's confirm resolves false for both, so over rpc the clock tells
+ * them apart.
+ */
+export async function askRefusingFirst(ctx: Pick<ExtensionContext, "ui" | "mode">, title: string, body: string, timeout: number): Promise<GuardAnswer> {
+	if (ctx.mode === "rpc") {
+		const asked = Date.now();
+		if (await ctx.ui.confirm(title, body, { timeout })) return "yes";
+		// Timers fire a millisecond or so early against Date.now(); a No in the last instants of the
+		// countdown cannot be told from the countdown anyway.
+		return Date.now() - asked >= timeout - Math.min(TIMEOUT_SLACK_MS, timeout / 10) ? "none" : "no";
+	}
+	const choice = await ctx.ui.select(`${title}\n${body}`, [GUARD_CHOICES.refuse, GUARD_CHOICES.allow], { timeout });
+	return allows(choice) ? "yes" : choice === GUARD_CHOICES.refuse ? "no" : "none";
+}
+
+export interface GuardConfig {
+	/** `[engine] window_guard`; false is 0.23's uncapped window. */
+	windowGuard: boolean;
+	/** `[danger] allow`: commands the dangerous-command policy lets through, as in the background. */
+	allowCommands: readonly string[];
+}
+
+/**
+ * The pi-loops tools a declared tool list lets through undeclared, as the background does (they are
+ * every run's `customTools`): the ones that only read (src/tools.ts), and the ones that carry their
+ * own gate. A job made in a capped turn is capped to that turn's tools (src/pi-loops.ts `toolHost`,
+ * as src/host-runtime.ts scopes a run's), so `cron_create` widens nothing; the rest ask through
+ * `confirmTool` exactly where the background's preflight refuses, and the guard asking as well made
+ * two questions of one call.
+ */
+export const READ_ONLY_AUTOMATION_TOOLS: readonly string[] = ["cron_list", "list_triggers"];
+/** The pi-loops tools whose gate is their own (`confirmTool`, or the cap on what they create): the guard adds no question. */
+export const SELF_GATED_AUTOMATION_TOOLS: readonly string[] = ["cron_create", "cron_remove", "set_cron_job_state", "new_trigger", "remove_trigger", "set_trigger_state"];
+const AUTOMATION_TOOLS: readonly string[] = [...READ_ONLY_AUTOMATION_TOOLS, ...SELF_GATED_AUTOMATION_TOOLS];
+
+export type GuardDecision = { kind: "allow" } | { kind: "ask"; reason: string };
+
+/** The shell command a call carries, for the tools that run one. */
+function commandOf(call: { toolName: string; input?: unknown }): string | undefined {
+	if (call.toolName !== "bash" && call.toolName !== "powershell") return undefined;
+	const command = (call.input as { command?: unknown } | undefined)?.command;
+	return typeof command === "string" ? command : undefined;
+}
+
+/**
+ * Pure. Everything is allowed unless the turn is a scheduled row's and the guard is on. Then a call
+ * asks when the tool is outside what the row declared (`--tools` names the whole set; a built-in
+ * list caps only pi's built-ins, so extension and MCP tools pass; neither declares nothing), or when
+ * the command is one the background would refuse.
+ */
+export function guardDecision(call: { toolName: string; input?: unknown }, current: CurrentTurn | undefined, cfg: GuardConfig): GuardDecision {
+	if (!cfg.windowGuard || !unattendedTurn(current)) return { kind: "allow" };
+	if (current.tools) {
+		if (!current.tools.includes(call.toolName) && !AUTOMATION_TOOLS.includes(call.toolName)) return { kind: "ask", reason: `${call.toolName} is not among the tools the job declared (${current.tools.join(", ") || "none"})` };
+	} else if (current.builtinTools && PI_BUILTIN_TOOL_NAMES.includes(call.toolName) && !current.builtinTools.includes(call.toolName)) {
+		return { kind: "ask", reason: `${call.toolName} is not among the built-in tools the job declared (${current.builtinTools.join(", ") || "none"})` };
+	}
+	const command = commandOf(call);
+	const danger = command === undefined ? undefined : dangerousCommandReason(command, undefined, cfg.allowCommands);
+	return danger === undefined ? { kind: "allow" } : { kind: "ask", reason: danger };
+}
+
+/**
+ * What the model is told: the sub-agent guard's wording, with who refused. `nobody` is the default:
+ * the question timed out, was escaped, or there was no UI to ask; `person` is a No the person gave.
+ */
+export function refusal(reason: string, by: "nobody" | "person" = "nobody"): string {
+	const who = by === "person" ? "The person at the window refused it" : "This scheduled turn ran with nobody answering";
+	return `refused by pi-loops: ${reason}. ${who}; commands that can destroy data or the machine, and tools the job did not declare, are not allowed; do the safe part and report what you would need a human for.`;
+}
+
+/**
+ * How much of the command the question shows. Cut in characters and marked with `…`, so a person
+ * asked to say yes can tell when they have not seen all of it: a code-unit cut with no marker showed
+ * a 300-character command as if it ended at 200, and could end it on half of an emoji.
+ */
+export const WINDOW_GUARD_COMMAND_CHARS = 200;
+
+export interface WindowGuardDeps {
+	current(): CurrentTurn | undefined;
+	config(): GuardConfig;
+	log(line: string): void;
+	/** WINDOW_GUARD_CONFIRM_MS unless a test shortens it. */
+	confirmTimeoutMs?: number;
+}
+
+/**
+ * The `tool_call` handler: decide, ask when the decision says so, refuse when the answer is not the
+ * allowing one or never comes. pi resolves an unanswered or escaped select to undefined, at the
+ * timeout in the terminal and over rpc alike, so the countdown is pi's and the refusal is ours. The
+ * question has no body of its own, so the body rides in the title. This is a boundary that fails closed:
+ * with no UI to ask, or with anything in here throwing, a scheduled turn's call is refused. The
+ * person's own turn goes on as if the guard were not there, and so does a turn with no row in force
+ * (nothing of ours is running: between settle cycles), the one unknown that is allowed. Whose turn
+ * it is comes first, and a failure to learn even that refuses.
+ */
+export function windowGuard(deps: WindowGuardDeps): (event: { toolName: string; input?: unknown }, ctx: Pick<ExtensionContext, "hasUI" | "ui" | "mode"> | undefined) => Promise<ToolCallEventResult | undefined> {
+	const timeout = deps.confirmTimeoutMs ?? WINDOW_GUARD_CONFIRM_MS;
+	return async (event, ctx) => {
+		let current: CurrentTurn | undefined;
+		try {
+			current = deps.current();
+		} catch (err: any) {
+			deps.log(`window guard failed on ${event.toolName}: ${err?.message ?? err}`);
+			return { block: true, reason: refusal("the guard could not decide") };
+		}
+		try {
+			const decision = guardDecision(event, current, deps.config());
+			if (decision.kind === "allow" || !unattendedTurn(current)) return undefined;
+			const command = commandOf(event);
+			const body = [`A scheduled prompt (trace ${current.id.slice(0, 8)}) wants to run ${event.toolName}: ${decision.reason}.`, ...(command === undefined ? [] : [capRedacted(command, WINDOW_GUARD_COMMAND_CHARS)]), `Yes runs it this once. No, or no answer in ${Math.round(timeout / 1000)} s, refuses it and tells the model why.`].join("\n");
+			const answer = ctx?.hasUI ? await askRefusingFirst(ctx, "Allow this in a scheduled turn?", body, timeout) : "none";
+			deps.log(`${answer === "yes" ? "allowed" : "refused"} ${event.toolName} in scheduled turn ${current.id.slice(0, 8)}: ${decision.reason}${ctx?.hasUI ? (answer === "no" ? " (the person said no)" : "") : " (no UI to ask)"}`);
+			return answer === "yes" ? undefined : { block: true, reason: refusal(decision.reason, answer === "no" ? "person" : "nobody") };
+		} catch (err: any) {
+			deps.log(`window guard failed on ${event.toolName}: ${err?.message ?? err}`);
+			return unattendedTurn(current) ? { block: true, reason: refusal("the guard could not decide") } : undefined;
+		}
+	};
+}

package/docs/agents/issue-tracker.md

@@ -1,34 +0,0 @@
-# Issue tracker: GitHub
-
-Work items for this repository live as GitHub Issues in `alphacoder-v0/pi-loops`; pull requests
-are the review surface. Use the `gh` CLI for every operation; it infers the repository from the
-remote when run in a clone. Loops shell out to `gh`, so the account must be authenticated in the
-environment a loop runs in — `gh auth status` answers that.
-
-## Operations
-
-- **List**: `gh issue list --state open --limit 200 --json number,title,labels,updatedAt,author` (add `--label <state>` to filter by state)
-- **Read**: `gh issue view <n> --comments --json number,title,body,labels,author,createdAt,comments`
-- **Comment**: `gh issue comment <n> --body "..."` (a heredoc for multi-line bodies)
-- **Change state**: `gh issue edit <n> --add-label "<new state>" --remove-label "<old state>"` — exactly one state label at a time
-- **Claim**: `gh issue edit <n> --add-label agent-working --remove-label ready-for-agent --add-assignee @me`
-- **Close**: `gh issue close <n> --comment "..."`
-- **Pull requests**: `gh pr create`, `gh pr list --state open --json number,url,headRefName,reviewDecision,comments,updatedAt`, `gh pr view <n> --comments`, `gh pr diff <n>`
-
-## State vocabulary
-
-One category label (`bug` | `enhancement`) and exactly one state label per open issue. The state
-labels are `needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, `agent-working`,
-`in-review`, `agent-blocked`, `wontfix`. They already exist in this repository; `labels.sh`
-refreshes their colour and description and touches no issue. A playbook that moves an issue names
-the label it moves to.
-
-## Blocking
-
-A `Blocked by: #<n>, #<m>` line near the top of an issue body (or the tracker's native
-dependency) gates it: the item is unblocked when every listed issue is closed.
-
-## Who counts as the agent
-
-Comments and assignments made by loops are made as the account `gh` is signed in as — currently
-`alphacoder-v0`. Every comment a loop posts starts with a line saying it was generated by AI.