pi-better-harness 0.36.0 → 0.37.0

package/node_modules/pi-better-subagents/README.md

@@ -12,6 +12,7 @@ Use `pi-better-subagents` when you want Pi to launch independent agent work with
 
 ## Core Features
 - Non-blocking subagent launches, with an optional role and named-agent catalog (`docs/agent-catalog.md`, `docs/agent-catalog-lifecycle.md`).
+- Completed-subagent continuation: `subagent_resume` continues a saved single or batch conversation under a new attempt id. Retention is optional cleanup protection: `retain_session` pins artifacts, and `subagent_release` removes that protection without invalidating history that still exists. See [continuing a completed subagent](docs/usage.md#continuing-a-completed-subagent).
 - Typed foreground `subagent_spawn_batch` launch receipts for native Pi codemode (Pi 0.99.1+), preserving direct tool calls, per-run callbacks, and batch capacity/catalog guarantees. See [codemode batch launches](docs/usage.md#codemode-batch-launches).
 - Opt-in OS task sandboxing on macOS and Linux.
 - Explicit tool allowlists for child sessions.

package/node_modules/pi-better-subagents/cleanup.ts

@@ -7,12 +7,13 @@ import {
     statSync,
     writeFileSync,
 } from "node:fs";
-import { join, relative } from "node:path";
+import { join, relative, sep } from "node:path";
 import {
     baseDir,
     listMetas,
     ownedByThisParent,
     orphanedTaskRuntimeProvenance,
+    processStartToken,
     readMeta,
     removeMetaArtifacts,
     removeRunDirectory,
@@ -23,6 +24,17 @@ import {
     type RunStatus,
 } from "./registry.ts";
 import type { SubagentConfig } from "./config.ts";
+import {
+    ConversationBusyError,
+    ConversationLockUnavailableError,
+    conversationLeaseDir,
+    readConversationLease,
+    readRetention,
+    retainedRunIds,
+    retainedSessionIds,
+    withConversationMutation,
+} from "./continuation.ts";
+import { processExists } from "./spawn.ts";
 
 export const DEFAULT_CLEANUP_RETENTION_MS = 7 * 24 * 60 * 60 * 1000;
 
@@ -46,6 +58,17 @@ export const DEFAULT_MAX_REGISTRY_BYTES = 2 * 1024 * 1024 * 1024; // 2 GiB
  */
 export const SIZE_SWEEP_INTERVAL_MS = 10 * 60 * 1000; // 10min
 
+/**
+ * How long one conversation's cleanup step may wait for its mutation lock.
+ * Admission fails fast (0) and release/retention wait a second; cleanup is a
+ * background sweep, so it waits just long enough to lose gracefully to an
+ * in-flight admission and then retains the resource.
+ */
+const CLEANUP_LOCK_WAIT_MS = 250;
+
+/** Conversation ids the per-conversation mutation lock accepts. */
+const SESSION_ID_PATTERN = /^[A-Za-z0-9_-]+$/;
+
 interface CleanupState {
     lastLocalDate?: string;
     lastRunAt?: number;
@@ -65,6 +88,29 @@ export interface DailyCleanupOptions {
     config?: Pick<SubagentConfig, "cleanupTerminalRunRetentionMs" | "cleanupSessionRetentionMs">;
     terminalRunRetentionMs?: number;
     sessionRetentionMs?: number;
+    /**
+     * Artifacts a caller has already validated and is about to use. A launch
+     * path that opens a saved conversation or runs inside a retained workspace
+     * passes them so its own in-process sweep cannot remove what it just checked.
+     *
+     * Protection is a caller promise, not a lease: the caller owns the lifetime
+     * it is asserting and passes nothing once the work is quiescent.
+     */
+    protect?: CleanupProtection;
+}
+
+/**
+ * Artifacts one sweep must keep, identified by the three things continuation
+ * cares about: the conversation, the individual attempt/root, and the exact
+ * paths on disk (saved session file, shared workspace, task scratch).
+ */
+export interface CleanupProtection {
+    /** Native session ids whose runs, saved history, and workspaces are in use. */
+    sessionIds?: Iterable<string>;
+    /** Individual run ids (attempt or root) that must not be removed. */
+    runIds?: Iterable<string>;
+    /** Exact paths to keep, e.g. a saved conversation file or a shared workspace. */
+    paths?: Iterable<string>;
 }
 
 const TERMINAL_CLEANUP_STATUSES = new Set<RunStatus>(["completed", "failed", "killed", "lost"]);
@@ -190,7 +236,210 @@ function removePath(path: string, errors: string[]): boolean {
     }
 }
 
-function cleanRunDirs(cutoff: number, errors: string[]): number {
+/** True when `path` is `root` itself or lies beneath it. */
+function pathWithin(path: string, root: string): boolean {
+    return path === root || path.startsWith(root.endsWith(sep) ? root : root + sep);
+}
+
+function pathOverlapsProtected(path: string, protectedPaths: readonly string[]): boolean {
+    for (const protectedPath of protectedPaths) {
+        if (pathWithin(path, protectedPath) || pathWithin(protectedPath, path)) return true;
+    }
+    return false;
+}
+
+/**
+ * Whether this attempt's recorded child may still be writing its conversation.
+ *
+ * A `running`/`orphaned` record is occupancy by itself. `killed` is recorded as
+ * soon as the stop policy decides, while the child can still be alive and
+ * appending; `lost` means supervision lost track, not that the process proved
+ * gone. So only an actual process-identity match counts there, and an
+ * unavailable start token proves nothing and counts as alive.
+ */
+function recordedChildMayWrite(meta: RunMeta): boolean {
+    if (!TERMINAL_CLEANUP_STATUSES.has(meta.status)) return true;
+    if (meta.status !== "killed" && meta.status !== "lost") return false;
+    const pid = meta.pid;
+    if (typeof pid !== "number" || pid <= 0 || !processExists(pid)) return false;
+    if (meta.pidStartTime === undefined) return true;
+    const current = processStartToken(pid);
+    return current === undefined || current === meta.pidStartTime;
+}
+
+/**
+ * Whether a writer lease says this conversation is in use.
+ *
+ * The lease is taken by the supervising foreground *before* the detached child
+ * is spawned and before the attempt's metadata exists, so it is the only
+ * evidence of occupancy during that admission window. This reads the same
+ * record continuation admission uses without recovering or deleting it. A dead
+ * supervisor can have spawned a child before publishing its attempt metadata;
+ * missing writer evidence therefore keeps the shared workspace protected.
+ */
+function leaseMayHaveWriter(sessionId: string): boolean {
+    const lease = readConversationLease(sessionId);
+    if (!lease) return false;
+    if (lease.pid === process.pid) return true;
+    if (processExists(lease.pid)) {
+        if (lease.start === undefined) return true;
+        const current = processStartToken(lease.pid);
+        if (current === undefined || current === lease.start) return true;
+    }
+    const writer = readMeta(lease.attemptId);
+    return !writer || recordedChildMayWrite(writer);
+}
+
+interface CleanupOccupancy {
+    /** Conversations with a possible writer, plus caller-protected conversations. */
+    sessions: Set<string>;
+    /** Every run id of an occupied conversation, plus caller-protected runs. */
+    runIds: Set<string>;
+    /** Caller-protected paths that neither sweep may remove. */
+    paths: string[];
+}
+
+/**
+ * Decide which conversations are live enough that no run of theirs (the shared
+ * root clone/scratch and saved history included) may be retired yet.
+ *
+ * Continuation made the workspace and saved session outlive the attempt that
+ * created them: a later attempt runs inside the root's clone and appends to the
+ * root's history. Age and size sweeps therefore protect conversation-level
+ * occupancy, not attempt-local status alone.
+ */
+function planCleanupOccupancy(
+    metas: readonly RunMeta[],
+    protect: CleanupProtection | undefined,
+): CleanupOccupancy {
+    const runIds = new Set<string>(protect?.runIds ?? []);
+    const paths = [...(protect?.paths ?? [])];
+
+    // A protected path may be the shared workspace or something inside it. The
+    // run whose removal would delete it is protected instead, because
+    // `removeMetaArtifacts` removes an owned workspace/scratch with its run.
+    for (const meta of metas) {
+        if (ownedResources(meta).some((owned) => paths.some((keep) => pathWithin(keep, owned)))) {
+            runIds.add(meta.id);
+        }
+    }
+
+    const sessions = new Set<string>(protect?.sessionIds ?? []);
+    for (const meta of metas) {
+        if (runIds.has(meta.id)) sessions.add(meta.sessionId);
+        if (recordedChildMayWrite(meta) || leaseMayHaveWriter(meta.sessionId)) {
+            sessions.add(meta.sessionId);
+        }
+    }
+    for (const meta of metas) {
+        if (sessions.has(meta.sessionId)) runIds.add(meta.id);
+    }
+    return { sessions, runIds, paths };
+}
+
+/**
+ * What one sweep needs to make a removal decision that outlives its snapshot:
+ * the run ids it knows per conversation (for a fresh re-read inside that
+ * conversation's lock) and the snapshot occupancy the caller's protection was
+ * folded into.
+ */
+interface CleanupScope {
+    occupancy: CleanupOccupancy;
+    runIdsBySession: Map<string, string[]>;
+}
+
+function runIdsBySession(metas: readonly RunMeta[]): Map<string, string[]> {
+    const bySession = new Map<string, string[]>();
+    for (const meta of metas) {
+        const ids = bySession.get(meta.sessionId);
+        if (ids) ids.push(meta.id);
+        else bySession.set(meta.sessionId, [meta.id]);
+    }
+    return bySession;
+}
+
+/** Session ids with a published writer lease file. */
+function leasedSessionIds(): string[] {
+    let names: string[];
+    try {
+        names = readdirSync(conversationLeaseDir());
+    } catch {
+        return [];
+    }
+    return names
+        .filter((name) => name.endsWith(".lock"))
+        .map((name) => name.slice(0, -".lock".length))
+        .filter((id) => SESSION_ID_PATTERN.test(id));
+}
+
+/**
+ * Conversations this sweep must serialize with admission: every conversation it
+ * has a run record for, plus every retained and leased one. Admission for a
+ * conversation always has either the run record of the attempt it continues or
+ * the writer lease it just took, so history that resolves to none of these is
+ * foreign and keeps the ordinary, unserialized cleanup path.
+ */
+function serializedConversations(metas: readonly RunMeta[]): Set<string> {
+    const sessions = new Set<string>();
+    for (const meta of metas) sessions.add(meta.sessionId);
+    for (const sessionId of retainedSessionIds()) sessions.add(sessionId);
+    for (const sessionId of leasedSessionIds()) sessions.add(sessionId);
+    return sessions;
+}
+
+/**
+ * Run `body` inside one conversation's mutation transaction — the same
+ * kernel-owned critical section admission, lease release, and retention writes
+ * take. A lock that is busy or unavailable retains the resource for this sweep
+ * instead of blocking the foreground, stalling forever, or failing every other
+ * deletion: keeping work is always the safe direction.
+ */
+function withConversationSerialization<T>(
+    sessionId: string | undefined,
+    body: () => T,
+    retained: () => T,
+): T {
+    if (!sessionId || !SESSION_ID_PATTERN.test(sessionId)) return body();
+    try {
+        return withConversationMutation(sessionId, body, { waitMs: CLEANUP_LOCK_WAIT_MS });
+    } catch (error) {
+        if (error instanceof ConversationBusyError || error instanceof ConversationLockUnavailableError) {
+            return retained();
+        }
+        throw error;
+    }
+}
+
+/**
+ * Is this conversation provably quiescent right now?
+ *
+ * Snapshot occupancy is not proof. Between the snapshot and a removal another
+ * process can publish a writer lease, re-request retention, or re-write an
+ * attempt, so this re-reads the same evidence inside the conversation's
+ * mutation transaction: a successful admission can therefore only be seen here
+ * (and retained) or happen after the removal it now follows.
+ *
+ * A brand-new attempt of the same conversation is admitted only under that
+ * conversation's lease, so re-reading the lease also covers an attempt this
+ * sweep has never seen in its snapshot.
+ */
+function conversationQuiescentUnderLock(sessionId: string, runIds: readonly string[]): boolean {
+    if (leaseMayHaveWriter(sessionId)) return false;
+    const retention = readRetention(sessionId);
+    if (retention && retention.releasedAt === undefined) return false;
+    for (const id of runIds) {
+        const meta = readMeta(id);
+        if (meta && recordedChildMayWrite(meta)) return false;
+    }
+    return true;
+}
+
+/** Paths whose removal follows this run's artifacts (see `removeMetaArtifacts`). */
+function ownedResources(meta: RunMeta): string[] {
+    return meta.taskScratch ? [meta.cwd, meta.taskScratch] : [meta.cwd];
+}
+
+function cleanRunDirs(cutoff: number, scope: CleanupScope, errors: string[]): number {
     let removed = 0;
     let ids: string[];
     try {
@@ -198,15 +447,18 @@ function cleanRunDirs(cutoff: number, errors: string[]): number {
     } catch {
         return 0;
     }
+    // Explicit retention (`retain_session`) pins every attempt of a
+    // conversation, not just the attempt that requested it, so its saved
+    // session and owned clone/scratch workspace stay available for a
+    // continuation until the owner releases them.
+    const retained = retainedSessionIds();
 
     for (const id of ids) {
         const dir = runDir(id);
         const meta = readMeta(id);
         if (meta) {
-            if (!TERMINAL_CLEANUP_STATUSES.has(meta.status)) continue;
-            if (terminalTimestamp(meta) >= cutoff) continue;
-            if (removeMetaArtifacts(meta)) removed += 1;
-            else errors.push(`${dir}: could not remove run artifacts`);
+            if (!ageSweepEligible(meta, cutoff, retained, scope.occupancy)) continue;
+            if (removeAgedRunArtifacts(meta, cutoff, retained, scope, errors)) removed += 1;
             continue;
         }
 
@@ -218,11 +470,111 @@ function cleanRunDirs(cutoff: number, errors: string[]): number {
     return removed;
 }
 
-function activeSessionIds(metas: RunMeta[]): Set<string> {
-    const active = new Set<string>();
+/**
+ * Snapshot eligibility for the age bound. Re-applied to the fresh record inside
+ * the conversation's lock, because a record can be rewritten between the two:
+ * a run that finished later, or one another sweep already retired, is decided
+ * on what it says now.
+ */
+function ageSweepEligible(
+    meta: RunMeta,
+    cutoff: number,
+    retained: ReadonlySet<string>,
+    occupancy: CleanupOccupancy,
+): boolean {
+    if (!TERMINAL_CLEANUP_STATUSES.has(meta.status)) return false;
+    if (retained.has(meta.sessionId)) return false;
+    // A released conversation can still be in use: a later attempt may run
+    // inside this root's clone, or a stop/kill may not have landed.
+    if (occupancy.runIds.has(meta.id)) return false;
+    return terminalTimestamp(meta) < cutoff;
+}
+
+/**
+ * Remove one aged attempt's artifacts, serialized with its conversation.
+ *
+ * This is the deletion the snapshot cannot authorize: an admission that
+ * published its writer lease after this sweep listed the registry would have
+ * its shared workspace, task scratch, and saved history removed underneath it.
+ * The recheck inside the lock sees that admission, so the attempt is retained.
+ *
+ * The removal itself is inside the transaction because it is the commit point:
+ * `removeMetaArtifacts` unlinks the shared workspace, and splitting the
+ * decision from that unlink would reopen the race. A conversation whose lock is
+ * held by an admission or a retention write is therefore retained for this
+ * sweep, and the holder's own bounded wait is what bounds this section.
+ */
+function removeAgedRunArtifacts(
+    meta: RunMeta,
+    cutoff: number,
+    retained: ReadonlySet<string>,
+    scope: CleanupScope,
+    errors: string[],
+): boolean {
+    const runIds = scope.runIdsBySession.get(meta.sessionId) ?? [meta.id];
+    return withConversationSerialization(meta.sessionId, () => {
+        if (!conversationQuiescentUnderLock(meta.sessionId, runIds)) return false;
+        const fresh = readMeta(meta.id) ?? meta;
+        if (!ageSweepEligible(fresh, cutoff, retained, scope.occupancy)) return false;
+        if (removeMetaArtifacts(fresh)) return true;
+        errors.push(`${runDir(meta.id)}: could not remove run artifacts`);
+        return false;
+    }, () => false);
+}
+
+/**
+ * Conversation a session-tree path names, resolved against conversations this
+ * sweep tracks: the per-run session directory `<runId>/`, a
+ * `<timestamp>_<sessionId>.jsonl` name, or the bare conversation name. History
+ * that resolves to nothing this sweep knows stays on the ordinary path.
+ */
+function sessionIdForPath(path: string, serialized: ReadonlySet<string>): string | undefined {
+    const rel = relative(sessionsDir(), path);
+    if (!rel || rel.startsWith("..")) return undefined;
+    const known = [...new Set(pathNameCandidates(rel.split(sep)))].filter((candidate) => serialized.has(candidate));
+    // Two different tracked conversations in one path is not a layout this
+    // package writes. Refusing to remove it keeps both, instead of serializing
+    // one and deleting under the other.
+    return known.length === 1 ? known[0] : undefined;
+}
+
+function* pathNameCandidates(parts: readonly string[]): Generator<string> {
+    yield parts[0]!; // per-run session directory
+    const name = parts[parts.length - 1]!;
+    const stem = name.endsWith(".jsonl") ? name.slice(0, -".jsonl".length) : name;
+    yield stem;
+    // `<timestamp>_<sessionId>.jsonl`: the timestamp carries no underscore.
+    const separator = stem.indexOf("_");
+    if (separator > 0) yield stem.slice(separator + 1);
+}
+
+/**
+ * Remove one aged session-tree entry, serialized with the conversation it names
+ * when this sweep tracks that conversation.
+ */
+function removeSessionPath(
+    path: string,
+    serialized: ReadonlySet<string>,
+    scope: CleanupScope,
+    errors: string[],
+): boolean {
+    const sessionId = sessionIdForPath(path, serialized);
+    if (!sessionId) return removePath(path, errors);
+    const runIds = scope.runIdsBySession.get(sessionId) ?? [];
+    return withConversationSerialization(sessionId, () => {
+        if (!conversationQuiescentUnderLock(sessionId, runIds)) return false;
+        return removePath(path, errors);
+    }, () => false);
+}
+
+function activeSessionIds(metas: RunMeta[], occupancy: CleanupOccupancy): Set<string> {
+    const active = new Set<string>(occupancy.sessions);
     for (const meta of metas) {
         if (meta.status === "running" || meta.status === "orphaned") active.add(meta.sessionId);
     }
+    // A retained completed conversation is not active work, but its saved
+    // session file is the history a continuation reopens.
+    for (const sessionId of retainedSessionIds()) active.add(sessionId);
     return active;
 }
 
@@ -235,7 +587,14 @@ function pathMentionsActiveSession(path: string, active: Set<string>): boolean {
     return false;
 }
 
-function cleanSessionTree(cutoff: number, active: Set<string>, errors: string[]): number {
+function cleanSessionTree(
+    cutoff: number,
+    active: Set<string>,
+    protectedPaths: readonly string[],
+    scope: CleanupScope,
+    serialized: ReadonlySet<string>,
+    errors: string[],
+): number {
     const root = sessionsDir();
     if (!existsSync(root)) return 0;
     let removed = 0;
@@ -254,9 +613,11 @@ function cleanSessionTree(cutoff: number, active: Set<string>, errors: string[])
             const path = join(dir, entry.name);
             if (entry.isDirectory()) {
                 const childEmpty = visit(path);
-                if (childEmpty && !pathMentionsActiveSession(path, active)) {
+                if (childEmpty
+                    && !pathMentionsActiveSession(path, active)
+                    && !pathOverlapsProtected(path, protectedPaths)) {
                     const mtimeMs = safeStatMtime(path);
-                    if (mtimeMs !== undefined && mtimeMs < cutoff && removePath(path, errors)) {
+                    if (mtimeMs !== undefined && mtimeMs < cutoff && removeSessionPath(path, serialized, scope, errors)) {
                         removed += 1;
                         continue;
                     }
@@ -265,12 +626,12 @@ function cleanSessionTree(cutoff: number, active: Set<string>, errors: string[])
                 continue;
             }
 
-            if (pathMentionsActiveSession(path, active)) {
+            if (pathMentionsActiveSession(path, active) || pathOverlapsProtected(path, protectedPaths)) {
                 empty = false;
                 continue;
             }
             const mtimeMs = safeStatMtime(path);
-            if (mtimeMs !== undefined && mtimeMs < cutoff && removePath(path, errors)) {
+            if (mtimeMs !== undefined && mtimeMs < cutoff && removeSessionPath(path, serialized, scope, errors)) {
                 removed += 1;
                 continue;
             }
@@ -295,8 +656,19 @@ export function runDailyCleanupOnce(options: DailyCleanupOptions = {}): DailyCle
     const terminalRetention = retentionMs(options.terminalRunRetentionMs, options.config?.cleanupTerminalRunRetentionMs);
     const sessionRetention = retentionMs(options.sessionRetentionMs, options.config?.cleanupSessionRetentionMs);
     const metas = listMetas();
-    const removedRunDirs = cleanRunDirs(now - terminalRetention, errors);
-    const removedSessionPaths = cleanSessionTree(now - sessionRetention, activeSessionIds(metas), errors);
+    const scope: CleanupScope = {
+        occupancy: planCleanupOccupancy(metas, options.protect),
+        runIdsBySession: runIdsBySession(metas),
+    };
+    const removedRunDirs = cleanRunDirs(now - terminalRetention, scope, errors);
+    const removedSessionPaths = cleanSessionTree(
+        now - sessionRetention,
+        activeSessionIds(metas, scope.occupancy),
+        scope.occupancy.paths,
+        scope,
+        serializedConversations(metas),
+        errors,
+    );
 
     try {
         writeCleanupState({ lastLocalDate: dateKey, lastRunAt: now });
@@ -361,6 +733,8 @@ export interface SizeCapOptions {
     /** Bypass the interval marker (tests, explicit operator sweeps). */
     force?: boolean;
     protectedIds?: ReadonlySet<string>;
+    /** Same caller-owned protection as `DailyCleanupOptions.protect`. */
+    protect?: CleanupProtection;
 }
 
 /**
@@ -393,14 +767,38 @@ export function enforceRegistrySizeCapOnce(options: SizeCapOptions = {}): SizeCa
         ?? (Number.isFinite(configured) && configured! > 0 ? configured! : DEFAULT_MAX_REGISTRY_BYTES);
 
     const errors: string[] = [];
-    const protectedIds = options.protectedIds ?? ownRunIds();
-    const plan = planRegistrySizeCap(collectSizeCapEntries(), { maxBytes, protectedIds });
+    const entries = collectSizeCapEntries();
+    // Retained conversations and their workspaces are exempt from the byte
+    // bound until the owner releases them; a size sweep must not delete the
+    // history or uncommitted workspace a continuation depends on. An occupied
+    // conversation is protected the same way: its root clone may be the oldest
+    // terminal run in the registry while a new attempt is still running in it.
+    // Occupancy costs a metadata scan and lease reads, so it is only computed
+    // when this sweep would actually remove something.
+    const totalBytes = entries.reduce((sum, entry) => sum + entry.bytes, 0);
+    const metas = listMetas();
+    const occupancy = totalBytes > maxBytes ? planCleanupOccupancy(metas, options.protect) : undefined;
+    const protectedIds = new Set([
+        ...(options.protectedIds ?? ownRunIds(metas)),
+        ...retainedRunIds(metas),
+        ...(occupancy?.runIds ?? []),
+    ]);
+    const plan = planRegistrySizeCap(entries, { maxBytes, protectedIds });
+    const scope: CleanupScope = {
+        occupancy: occupancy ?? { sessions: new Set(), runIds: new Set(), paths: [] },
+        runIdsBySession: runIdsBySession(metas),
+    };
+    const bytesById = new Map(entries.map((entry) => [entry.id, entry.bytes]));
     const removed: string[] = [];
+    let retainedBytes = 0;
     for (const id of plan.remove) {
-        const meta = readMeta(id);
-        if (meta ? removeMetaArtifacts(meta) : removeRun(id, errors)) removed.push(id);
-        else if (meta) errors.push(`${runDir(id)}: could not remove run artifacts`);
+        const outcome = removeSizeCappedRun(id, scope, errors);
+        if (outcome === "removed") removed.push(id);
+        else if (outcome === "retained") retainedBytes += bytesById.get(id) ?? 0;
     }
+    // A candidate the recheck retained is still on disk, so the byte account and
+    // the shortfall it reports stay honest.
+    const keptBytes = plan.keptBytes + retainedBytes;
 
     try {
         writeCleanupState({ ...state, lastSizeSweepAt: now });
@@ -408,14 +806,41 @@ export function enforceRegistrySizeCapOnce(options: SizeCapOptions = {}): SizeCa
         errors.push(`${cleanupStatePath()}: ${err instanceof Error ? err.message : String(err)}`);
     }
 
-    return { ...plan, ran: true, removed, errors };
+    return { ...plan, ran: true, removed, keptBytes, overBudget: keptBytes > maxBytes, errors };
+}
+
+/**
+ * Remove one planned size-cap candidate, serialized with its conversation.
+ *
+ * The plan is a snapshot of both bytes and occupancy. Re-reading inside the
+ * lock keeps a run that became active, retained, or newly leased since then:
+ * a continuation admitted after planning runs inside the root the plan chose to
+ * delete, and its shared workspace is exactly what a size sweep goes after.
+ */
+function removeSizeCappedRun(
+    id: string,
+    scope: CleanupScope,
+    errors: string[],
+): "removed" | "retained" | "failed" {
+    const meta = readMeta(id);
+    if (!meta) return removeRun(id, errors) ? "removed" : "failed";
+    const runIds = scope.runIdsBySession.get(meta.sessionId) ?? [meta.id];
+    return withConversationSerialization(meta.sessionId, () => {
+        if (!conversationQuiescentUnderLock(meta.sessionId, runIds)) return "retained";
+        const fresh = readMeta(id) ?? meta;
+        if (!TERMINAL_CLEANUP_STATUSES.has(fresh.status)) return "retained";
+        if (scope.occupancy.runIds.has(fresh.id)) return "retained";
+        if (removeMetaArtifacts(fresh)) return "removed";
+        errors.push(`${runDir(id)}: could not remove run artifacts`);
+        return "failed";
+    }, () => "retained");
 }
 
 /** Run ids owned by this pi process, which a size sweep must never remove. */
-function ownRunIds(): Set<string> {
+function ownRunIds(metas: readonly RunMeta[] = listMetas()): Set<string> {
     const own = new Set<string>();
     try {
-        for (const meta of listMetas()) {
+        for (const meta of metas) {
             if (ownedByThisParent(meta)) own.add(meta.id);
         }
     } catch { /* registry unreadable: protect nothing, remove nothing new */ }