@selesai/code 0.13.39 → 0.13.40

package/dist/extensions/pi-subagents/src/runs/background/result-delivery-ownership.ts

@@ -1,28 +1,288 @@
-import type { SubagentState } from "../../shared/types.ts";
+import { randomUUID } from "node:crypto";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { ownerFileStem, parseOwnerRecord, readOwnerRecord } from "../../shared/owner-record.ts";
+import { processLiveness, processStartKey, startKeyScheme, type ProcessLiveness } from "../../shared/process-identity.ts";
+import { DIRS, type SubagentState } from "../../shared/types.ts";
 
 const MAX_CLAIMED_PREDECESSOR_SESSIONS = 8;
+const DEFAULT_LIVENESS_TTL_MS = 2_000;
+/** Initial claim plus re-claims after a dead claimer. Exhausting this fails safe (no takeover). */
+const MAX_CLAIM_GENERATIONS = 4;
+const MAX_TAKEN_RESULTS = 256;
+const MAX_VERDICT_CACHE_ENTRIES = 64;
+const OWNER_RECORD_GC_AGE_MS = 7 * 24 * 60 * 60 * 1000;
+const CLAIM_GC_HARD_AGE_MS = 30 * 24 * 60 * 60 * 1000;
+const STALE_TEMP_AGE_MS = 10 * 60 * 1000;
+const GC_INTERVAL_MS = 10 * 60 * 1000;
+const GC_MAX_ENTRIES_EXAMINED = 256;
+const GC_MAX_DELETIONS = 16;
+const CLAIMS_DIR_NAME = "claims";
 
 type ResultDeliveryState = Pick<SubagentState, "currentSessionId" | "completionOwnerId">;
 
+/** `dead` is the only verdict that permits takeover; `unknown` covers every kind of missing or ambiguous proof. */
+export type OwnerVerdict = "dead" | "live" | "unknown";
+
+export interface ResultTakeoverDeps {
+	/** Directory holding `<completionOwnerId>.json` owner records and `claims/`. Defaults to `DIRS.owners`, read per call. */
+	ownersDir?: string | (() => string);
+	hostname?: () => string;
+	processLiveness?: (pid: number) => ProcessLiveness;
+	processStartKey?: (pid: number) => string | undefined;
+	now?: () => number;
+	/** How long a per-owner verdict is reused before liveness is probed again (probing may spawn `ps`). */
+	livenessTtlMs?: number;
+}
+
 export interface ResultDeliveryOwnership {
-	owns(sessionId: string, completionOwnerId: unknown): boolean;
+	/**
+	 * True when this process owns the result. Pass `runKey` (the result's run id) so a result left by a provably dead
+	 * previous owner can be taken over; that call atomically claims it (exactly once across processes).
+	 */
+	owns(sessionId: string, completionOwnerId: unknown, runKey?: string): boolean;
+	/** Side-effect-free twin of the takeover half of `owns`: would `owns(..., runKey)` succeed? */
+	canTakeOver(sessionId: string, completionOwnerId: unknown, runKey?: string): boolean;
 	claimedSessionIds(): readonly string[];
 	claimPredecessor(previousSessionFile: string | undefined, previousRuntimeSessionId: string | null): boolean;
 	clear(): void;
 }
 
-export function createResultDeliveryOwnership(state: ResultDeliveryState): ResultDeliveryOwnership {
+interface ClaimMarker {
+	claimedBy: string;
+	previousOwner: string;
+	claimedAt: number;
+}
+
+type MarkerRead = { state: "missing" } | { state: "invalid" } | { state: "ok"; claimedBy: string };
+
+function errorCode(error: unknown): string | undefined {
+	return typeof error === "object" && error !== null && "code" in error ? (error as NodeJS.ErrnoException).code : undefined;
+}
+
+export function createResultDeliveryOwnership(state: ResultDeliveryState, deps: ResultTakeoverDeps = {}): ResultDeliveryOwnership {
 	const claimed = new Map<string, string>();
+	/** runKey -> proof that this process already holds the claim; keeps `owns` a cheap read after the first call. */
+	const takenOver = new Map<string, { sessionId: string; previousOwner: string; by: string }>();
+	const verdicts = new Map<string, { verdict: OwnerVerdict; at: number }>();
+	const now = deps.now ?? Date.now;
+	const hostname = deps.hostname ?? os.hostname;
+	const livenessOf = deps.processLiveness ?? ((pid: number) => processLiveness(pid));
+	const startKeyOf = deps.processStartKey ?? processStartKey;
+	const livenessTtlMs = deps.livenessTtlMs ?? DEFAULT_LIVENESS_TTL_MS;
+	let lastGcAt = Number.NEGATIVE_INFINITY;
 
 	const currentOwner = (): string | undefined => typeof state.completionOwnerId === "string" && state.completionOwnerId
 		? state.completionOwnerId
 		: undefined;
+	const ownersDir = (): string => typeof deps.ownersDir === "function" ? deps.ownersDir() : deps.ownersDir ?? DIRS.owners;
+	const claimsDir = (): string => path.join(ownersDir(), CLAIMS_DIR_NAME);
+
+	/** Same session condition the in-process rule has always used; takeover never widens it. */
+	const sessionIsOurs = (sessionId: string, owner: string): boolean =>
+		sessionId === state.currentSessionId || claimed.get(sessionId) === owner;
+
+	const ownerVerdictFromDisk = (ownerId: string): OwnerVerdict => {
+		const record = readOwnerRecord(ownersDir(), ownerId);
+		if (!record) return "unknown";
+		return recordVerdict(record.pid, record.startKey, record.hostname);
+	};
+	const recordVerdict = (pid: number, recordedStartKey: string | undefined, recordedHostname: string): OwnerVerdict => {
+		if (recordedHostname !== hostname()) return "unknown";
+		const liveness = livenessOf(pid);
+		if (liveness === "dead") return "dead";
+		if (liveness !== "alive") return "unknown";
+		if (recordedStartKey) {
+			const current = startKeyOf(pid);
+			// A pid reused by another process has a different start time. Keys from different schemes (for example
+			// `/proc` vs `ps`) are not comparable, so a scheme change proves nothing.
+			if (current && startKeyScheme(current) === startKeyScheme(recordedStartKey) && current !== recordedStartKey) return "dead";
+		}
+		return "live";
+	};
+	const verdictOf = (ownerId: string): OwnerVerdict => {
+		const at = now();
+		const cached = verdicts.get(ownerId);
+		if (cached && at >= cached.at && at - cached.at < livenessTtlMs) return cached.verdict;
+		let verdict: OwnerVerdict;
+		try {
+			verdict = ownerVerdictFromDisk(ownerId);
+		} catch {
+			verdict = "unknown";
+		}
+		verdicts.delete(ownerId);
+		verdicts.set(ownerId, { verdict, at });
+		while (verdicts.size > MAX_VERDICT_CACHE_ENTRIES) verdicts.delete(verdicts.keys().next().value!);
+		return verdict;
+	};
+
+	const claimPath = (runKey: string, generation: number): string | undefined => {
+		const stem = ownerFileStem(runKey);
+		// `%g` cannot occur in an encodeURIComponent() stem, so generation files never collide with another key.
+		return stem ? path.join(claimsDir(), generation <= 1 ? `${stem}.json` : `${stem}%g${generation}.json`) : undefined;
+	};
+	const readMarker = (file: string): MarkerRead => {
+		try {
+			const parsed = JSON.parse(fs.readFileSync(file, "utf-8")) as Partial<ClaimMarker> | null;
+			return parsed && typeof parsed.claimedBy === "string" && parsed.claimedBy
+				? { state: "ok", claimedBy: parsed.claimedBy }
+				: { state: "invalid" };
+		} catch (error) {
+			return errorCode(error) === "ENOENT" ? { state: "missing" } : { state: "invalid" };
+		}
+	};
+	/**
+	 * Exclusive create with complete content: write a private temp file, then hard-link it into place (link fails
+	 * with EEXIST if any claimant got there first, and a crash can never leave a half-written marker). Filesystems
+	 * without hard links fall back to `wx`.
+	 */
+	const createMarkerExclusively = (file: string, marker: ClaimMarker): boolean => {
+		fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+		const body = `${JSON.stringify(marker)}\n`;
+		const temp = `${file}.${process.pid}.${randomUUID()}.tmp`;
+		fs.writeFileSync(temp, body, { encoding: "utf-8", mode: 0o600, flag: "wx" });
+		try {
+			fs.linkSync(temp, file);
+			return true;
+		} catch (error) {
+			const code = errorCode(error);
+			if (code === "EEXIST") return false;
+			if (code !== "EPERM" && code !== "ENOSYS" && code !== "ENOTSUP" && code !== "EOPNOTSUPP" && code !== "EXDEV") throw error;
+			try {
+				fs.writeFileSync(file, body, { encoding: "utf-8", mode: 0o600, flag: "wx" });
+				return true;
+			} catch (fallbackError) {
+				if (errorCode(fallbackError) === "EEXIST") return false;
+				throw fallbackError;
+			}
+		} finally {
+			fs.rmSync(temp, { force: true });
+		}
+	};
+
+	/**
+	 * Claim chain: generation 1 is created by the first taker; if its claimer is later proven dead, the next taker
+	 * creates generation 2 (exclusively), and so on. Nothing is ever renamed or overwritten, so two processes that
+	 * both saw a dead claimer cannot both win: exactly one create succeeds per generation.
+	 */
+	const claimResult = (runKey: string, previousOwner: string, owner: string, mode: "claim" | "peek"): boolean => {
+		for (let generation = 1; generation <= MAX_CLAIM_GENERATIONS; generation += 1) {
+			const file = claimPath(runKey, generation);
+			if (!file) return false;
+			let marker = readMarker(file);
+			if (marker.state === "missing") {
+				if (mode === "peek") return true;
+				if (createMarkerExclusively(file, { claimedBy: owner, previousOwner, claimedAt: now() })) return true;
+				marker = readMarker(file);
+			}
+			if (marker.state !== "ok") return false;
+			if (marker.claimedBy === owner) return true;
+			if (verdictOf(marker.claimedBy) !== "dead") return false;
+		}
+		return false;
+	};
+
+	const collectGarbage = (): void => {
+		const at = now();
+		if (at - lastGcAt < GC_INTERVAL_MS) return;
+		lastGcAt = at;
+		const owner = currentOwner();
+		const root = ownersDir();
+		let examined = 0;
+		let deleted = 0;
+		const old = (file: string, ageMs: number): boolean => {
+			try {
+				return at - fs.statSync(file).mtimeMs > ageMs;
+			} catch {
+				return false;
+			}
+		};
+		try {
+			for (const name of fs.readdirSync(root)) {
+				if (examined >= GC_MAX_ENTRIES_EXAMINED || deleted >= GC_MAX_DELETIONS) break;
+				if (!name.endsWith(".json")) continue;
+				examined += 1;
+				const file = path.join(root, name);
+				if (!old(file, OWNER_RECORD_GC_AGE_MS)) continue;
+				const record = (() => {
+					try {
+						return parseOwnerRecord(JSON.parse(fs.readFileSync(file, "utf-8")));
+					} catch {
+						return undefined;
+					}
+				})();
+				if (record?.completionOwnerId === owner) continue;
+				if (record && recordVerdict(record.pid, record.startKey, record.hostname) !== "dead") continue;
+				fs.rmSync(file, { force: true });
+				deleted += 1;
+			}
+		} catch {
+			// Garbage collection is best effort and must never affect delivery.
+		}
+		try {
+			const claims = claimsDir();
+			for (const name of fs.readdirSync(claims)) {
+				if (examined >= GC_MAX_ENTRIES_EXAMINED || deleted >= GC_MAX_DELETIONS) break;
+				examined += 1;
+				const file = path.join(claims, name);
+				if (name.endsWith(".tmp")) {
+					if (old(file, STALE_TEMP_AGE_MS)) {
+						fs.rmSync(file, { force: true });
+						deleted += 1;
+					}
+					continue;
+				}
+				if (!name.endsWith(".json") || !old(file, OWNER_RECORD_GC_AGE_MS)) continue;
+				// Only the newest generation of a key may go, or an older dead claim could be re-created beneath a live one.
+				const match = /^(.*?)(?:%g(\d+))?\.json$/.exec(name);
+				if (!match) continue;
+				const generation = match[2] ? Number(match[2]) : 1;
+				if (fs.existsSync(path.join(claims, `${match[1]}%g${generation + 1}.json`))) continue;
+				if (!old(file, CLAIM_GC_HARD_AGE_MS)) {
+					const marker = readMarker(file);
+					if (marker.state === "ok" && (marker.claimedBy === owner || verdictOf(marker.claimedBy) !== "dead")) continue;
+				}
+				fs.rmSync(file, { force: true });
+				deleted += 1;
+			}
+		} catch {
+			// Best effort, as above.
+		}
+	};
+
+	const takeOver = (sessionId: string, completionOwnerId: unknown, runKey: string | undefined, mode: "claim" | "peek"): boolean => {
+		const owner = currentOwner();
+		if (!owner || typeof completionOwnerId !== "string" || !completionOwnerId || completionOwnerId === owner) return false;
+		if (typeof runKey !== "string" || !runKey || typeof sessionId !== "string" || !sessionId) return false;
+		if (!sessionIsOurs(sessionId, owner)) return false;
+		const taken = takenOver.get(runKey);
+		if (taken && taken.by === owner && taken.sessionId === sessionId && taken.previousOwner === completionOwnerId) return true;
+		try {
+			collectGarbage();
+			if (verdictOf(completionOwnerId) !== "dead") return false;
+			if (!claimResult(runKey, completionOwnerId, owner, mode)) return false;
+		} catch {
+			// Any filesystem surprise means we cannot prove exclusive ownership: fail safe.
+			return false;
+		}
+		if (mode === "claim") {
+			takenOver.delete(runKey);
+			takenOver.set(runKey, { sessionId, previousOwner: completionOwnerId, by: owner });
+			while (takenOver.size > MAX_TAKEN_RESULTS) takenOver.delete(takenOver.keys().next().value!);
+		}
+		return true;
+	};
 
 	return {
-		owns(sessionId, completionOwnerId) {
+		owns(sessionId, completionOwnerId, runKey) {
 			const owner = currentOwner();
-			if (!owner || completionOwnerId !== owner) return false;
-			return sessionId === state.currentSessionId || claimed.get(sessionId) === owner;
+			if (!owner) return false;
+			if (completionOwnerId === owner) return sessionId === state.currentSessionId || claimed.get(sessionId) === owner;
+			return takeOver(sessionId, completionOwnerId, runKey, "claim");
+		},
+		canTakeOver(sessionId, completionOwnerId, runKey) {
+			return takeOver(sessionId, completionOwnerId, runKey, "peek");
 		},
 		claimedSessionIds() {
 			const owner = currentOwner();
@@ -40,6 +300,8 @@ export function createResultDeliveryOwnership(state: ResultDeliveryState): Resul
 		},
 		clear() {
 			claimed.clear();
+			takenOver.clear();
+			verdicts.clear();
 		},
 	};
-}
+}

package/dist/extensions/pi-subagents/src/runs/background/result-watcher.ts

@@ -223,16 +223,17 @@ export function createResultWatcher(
 	// The sole in-memory ownership lease. It is acquired for one active session
 	// and revoked before the watcher, queues, or callbacks are torn down.
 	let activeSessionId: string | null = null;
+	// `runKey` lets the shared ownership take over a result left by a provably dead previous owner.
 	const ownsResult = deps.ownership?.owns
-		?? ((sessionId: string, completionOwnerId: unknown) => sessionId === state.currentSessionId
+		?? ((sessionId: string, completionOwnerId: unknown, _runKey?: string) => sessionId === state.currentSessionId
 			&& typeof completionOwnerId === "string"
 			&& completionOwnerId === state.completionOwnerId);
 	const claimedSessionIds = () => deps.ownership?.claimedSessionIds() ?? [];
 
-	const ownsCompletion = (sessionId: string, completionOwnerId: unknown, epoch: number) => {
+	const ownsCompletion = (sessionId: string, completionOwnerId: unknown, epoch: number, runKey?: string) => {
 		if (!deliveryActive || epoch !== deliveryEpoch) return false;
 		if (!activeSessionId && state.currentSessionId) activeSessionId = state.currentSessionId;
-		return activeSessionId === state.currentSessionId && ownsResult(sessionId, completionOwnerId);
+		return activeSessionId === state.currentSessionId && ownsResult(sessionId, completionOwnerId, runKey);
 	};
 
 	const scheduleResult = (file: string, triggerTurn: boolean, delayMs = 0) => {
@@ -318,7 +319,7 @@ export function createResultWatcher(
 		// Missing identity stays on the normal parser path so malformed or legacy
 		// files keep their existing diagnostics and compatibility behavior.
 		if (!identity.sessionId) return true;
-		if (ownsResult(identity.sessionId, identity.completionOwnerId)) return true;
+		if (ownsResult(identity.sessionId, identity.completionOwnerId, identity.runId)) return true;
 		if (identity.asyncDir && fsApi.existsSync(path.join(identity.asyncDir, MISSION_BINDING_FILE))) return true;
 		if (identity.runId && (observed ?? observedRunIds()).has(identity.runId)) return true;
 		return Boolean(deps.observeCompletion && !deps.observedCompletionRunIds);
@@ -425,7 +426,7 @@ export function createResultWatcher(
 			}
 			if (observerSucceeded) removeMissionObserverIndex(resultsDir, runId);
 			const epoch = deliveryEpoch;
-			if (!ownsCompletion(sessionId, completionOwnerId, epoch)) return;
+			if (!ownsCompletion(sessionId, completionOwnerId, epoch, runId)) return;
 			// Recorded before dedupe and before the unlink below so bg_wait can
 			// use the in-memory record or its bounded durable replay after cleanup.
 			recordWaitCompletion(state, runId, data, Date.now(), completionTtlMs, {
@@ -454,7 +455,7 @@ export function createResultWatcher(
 					scheduleResult(file, triggerTurn, RETRY_DELAY_MS);
 					return;
 				}
-				if (!ownsCompletion(sessionId, completionOwnerId, epoch)) return;
+				if (!ownsCompletion(sessionId, completionOwnerId, epoch, runId)) return;
 				if (markReplacedPayload()) return;
 				if (!removeDeliveredResult(file, sessionId, runId, toolCallId)) scheduleResult(file, triggerTurn, RETRY_DELAY_MS);
 				return;
@@ -511,7 +512,7 @@ export function createResultWatcher(
 					scheduleResult(file, triggerTurn, RETRY_DELAY_MS);
 					return;
 				}
-				if (!ownsCompletion(sessionId, completionOwnerId, epoch)) return;
+				if (!ownsCompletion(sessionId, completionOwnerId, epoch, runId)) return;
 				if (markReplacedPayload()) return;
 				if (!removeDeliveredResult(file, sessionId, runId, toolCallId)) scheduleResult(file, triggerTurn, RETRY_DELAY_MS);
 				return;
@@ -533,7 +534,7 @@ export function createResultWatcher(
 					asyncDir: data.asyncDir,
 					...(data.parallelHandoff ? { parallelHandoff: data.parallelHandoff } : {}),
 				}));
-				if (!ownsCompletion(sessionId, completionOwnerId, epoch)) return;
+				if (!ownsCompletion(sessionId, completionOwnerId, epoch, runId)) return;
 				if (!intercomDelivered) console.error(`Subagent async grouped result intercom delivery was not acknowledged for '${resultPath}'.`);
 			}
 
@@ -557,7 +558,7 @@ export function createResultWatcher(
 					})) : [],
 				} : {}),
 			});
-			if (!ownsCompletion(sessionId, completionOwnerId, epoch)) return;
+			if (!ownsCompletion(sessionId, completionOwnerId, epoch, runId)) return;
 			if (!accepted) {
 				scheduleResult(file, triggerTurn, RETRY_DELAY_MS);
 				return;
@@ -599,7 +600,7 @@ export function createResultWatcher(
 				scheduleResult(file, triggerTurn, RETRY_DELAY_MS);
 				return;
 			}
-			if (!ownsCompletion(sessionId, completionOwnerId, epoch)) return;
+			if (!ownsCompletion(sessionId, completionOwnerId, epoch, runId)) return;
 			if (!removeDeliveredResult(file, sessionId, runId, toolCallId)) scheduleResult(file, triggerTurn, RETRY_DELAY_MS);
 		} catch (error) {
 			if (isAccessDenied(error)) {

package/dist/extensions/pi-subagents/src/runs/background/retained-nested-route-tracker.ts

@@ -13,7 +13,7 @@ const DEFAULT_POLL_INTERVAL_MS = 5000;
 const REFRESH_DEBOUNCE_MS = 25;
 
 export function createRetainedNestedRouteTracker(
-	state: Pick<SubagentState, "retainedForegroundNestedRoutes">,
+	state: Pick<SubagentState, "retainedForegroundNestedRoutes" | "retainedForegroundNestedChildren"> & Partial<Pick<SubagentState, "currentSessionId">>,
 	options: RetainedNestedRouteTrackerOptions = {},
 ): { track: (rootRunId: string) => void; clear: () => void } {
 	const pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
@@ -32,12 +32,23 @@ export function createRetainedNestedRouteTracker(
 
 	const refresh = (rootRunId: string): void => {
 		const retained = state.retainedForegroundNestedRoutes?.get(rootRunId);
-		if (!retained) {
+		const cached = state.retainedForegroundNestedChildren?.get(rootRunId);
+		if (!retained || cached && cached.sessionId !== state.currentSessionId) {
+			state.retainedForegroundNestedChildren?.delete(rootRunId);
+			state.retainedForegroundNestedRoutes?.delete(rootRunId);
 			close(rootRunId);
 			return;
 		}
 		try {
-			if (hasLiveNestedDescendants(projectNestedEvents(retained).children)) return;
+			const children = projectNestedEvents(retained).children;
+			if (hasLiveNestedDescendants(children)) {
+				if (state.currentSessionId) {
+					state.retainedForegroundNestedChildren ??= new Map();
+					state.retainedForegroundNestedChildren.set(rootRunId, { sessionId: state.currentSessionId, ...(cached?.workflowId ? { workflowId: cached.workflowId } : {}), children });
+				}
+				return;
+			}
+			state.retainedForegroundNestedChildren?.delete(rootRunId);
 			state.retainedForegroundNestedRoutes?.delete(rootRunId);
 			close(rootRunId);
 		} catch (error) {
@@ -90,6 +101,7 @@ export function createRetainedNestedRouteTracker(
 		for (const timer of refreshTimers.values()) clearTimeout(timer);
 		refreshTimers.clear();
 		state.retainedForegroundNestedRoutes?.clear();
+		state.retainedForegroundNestedChildren?.clear();
 	};
 
 	return { track, clear };

package/dist/extensions/pi-subagents/src/runs/background/scheduled-runs.ts

@@ -562,6 +562,70 @@ export class ScheduledRunManager {
 		return new Set(this.observedAsyncIds);
 	}
 
+	/** Read-only: schedules that currently hold an armed timer in THIS process (used by release readiness). */
+	armedSchedules(): Array<{ id: string; nextRunAt?: number; sessionOnly?: boolean }> {
+		const armed: Array<{ id: string; nextRunAt?: number; sessionOnly?: boolean }> = [];
+		for (const key of this.timers.keys()) {
+			const [root = "", id = ""] = key.split("\0");
+			const entry: { id: string; nextRunAt?: number; sessionOnly?: boolean } = { id };
+			try {
+				const schedule = this.stores.get(root)?.find(id);
+				const next = schedule?.trigger.nextRunAt ? Date.parse(schedule.trigger.nextRunAt) : Number.NaN;
+				if (Number.isFinite(next)) entry.nextRunAt = next;
+				if (schedule) entry.sessionOnly = schedule.sessionOnly === true;
+			} catch {
+				// An unreadable schedule is still armed; report it without detail.
+			}
+			armed.push(entry);
+		}
+		return armed;
+	}
+
+	/**
+	 * Kill switch (`stop_all_background`): disarms every armed SESSION-ONLY schedule of this process. Each one is PAUSED (persisted,
+	 * `schedule.paused` event) and its timer cleared, so it neither fires now nor on the next launch (`restoreOne`/`runDue` skip
+	 * paused schedules, so `catchUp: "latest"` cannot revive it). Pause is chosen over delete on purpose: it is reversible
+	 * (`schedule.resume`), keeps the schedule's history and active-run bookkeeping, and `delete` refuses a schedule with an active run.
+	 * Project schedules are NOT touched (D11: they persist on disk and re-arm from the project on any launch). An armed timer whose
+	 * record cannot be read is left alone and reported (it may be a project schedule). Idempotent: a disarmed schedule holds no timer.
+	 */
+	disarmSessionOnlySchedules(): Array<{ id: string; ok: boolean; detail: string; error?: string }> {
+		const results: Array<{ id: string; ok: boolean; detail: string; error?: string }> = [];
+		for (const key of [...this.timers.keys()]) {
+			const [root = "", id = ""] = key.split("\0");
+			const store = this.stores.get(root);
+			try {
+				if (!store) throw new Error("schedule store is not loaded");
+				const schedule = store.find(id);
+				if (!schedule) {
+					// Deleted by another process while this one still held the timer: nothing to pause, just un-arm.
+					this.clearTimer(store, id);
+					results.push({ id, ok: true, detail: `Schedule ${id} no longer exists; cleared its timer` });
+					continue;
+				}
+				if (schedule.sessionOnly !== true) continue;
+				try {
+					if (!schedule.paused) {
+						schedule.paused = true;
+						schedule.updatedAt = timestamp(this.now());
+						store.write(schedule);
+						store.appendEvent(schedule, "schedule.paused");
+					}
+				} catch (error) {
+					results.push({ id, ok: false, detail: `Session-only schedule ${id}: timer cleared but the pause could not be saved, so it may fire on the next launch: ${error instanceof Error ? error.message : String(error)}`, error: error instanceof Error ? error.message : String(error) });
+					continue;
+				} finally {
+					this.clearTimer(store, id);
+				}
+				results.push({ id, ok: true, detail: `Paused session-only schedule ${id} and cleared its timer (schedule.resume re-arms it)` });
+			} catch (error) {
+				const text = error instanceof Error ? error.message : String(error);
+				results.push({ id, ok: false, detail: `Armed schedule ${id} could not be read (${text}); left armed because it may be a project schedule`, error: text });
+			}
+		}
+		return results;
+	}
+
 	referencedAsyncRunIds(): Set<string> {
 		const runIds = new Set(this.observedAsyncIds);
 		for (const store of this.stores.values()) {

package/dist/extensions/pi-subagents/src/runs/background/subagent-runner.ts

@@ -79,6 +79,7 @@ import {
 	formatControlIntercomMessage,
 	formatControlNoticeMessage,
 	shouldEmitOpenToolAttention,
+	forgetControlNotifications,
 } from "../shared/subagent-control.ts";
 import {
 	type RunnerSubagentStep as SubagentStep,
@@ -2735,6 +2736,53 @@ export async function runSubagent(
 		currentActivityState = nextRunState;
 		setOptionalProperty(statusPayload, "activityState", nextRunState);
 	};
+	/**
+	 * Why a step is flagged `needs_attention`, by flat index, so the flag is dropped when THAT cause resolves (decision D12).
+	 * `supervisor_request` is tracked separately by `supervisorAttentionSteps`. Terminal handling (stop/interrupt/timeout/final
+	 * status) still clears the flag unconditionally, and the `partial`-with-evidence and completion-guard paths stay terminal-only.
+	 */
+	type AttentionCause = "tool_open_threshold" | "tool_failures" | "idle" | "steering";
+	const attentionCauses = new Map<number, Set<AttentionCause>>();
+	const attentionResumeState = new Map<number, ActivityState | undefined>();
+	const noteAttentionCause = (flatIndex: number, cause: AttentionCause, previous: ActivityState | undefined): void => {
+		const causes = attentionCauses.get(flatIndex) ?? new Set<AttentionCause>();
+		if (causes.size === 0 && previous !== "needs_attention") attentionResumeState.set(flatIndex, previous);
+		causes.add(cause);
+		attentionCauses.set(flatIndex, causes);
+	};
+	const emitAttentionCleared = (flatIndex: number, cause: AttentionCause | "supervisor_request", to: ActivityState | undefined, now: number): void => {
+		const step = statusPayload.steps[flatIndex];
+		appendJsonl(eventsPath, JSON.stringify({
+			type: "subagent.attention.cleared",
+			ts: now,
+			runId: id,
+			...(step?.agent ? { agent: step.agent } : {}),
+			index: flatIndex,
+			from: "needs_attention",
+			to: to ?? null,
+			reason: cause,
+		}));
+	};
+	/**
+	 * Drops one `needs_attention` cause. When it was the last one holding the step, restores the step's previous non-attention state,
+	 * recomputes the run-level state, lets the same problem notify again if it recurs and appends `subagent.attention.cleared`.
+	 * The caller persists status. Returns true when the step's state changed.
+	 */
+	const resolveAttentionCause = (flatIndex: number, cause: AttentionCause, now: number): boolean => {
+		const causes = attentionCauses.get(flatIndex);
+		if (!causes?.delete(cause) || causes.size > 0) return false;
+		attentionCauses.delete(flatIndex);
+		const resumeState = attentionResumeState.get(flatIndex);
+		attentionResumeState.delete(flatIndex);
+		const step = statusPayload.steps[flatIndex];
+		if (!step || step.status !== "running" || step.activityState !== "needs_attention") return false;
+		if (supervisorAttentionSteps.has(flatIndex)) return false;
+		setOptionalProperty(step, "activityState", resumeState);
+		syncAggregateActivityState();
+		if (cause !== "steering") forgetControlNotifications(emittedControlEventKeys, { runId: id, index: flatIndex }, cause, config.childIntercomTargets?.[flatIndex]);
+		emitAttentionCleared(flatIndex, cause, resumeState, now);
+		return true;
+	};
 	const maybeEmitOpenToolAttention = (flatIndex: number, now: number): boolean => {
 		const step = statusPayload.steps[flatIndex];
 		if (!step || step.status !== "running" || step.activityState === "needs_attention") return false;
@@ -2742,6 +2790,7 @@ export async function runSubagent(
 		if (!target) return false;
 		const previous = step.activityState;
 		step.activityState = "needs_attention";
+		noteAttentionCause(flatIndex, "tool_open_threshold", previous);
 		statusPayload.activityState = "needs_attention";
 		const toolDurationMs = Math.max(0, now - target.startedAt);
 		appendControlEvent(buildControlEvent(omitUndefinedProperties({
@@ -2802,7 +2851,10 @@ export async function runSubagent(
 	const steeringMarkerPath = (requestId: string): string => path.join(asyncDir, "control", "steer-recovery", `${Buffer.from(requestId).toString("base64url")}.json`);
 	const markSteeringAttention = (index: number): void => {
 		const step = statusPayload.steps[index];
-		if (step) step.activityState = "needs_attention";
+		if (step) {
+			noteAttentionCause(index, "steering", step.activityState);
+			step.activityState = "needs_attention";
+		}
 		statusPayload.activityState = "needs_attention";
 	};
 	const emitSteeringEvent = (type: string, request: SteerRequest, index?: number, extra: Record<string, unknown> = {}): void => {
@@ -2903,6 +2955,8 @@ export async function runSubagent(
 		const now = Date.now();
 		if (delivery.state === "delivered") {
 			updateSteeringLifecycleTarget(requestId, index, late ? "late" : "delivered", now, omitUndefinedProperties({ reason: late ? "acknowledged after recovery commit" : undefined }));
+			// A delivered (or late-acknowledged) steer shows the child accepts steering again: the steering problem is over.
+			resolveAttentionCause(index, "steering", now);
 			emitSteeringEvent("subagent.steer.delivered", { type: "steer", id: requestId, ts: now, message: delivery.message }, index, { late, deliveryStatus: "delivered", message: delivery.message });
 		} else if (delivery.state === "queued") {
 			updateSteeringLifecycleTarget(requestId, index, "queued", now);
@@ -3029,9 +3083,11 @@ export async function runSubagent(
 			const supervisorPreviousActivity = supervisorAttentionSteps.get(flatIndex);
 			const stillBlockingSupervisor = [...(activeToolCalls[flatIndex]?.values() ?? [])].some((active) => active.blocksSupervisor);
 			const clearedSupervisorAttention = endedTool?.blocksSupervisor && !stillBlockingSupervisor ? supervisorAttentionSteps.delete(flatIndex) : false;
-			if (clearedSupervisorAttention && step.activityState === "needs_attention") {
+			// Another unresolved cause (e.g. a failed steer) keeps the step flagged; its own resolution restores the state.
+			if (clearedSupervisorAttention && step.activityState === "needs_attention" && !attentionCauses.get(flatIndex)?.size) {
 				setOptionalProperty(step, "activityState", supervisorPreviousActivity);
 				syncAggregateActivityState();
+				emitAttentionCleared(flatIndex, "supervisor_request", supervisorPreviousActivity, now);
 			}
 			syncTopLevelCurrentTool();
 		} else if (event.type === "tool_result_end" && event.message) {
@@ -3059,6 +3115,7 @@ export async function runSubagent(
 				if (controlConfig.enabled && shouldEscalateMutatingFailures(state, controlConfig.failedToolAttemptsBeforeAttention) && step.activityState !== "needs_attention") {
 					const previous = step.activityState;
 					step.activityState = "needs_attention";
+					noteAttentionCause(flatIndex, "tool_failures", previous);
 					statusPayload.activityState = "needs_attention";
 					appendControlEvent(buildControlEvent(omitUndefinedProperties({
 						type: "needs_attention",
@@ -3081,6 +3138,8 @@ export async function runSubagent(
 				}
 			} else if (toolSnapshot?.mutates) {
 				resetMutatingFailureState(mutatingFailureStates[flatIndex]!);
+				// The failure streak that raised the flag is broken by a successful mutating tool.
+				resolveAttentionCause(flatIndex, "tool_failures", now);
 			}
 		} else if (event.type === "message_end" && event.message?.role === "assistant") {
 			appendRecentStepOutput(step, stripAcceptanceReport(extractTextFromContent(event.message.content)).split("\n").slice(-10));
@@ -3108,6 +3167,8 @@ export async function runSubagent(
 		step.lastActivityAt = now;
 		statusPayload.lastActivityAt = now;
 		statusPayload.lastUpdate = now;
+		// The open tool that raised `tool_open_threshold` ended (or no remaining open tool is past the threshold): the step recovered.
+		if (attentionCauses.get(flatIndex)?.has("tool_open_threshold") && !openToolAttentionTarget(flatIndex, now)) resolveAttentionCause(flatIndex, "tool_open_threshold", now);
 		maybeEmitActiveLongRunning(flatIndex, now);
 		// A sibling may keep aggregate attention unchanged; publish this step's transition.
 		writeStatusPayload(step.activityState !== previousActivityState);
@@ -3137,6 +3198,7 @@ export async function runSubagent(
 			if (idleState === "needs_attention") {
 				const previous = step.activityState;
 				step.activityState = "needs_attention";
+				noteAttentionCause(index, "idle", previous);
 				if (previous !== "needs_attention") {
 					appendControlEvent(buildControlEvent(omitUndefinedProperties({
 						from: previous,
@@ -3149,10 +3211,11 @@ export async function runSubagent(
 					})));
 					changed = true;
 				}
-			} else if (maybeEmitOpenToolAttention(index, now)) {
-				changed = true;
-			} else if (maybeEmitActiveLongRunning(index, now)) {
-				changed = true;
+			} else {
+				// New activity (or an open tool) ended the idle period that raised the flag.
+				if (resolveAttentionCause(index, "idle", now)) changed = true;
+				if (maybeEmitOpenToolAttention(index, now)) changed = true;
+				else if (maybeEmitActiveLongRunning(index, now)) changed = true;
 			}
 		}
 		if (statusPayload.lastActivityAt !== runLastActivityAt) {