@bermudi/pi-delegate 0.1.4 → 0.1.7

package/dispatch.ts

@@ -293,7 +293,6 @@ export function dispatchAsync(input: AsyncDispatchInput): DelegateToolResult {
   const asyncEnv: TaskRunEnv = {
     signal: ticketSignal,
     modelRegistry,
-    parentSessionManager: ctx.sessionManager,
     ticketId,
     delegateStartedAt: ticket.created,
     telemetryCallId: callSpan?.id,
@@ -426,7 +425,6 @@ export async function dispatchSync(
   const syncEnv: TaskRunEnv = {
     signal,
     modelRegistry: ctx.modelRegistry,
-    parentSessionManager: ctx.sessionManager,
     ticketId: undefined,
     delegateStartedAt: startedAt,
     telemetryCallId: callSpan?.id,

package/lifecycle.ts

@@ -18,7 +18,6 @@ import { isSessionBusy } from "./tickets.ts";
 import {
   createSubagentSessionManager,
   persistSessionHeader,
-  setParentSession,
 } from "./sessions.ts";
 import { runAgentSession, formatDeadlineExceededError } from "./runner.ts";
 import { getGitChangedFiles } from "./file-tracking.ts";
@@ -329,8 +328,8 @@ async function sleepForWholeTaskRetry(
 }
 
 /** Build the AgentSession for a fresh or resumed subagent via createAgentSession.
- *  Reuses the caller-supplied sessionManager (so parent-linking + per-task .jsonl
- *  files stay under our control). Extension-free host deps may be cached, while
+ *  Reuses the caller-supplied sessionManager (so per-task .jsonl files stay under
+ *  our control). Extension-free host deps may be cached, while
  *  provider-configured or allowlisted-extension deps are session-local because
  *  Pi binds mutable extension callbacks onto each loader runtime. */
 async function buildDelegateSession(
@@ -484,10 +483,6 @@ async function acquireAgentSession(
       };
     }
 
-    // Link resumed session to parent for /resume discoverability.
-    const parentFile = env.parentSessionManager?.getSessionFile?.();
-    if (parentFile) setParentSession(resumed, parentFile);
-
     const session = await buildDelegateSession(
       task,
       resumed,
@@ -508,10 +503,7 @@ async function acquireAgentSession(
     // isolation. Keep scratch transcripts in memory only.
     sessionManager = SessionManager.inMemory(task.cwd);
   } else {
-    const fresh = createSubagentSessionManager(
-      env.parentSessionManager,
-      task.cwd,
-    );
+    const fresh = createSubagentSessionManager(task.cwd);
     if (!fresh) {
       return {
         error: failTask(task, "Internal: could not create session file"),

package/migrate-delegate-sessions.ts

@@ -0,0 +1,202 @@
+/**
+ * Move old pi-delegate sessions out of Pi's normal session index.
+ *
+ * This is intentionally a standalone migration, not extension startup code:
+ * `pi -r` indexes sessions before extensions are loaded.
+ *
+ * Usage:
+ *   bun run migrate-delegate-sessions.ts          # report only
+ *   bun run migrate-delegate-sessions.ts --apply  # unlink and move
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+
+type JsonObject = Record<string, unknown>;
+
+const agentDir = getAgentDir();
+const sourceDir = path.join(agentDir, "sessions");
+const destinationDir = path.join(agentDir, "delegate-sessions");
+const apply = process.argv.includes("--apply");
+
+function isObject(value: unknown): value is JsonObject {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isWithin(root: string, candidate: string): boolean {
+  const relative = path.relative(root, candidate);
+  return (
+    relative === "" ||
+    (!relative.startsWith(`..${path.sep}`) &&
+      relative !== ".." &&
+      !path.isAbsolute(relative))
+  );
+}
+
+function readSession(file: string): JsonObject[] | undefined {
+  try {
+    const lines = fs.readFileSync(file, "utf8").split(/\r?\n/);
+    const entries: JsonObject[] = [];
+    for (const line of lines) {
+      if (!line.trim()) continue;
+      const parsed: unknown = JSON.parse(line);
+      if (!isObject(parsed)) return undefined;
+      entries.push(parsed);
+    }
+    return entries;
+  } catch {
+    return undefined;
+  }
+}
+
+function readSessionHeader(file: string): JsonObject | undefined {
+  try {
+    const firstLine = fs.readFileSync(file, "utf8").split(/\r?\n/, 1)[0];
+    const parsed: unknown = JSON.parse(firstLine);
+    return isObject(parsed) && parsed.type === "session" ? parsed : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function sessionHeader(entries: JsonObject[]): JsonObject | undefined {
+  const header = entries[0];
+  return header?.type === "session" ? header : undefined;
+}
+
+function entryKey(entry: JsonObject): string {
+  return JSON.stringify(entry);
+}
+
+/**
+ * Pi's forkFrom() copies every non-header entry from the source session before
+ * writing anything new. Old delegate sessions do not copy the parent history.
+ * This is the discriminator: parentSession by itself is deliberately not
+ * sufficient because genuine Pi forks also have it.
+ */
+function isPiFork(
+  childEntries: JsonObject[],
+  parentEntries: JsonObject[],
+): boolean {
+  const childBody = childEntries.slice(1);
+  const parentBody = parentEntries.slice(1);
+  if (parentBody.length === 0 || childBody.length < parentBody.length) {
+    return false;
+  }
+  return parentBody.every(
+    (entry, index) => entryKey(entry) === entryKey(childBody[index]),
+  );
+}
+
+function findJsonlFiles(directory: string): string[] {
+  if (!fs.existsSync(directory)) return [];
+  const files: string[] = [];
+  const visit = (current: string): void => {
+    for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+      const candidate = path.join(current, entry.name);
+      if (entry.isDirectory()) visit(candidate);
+      else if (entry.isFile() && entry.name.endsWith(".jsonl"))
+        files.push(candidate);
+    }
+  };
+  visit(directory);
+  return files;
+}
+
+interface MigrationCandidate {
+  source: string;
+  destination: string;
+}
+
+const candidates: MigrationCandidate[] = [];
+let skipped = 0;
+const parentCache = new Map<string, JsonObject[] | undefined>();
+
+for (const file of findJsonlFiles(sourceDir)) {
+  const header = readSessionHeader(file);
+  const parent = header?.parentSession;
+  if (!header || typeof parent !== "string") continue;
+
+  const parentPath = path.resolve(parent);
+  if (!isWithin(sourceDir, parentPath) || !fs.existsSync(parentPath)) {
+    skipped++;
+    console.warn(`skip (parent unavailable): ${file}`);
+    continue;
+  }
+
+  let parentEntries = parentCache.get(parentPath);
+  if (parentEntries === undefined && !parentCache.has(parentPath)) {
+    parentEntries = readSession(parentPath);
+    parentCache.set(parentPath, parentEntries);
+  }
+  const entries = readSession(file);
+  if (!entries) {
+    skipped++;
+    console.warn(`skip (invalid session): ${file}`);
+    continue;
+  }
+  if (!parentEntries || isPiFork(entries, parentEntries)) continue;
+
+  const relative = path.relative(sourceDir, file);
+  candidates.push({
+    source: file,
+    destination: path.join(destinationDir, relative),
+  });
+}
+
+console.log(
+  `${apply ? "Migrating" : "Found"} ${candidates.length} delegate session(s); ` +
+    `${skipped} skipped because their parent could not be verified.`,
+);
+
+if (!apply) {
+  for (const candidate of candidates) {
+    console.log(`would move: ${candidate.source} -> ${candidate.destination}`);
+  }
+  console.log("Nothing changed. Re-run with --apply to perform the migration.");
+  process.exit(0);
+}
+
+let moved = 0;
+for (const candidate of candidates) {
+  const entries = readSession(candidate.source);
+  const header = entries && sessionHeader(entries);
+  if (!entries || !header) {
+    console.warn(`skip (changed during migration): ${candidate.source}`);
+    continue;
+  }
+
+  delete header.parentSession;
+  const parent = path.dirname(candidate.destination);
+  fs.mkdirSync(parent, { recursive: true });
+
+  const temporary = `${candidate.source}.delegate-migration-${process.pid}.tmp`;
+  try {
+    if (fs.existsSync(candidate.destination)) {
+      throw new Error("destination already exists");
+    }
+    fs.writeFileSync(
+      temporary,
+      `${entries.map((entry) => JSON.stringify(entry)).join("\n")}\n`,
+      { flag: "wx", mode: 0o600 },
+    );
+    fs.renameSync(temporary, candidate.source);
+    fs.renameSync(candidate.source, candidate.destination);
+    console.log(`moved: ${candidate.source} -> ${candidate.destination}`);
+    moved++;
+  } catch (error) {
+    try {
+      if (fs.existsSync(temporary)) fs.unlinkSync(temporary);
+    } catch {
+      // Preserve the original error below; the temp file is harmless and
+      // uniquely named for this process.
+    }
+    console.error(
+      `failed: ${candidate.source}: ${
+        error instanceof Error ? error.message : String(error)
+      }`,
+    );
+  }
+}
+
+console.log(`Moved ${moved}/${candidates.length} delegate session(s).`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bermudi/pi-delegate",
-  "version": "0.1.4",
+  "version": "0.1.7",
   "description": "Delegate tool for the Pi coding agent.",
   "keywords": [
     "pi-package"

package/sessions.ts

@@ -1,67 +1,26 @@
 import * as fs from "node:fs";
-import { SessionManager } from "@earendil-works/pi-coding-agent";
+import { join } from "node:path";
+import { SessionManager, getAgentDir } from "@earendil-works/pi-coding-agent";
 
-/** Link a subagent session to its parent and persist the header when possible. */
-export function setParentSession(sm: SessionManager, parentPath: string): void {
-  const inner = sm as unknown as {
-    fileEntries: Array<{ type: string; parentSession?: string }>;
-    getSessionFile?: () => string | undefined;
-    _rewriteFile?: () => void;
-  };
-  const header = inner.fileEntries[0];
-  if (header && header.type === "session") {
-    header.parentSession = parentPath;
-    // For a *resumed* session the file already exists on disk and the manager
-    // is flushed (SessionManager.open/setSessionFile sets flushed=true). The
-    // in-memory header mutation above is otherwise lost: upstream _persist()
-    // only *appends* new entries once flushed — it never rewrites the header.
-    // So a resumeFrom session would never surface as a child in /resume despite
-    // the link being set in memory. Rewrite the whole file (header + entries)
-    // so the parentSession field is actually persisted. Fresh sessions skip
-    // this (file doesn't exist yet); their first _persist() writes the mutated
-    // header along with the rest, and rewriting early would trip the
-    // duplicate-header bug in _persist()'s not-yet-flushed path.
-    const file = inner.getSessionFile?.();
-    if (file && fs.existsSync(file)) {
-      try {
-        inner._rewriteFile?.();
-      } catch {
-        /* best effort — link stays in-memory; not fatal */
-      }
-    }
-  }
+/** Persistent storage for delegate-only conversations. */
+export function getDelegateSessionDir(): string {
+  return join(getAgentDir(), "delegate-sessions");
 }
 
 /**
  * Create a session manager for a subagent run.
  *
- * Always creates a standalone session file in the target cwd.
- * Sets `parentSession` in the header so subagent work is discoverable
- * as a child of the parent session in `/resume`.
- *
- * Returns the concrete `SessionManager` (ready to hand to `createAgentSession`)
- * and its file path (for result reporting + pool bookkeeping).
+ * Delegate sessions are deliberately standalone and live in their own
+ * directory. They are not attached to the parent's session tree.
  */
 export function createSubagentSessionManager(
-  parentSessionManager: unknown,
   cwd: string,
 ): { manager: SessionManager; file: string } | undefined {
-  // Resolve parent session file path for linking.
-  const parentFile = (
-    parentSessionManager as
-      { getSessionFile?(): string | undefined } | undefined
-  )?.getSessionFile?.();
-
-  // Always persist subagent work so the main agent can search it later.
-  const sm = SessionManager.create(cwd);
+  // Always persist subagent work separately from the parent's session tree.
+  const sm = SessionManager.create(cwd, getDelegateSessionDir());
   const sessionFile = sm.getSessionFile();
   if (!sessionFile) return undefined;
 
-  // Link to parent session so subagent appears as a child in /resume.
-  if (parentFile) {
-    setParentSession(sm, parentFile);
-  }
-
   return { manager: sm, file: sessionFile };
 }
 

package/types.ts

@@ -251,8 +251,6 @@ export interface TaskRunEnv {
   /** Abort signal — parent's for sync, ticket's for async. May be undefined when no parent signal is available. */
   signal: AbortSignal | undefined;
   modelRegistry: ModelRegistry;
-  /** Parent session manager — used to link subagent sessions for /resume. */
-  parentSessionManager: { getSessionFile?(): string | undefined } | undefined;
   /** Ticket id for busy-guard self-checks. undefined for sync. */
   ticketId?: string;
   /** When the delegate started. Used for close/list progress (elapsed time). */

package/workspace.ts

@@ -3,7 +3,9 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { scheduleDeadline } from "./timer.ts";
 
-const SCRATCH_PREFIX = ".pi-delegate-scratch-";
+const SCRATCH_CONTAINER_NAME = ".pi-delegate-scratch";
+const SCRATCH_LEASE_PREFIX = "lease-";
+const SCRATCH_LEGACY_PREFIX = ".pi-delegate-scratch-";
 const SCRATCH_TREE_NAME = "project";
 const SCRATCH_OWNER_NAME = ".owner";
 const COPY_TIMEOUT_MS = 5 * 60 * 1000;
@@ -36,6 +38,8 @@ export class ScratchSetupError extends Error {}
 
 export class ScratchDeadlineError extends ScratchSetupError {}
 
+class ScratchLeaseIdentityError extends Error {}
+
 class CommandError extends Error {
   constructor(
     message: string,
@@ -195,167 +199,381 @@ function isProcessAlive(pid: number): boolean {
   }
 }
 
+function sameFileIdentity(left: fs.Stats, right: fs.Stats): boolean {
+  // dev+ino alone can alias after an unlink+mkdir reuses the same inode
+  // (observed on ext4 in CI: project replaced in the sweep race test
+  // reused the previous ino). Birthtime distinguishes a recreated entry
+  // and is stable across the chmod 0500→0700 transitions that update
+  // ctime. Where birthtime is unavailable (0) we fall back to dev+ino.
+  if (left.dev !== right.dev || left.ino !== right.ino) return false;
+  if (left.birthtimeMs !== 0 || right.birthtimeMs !== 0) {
+    return left.birthtimeMs === right.birthtimeMs;
+  }
+  return true;
+}
+
+function parseOwnerPid(content: string): number | undefined {
+  const value = content.trim();
+  if (!/^[1-9][0-9]*$/.test(value)) return undefined;
+  const pid = Number(value);
+  return Number.isSafeInteger(pid) ? pid : undefined;
+}
+
+type LeaseDeletionExpectations =
+  | {
+      hasProject: true;
+      lease: fs.Stats;
+      project: fs.Stats;
+      owner: fs.Stats;
+    }
+  | {
+      hasProject: false;
+      lease: fs.Stats;
+      owner: fs.Stats;
+    };
+
+async function deleteLeaseContentsAndRmdir(
+  parentHandle: fs.promises.FileHandle,
+  leaseName: string,
+  leaseHandle: fs.promises.FileHandle,
+  expectations: LeaseDeletionExpectations,
+): Promise<void> {
+  const leasePath = path.join(`/proc/self/fd/${parentHandle.fd}`, leaseName);
+  const openLeaseStat = await leaseHandle.stat();
+  const currentLeaseStat = await fs.promises.lstat(leasePath);
+  if (
+    !openLeaseStat.isDirectory() ||
+    !sameFileIdentity(openLeaseStat, expectations.lease) ||
+    !sameFileIdentity(currentLeaseStat, openLeaseStat)
+  ) {
+    throw new ScratchLeaseIdentityError(
+      "Scratch lease was moved or replaced; refusing cleanup.",
+    );
+  }
+
+  await leaseHandle.chmod(0o700);
+  const ownerPath = path.join(
+    `/proc/self/fd/${leaseHandle.fd}`,
+    SCRATCH_OWNER_NAME,
+  );
+  const initialOwnerStat = await fs.promises.lstat(ownerPath);
+  if (!sameFileIdentity(initialOwnerStat, expectations.owner)) {
+    throw new ScratchLeaseIdentityError(
+      "Scratch owner marker was replaced; refusing cleanup.",
+    );
+  }
+
+  if (expectations.hasProject) {
+    const projectPath = path.join(
+      `/proc/self/fd/${leaseHandle.fd}`,
+      SCRATCH_TREE_NAME,
+    );
+    const projectHandle = await fs.promises.open(
+      projectPath,
+      fs.constants.O_RDONLY | fs.constants.O_DIRECTORY,
+    );
+    try {
+      const openProjectStat = await projectHandle.stat();
+      const currentProjectStat = await fs.promises.lstat(projectPath);
+      if (
+        !openProjectStat.isDirectory() ||
+        !sameFileIdentity(openProjectStat, expectations.project) ||
+        !sameFileIdentity(currentProjectStat, openProjectStat)
+      ) {
+        throw new ScratchLeaseIdentityError(
+          "Scratch project was moved or replaced; refusing cleanup.",
+        );
+      }
+
+      // Remove children through the opened project directory, not the project
+      // pathname.  This means a replacement at `project` is never recursively
+      // traversed.  The final rmdir is still a pathname operation; the identity
+      // is checked again immediately beforehand, so this is fail-closed for
+      // the deterministic replacement races we can observe, not an atomic
+      // guarantee against a cooperating same-user process.
+      for (const name of await fs.promises.readdir(
+        `/proc/self/fd/${projectHandle.fd}`,
+      )) {
+        await fs.promises.rm(
+          path.join(`/proc/self/fd/${projectHandle.fd}`, name),
+          { recursive: true, force: false },
+        );
+      }
+      const finalProjectStat = await fs.promises.lstat(projectPath);
+      if (!sameFileIdentity(finalProjectStat, openProjectStat)) {
+        throw new ScratchLeaseIdentityError(
+          "Scratch project was moved or replaced; refusing cleanup.",
+        );
+      }
+      await fs.promises.rmdir(projectPath);
+    } finally {
+      await projectHandle.close();
+    }
+  }
+
+  const currentOwnerStat = await fs.promises.lstat(ownerPath);
+  if (!sameFileIdentity(currentOwnerStat, expectations.owner)) {
+    throw new ScratchLeaseIdentityError(
+      "Scratch owner marker was replaced; refusing cleanup.",
+    );
+  }
+  await fs.promises.rm(ownerPath, { force: false });
+
+  const finalLeaseStat = await fs.promises.lstat(leasePath);
+  if (!sameFileIdentity(finalLeaseStat, openLeaseStat)) {
+    throw new ScratchLeaseIdentityError(
+      "Scratch lease was moved or replaced; refusing cleanup.",
+    );
+  }
+  await fs.promises.rmdir(leasePath);
+}
+
+async function ensureScratchContainer(
+  containerDir: string,
+  uid: number | undefined,
+): Promise<void> {
+  try {
+    await fs.promises.mkdir(containerDir, { mode: 0o700 });
+    await fs.promises.chmod(containerDir, 0o700);
+    return;
+  } catch (error) {
+    if (!(
+      error instanceof Error &&
+      "code" in error &&
+      error.code === "EEXIST"
+    )) {
+      throw error;
+    }
+  }
+
+  const stat = await fs.promises.lstat(containerDir);
+  if (!stat.isDirectory() || (uid !== undefined && stat.uid !== uid)) {
+    throw new ScratchSetupError(
+      `Scratch container directory '${containerDir}' is not a directory owned by the current user.`,
+    );
+  }
+  if ((stat.mode & 0o7777) !== 0o700) {
+    await fs.promises.chmod(containerDir, 0o700);
+  }
+}
+
+interface SweepOptions {
+  prefix?: string;
+  onLeaseOpened?: (leaseName: string, leaseFd: number) => Promise<void> | void;
+  onLeaseValidated?: (leaseName: string) => Promise<void> | void;
+}
+
 /** Remove leases left behind by a process that is no longer running.
  *
  * The owner marker distinguishes our leases from unrelated prefix-matching
- * directories. Live owners are never touched. The final removal still goes
- * through opened descriptors and a non-recursive rmdir, so a replacement or
- * active workspace fails closed.
+ * directories. Live owners are never touched. Descriptors make the scan
+ * independent of a renamed parent, while pathname identity checks ensure that
+ * a lease renamed or replaced after it was opened is left alone. These checks
+ * are snapshots rather than an atomic cross-process locking primitive.
  */
-async function sweepStaleScratchLeases(parent: string): Promise<void> {
+async function sweepStaleScratchLeases(
+  container: string,
+  options: SweepOptions = {},
+): Promise<void> {
   const uid = process.getuid?.();
   if (uid === undefined) return;
 
-  let entries: fs.Dirent[];
+  let parentHandle: fs.promises.FileHandle;
   try {
-    entries = await fs.promises.readdir(parent, { withFileTypes: true });
-  } catch (error) {
-    console.error("[delegate] scratch lease sweep failed", error);
+    parentHandle = await fs.promises.open(
+      container,
+      fs.constants.O_RDONLY | fs.constants.O_DIRECTORY,
+    );
+  } catch {
     return;
   }
 
-  for (const entry of entries) {
-    if (!entry.name.startsWith(SCRATCH_PREFIX) || !entry.isDirectory()) {
-      continue;
-    }
-    const leaseRoot = path.join(parent, entry.name);
+  try {
+    const parentStat = await parentHandle.stat();
+    if (!parentStat.isDirectory() || parentStat.uid !== uid) return;
+
+    let entries: fs.Dirent[];
     try {
-      const leaseStat = await fs.promises.lstat(leaseRoot);
-      if (!leaseStat.isDirectory() || leaseStat.uid !== uid) continue;
-      const contents = await fs.promises.readdir(leaseRoot);
-      if (!contents.includes(SCRATCH_OWNER_NAME)) {
-        // Empty leases from versions without an owner marker are still safe
-        // to reclaim; anything else may be an unrelated directory.
-        if (contents.length === 0) await fs.promises.rmdir(leaseRoot);
-        continue;
-      }
-      const ownerPath = path.join(leaseRoot, SCRATCH_OWNER_NAME);
-      const ownerStat = await fs.promises.lstat(ownerPath);
-      if (
-        !ownerStat.isFile() ||
-        ownerStat.uid !== uid ||
-        ownerStat.mode & 0o077
-      ) {
-        continue;
-      }
-      const pid = Number.parseInt(
-        (await fs.promises.readFile(ownerPath, "utf8")).trim(),
-        10,
-      );
-      if (!Number.isSafeInteger(pid) || isProcessAlive(pid)) {
-        continue;
-      }
+      entries = await fs.promises.readdir(`/proc/self/fd/${parentHandle.fd}`, {
+        withFileTypes: true,
+      });
+    } catch (error) {
+      console.error("[delegate] scratch lease sweep failed", error);
+      return;
+    }
 
-      const projectRoot = path.join(leaseRoot, SCRATCH_TREE_NAME);
-      if (
-        contents.some(
-          (name) => name !== SCRATCH_OWNER_NAME && name !== SCRATCH_TREE_NAME,
-        )
-      ) {
-        continue;
-      }
-      let projectStat: fs.Stats | undefined;
-      try {
-        projectStat = await fs.promises.lstat(projectRoot);
-        if (!projectStat.isDirectory()) continue;
-      } catch (error) {
-        if (!(
-          error instanceof Error &&
-          "code" in error &&
-          error.code === "ENOENT"
-        )) {
-          throw error;
-        }
-      }
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      if (options.prefix && !entry.name.startsWith(options.prefix)) continue;
 
-      // Open the parent and lease before removing anything. This repeats the
-      // same identity checks as normal cleanup against the directory found by
-      // the initial scan, rather than trusting a pathname that may be replaced.
-      const parentHandle = await fs.promises.open(
-        parent,
-        fs.constants.O_RDONLY | fs.constants.O_DIRECTORY,
-      );
-      let leaseHandle: Awaited<ReturnType<typeof fs.promises.open>> | undefined;
-      let projectHandle:
-        Awaited<ReturnType<typeof fs.promises.open>> | undefined;
+      let leaseHandle: fs.promises.FileHandle | undefined;
       try {
+        const leasePath = path.join(
+          `/proc/self/fd/${parentHandle.fd}`,
+          entry.name,
+        );
         leaseHandle = await fs.promises.open(
-          path.join(`/proc/self/fd/${parentHandle.fd}`, entry.name),
+          leasePath,
           fs.constants.O_RDONLY | fs.constants.O_DIRECTORY,
         );
-        const currentLeaseStat = await fs.promises.lstat(leaseRoot);
-        const openLeaseStat = await leaseHandle.stat();
+        const openedLeaseStat = await leaseHandle.stat();
+        const scannedLeaseStat = await fs.promises.lstat(leasePath);
         if (
-          currentLeaseStat.dev !== leaseStat.dev ||
-          currentLeaseStat.ino !== leaseStat.ino ||
-          openLeaseStat.dev !== leaseStat.dev ||
-          openLeaseStat.ino !== leaseStat.ino
+          !openedLeaseStat.isDirectory() ||
+          openedLeaseStat.uid !== uid ||
+          !sameFileIdentity(scannedLeaseStat, openedLeaseStat)
         ) {
           continue;
         }
-        const currentOwnerPath = path.join(
+
+        // Snapshot the identities before the test hook / concurrent work. If
+        // either pathname changes, the opened descriptor is not used for
+        // deletion. In particular, a rename must not turn this into cleanup of
+        // a lease that merely moved elsewhere.
+        const ownerPath = path.join(
           `/proc/self/fd/${leaseHandle.fd}`,
           SCRATCH_OWNER_NAME,
         );
-        const currentOwnerStat = await fs.promises.lstat(currentOwnerPath);
-        const currentPid = Number.parseInt(
-          (await fs.promises.readFile(currentOwnerPath, "utf8")).trim(),
-          10,
-        );
+        let scannedOwnerStat: fs.Stats;
+        try {
+          scannedOwnerStat = await fs.promises.lstat(ownerPath);
+        } catch (error) {
+          if (
+            error instanceof Error &&
+            "code" in error &&
+            error.code === "ENOENT"
+          ) {
+            // Leases from versions without an owner marker, or partial leases
+            // from a crash between mkdtemp and the marker write: reclaim only
+            // when empty. Anything else may be an unrelated directory. The
+            // identity re-check keeps the rmdir anchored to the scanned lease.
+            const contents = await fs.promises.readdir(
+              `/proc/self/fd/${leaseHandle.fd}`,
+            );
+            if (contents.length === 0) {
+              const currentLeaseStat = await fs.promises.lstat(leasePath);
+              if (sameFileIdentity(currentLeaseStat, scannedLeaseStat)) {
+                await fs.promises.rmdir(leasePath);
+              }
+            }
+            continue;
+          }
+          throw error;
+        }
+        let scannedProjectStat: fs.Stats | undefined;
+        try {
+          scannedProjectStat = await fs.promises.lstat(
+            path.join(`/proc/self/fd/${leaseHandle.fd}`, SCRATCH_TREE_NAME),
+          );
+        } catch (error) {
+          if (!(
+            error instanceof Error &&
+            "code" in error &&
+            error.code === "ENOENT"
+          )) {
+            throw error;
+          }
+        }
+
+        if (options.onLeaseOpened) {
+          await options.onLeaseOpened(entry.name, leaseHandle.fd);
+        }
+
+        const currentLeaseStat = await fs.promises.lstat(leasePath);
+        if (!sameFileIdentity(currentLeaseStat, scannedLeaseStat)) continue;
+        const currentOwnerStat = await fs.promises.lstat(ownerPath);
+        if (!sameFileIdentity(currentOwnerStat, scannedOwnerStat)) continue;
+        if (scannedProjectStat) {
+          const currentProjectStat = await fs.promises.lstat(
+            path.join(`/proc/self/fd/${leaseHandle.fd}`, SCRATCH_TREE_NAME),
+          );
+          if (!sameFileIdentity(currentProjectStat, scannedProjectStat)) {
+            continue;
+          }
+        }
+
         if (
           !currentOwnerStat.isFile() ||
           currentOwnerStat.uid !== uid ||
-          currentOwnerStat.dev !== ownerStat.dev ||
-          currentOwnerStat.ino !== ownerStat.ino ||
-          !Number.isSafeInteger(currentPid) ||
-          isProcessAlive(currentPid)
+          (currentOwnerStat.mode & 0o077) !== 0
         ) {
           continue;
         }
-        if (projectStat) {
-          projectHandle = await fs.promises.open(
-            path.join(`/proc/self/fd/${leaseHandle.fd}`, SCRATCH_TREE_NAME),
-            fs.constants.O_RDONLY | fs.constants.O_DIRECTORY,
-          );
-          const openProjectStat = await projectHandle.stat();
-          if (
-            openProjectStat.dev !== projectStat.dev ||
-            openProjectStat.ino !== projectStat.ino
-          ) {
-            continue;
-          }
+
+        const ownerContent = await fs.promises.readFile(ownerPath, "utf8");
+        const pid = parseOwnerPid(ownerContent);
+        if (pid === undefined || isProcessAlive(pid)) continue;
+
+        const contents = await fs.promises.readdir(
+          `/proc/self/fd/${leaseHandle.fd}`,
+        );
+        if (
+          contents.some(
+            (name) => name !== SCRATCH_OWNER_NAME && name !== SCRATCH_TREE_NAME,
+          )
+        ) {
+          continue;
         }
-        await leaseHandle.chmod(0o700);
-        if (projectStat) {
-          await fs.promises.rm(
-            path.join(`/proc/self/fd/${leaseHandle.fd}`, SCRATCH_TREE_NAME),
-            { recursive: true, force: false },
+
+        const hasProject = contents.includes(SCRATCH_TREE_NAME);
+        if (
+          hasProject &&
+          (!scannedProjectStat ||
+            !scannedProjectStat.isDirectory() ||
+            scannedProjectStat.isSymbolicLink())
+        ) {
+          continue;
+        }
+
+        if (options.onLeaseValidated) {
+          await options.onLeaseValidated(entry.name);
+        }
+        if (hasProject) {
+          if (!scannedProjectStat) continue;
+          await deleteLeaseContentsAndRmdir(
+            parentHandle,
+            entry.name,
+            leaseHandle,
+            {
+              hasProject: true,
+              lease: scannedLeaseStat,
+              project: scannedProjectStat,
+              owner: scannedOwnerStat,
+            },
           );
+        } else {
+          await deleteLeaseContentsAndRmdir(
+            parentHandle,
+            entry.name,
+            leaseHandle,
+            {
+              hasProject: false,
+              lease: scannedLeaseStat,
+              owner: scannedOwnerStat,
+            },
+          );
+        }
+      } catch (error) {
+        if (error instanceof ScratchLeaseIdentityError) continue;
+        if (
+          error instanceof Error &&
+          "code" in error &&
+          (error.code === "ENOENT" ||
+            error.code === "ENOTDIR" ||
+            error.code === "ENOTEMPTY")
+        ) {
+          continue;
         }
-        await fs.promises.rm(currentOwnerPath, { force: false });
-        await fs.promises.rmdir(
-          path.join(`/proc/self/fd/${parentHandle.fd}`, entry.name),
+        console.error(
+          `[delegate] failed to sweep stale scratch lease '${entry.name}'`,
+          error,
         );
       } finally {
-        await projectHandle?.close();
         await leaseHandle?.close();
-        await parentHandle.close();
-      }
-    } catch (error) {
-      if (
-        error instanceof Error &&
-        "code" in error &&
-        (error.code === "ENOENT" || error.code === "ENOTDIR")
-      ) {
-        continue;
       }
-      // A concurrent creator/remover can legitimately win this race. Other
-      // failures are still reported, but must not block a new scratch task.
-      console.error(
-        `[delegate] failed to sweep stale scratch lease '${leaseRoot}'`,
-        error,
-      );
     }
+  } finally {
+    await parentHandle.close();
   }
 }
 
@@ -392,10 +610,12 @@ export async function createScratchWorkspace(
 
   let sourceCwd: string;
   let sourceRoot: string;
+  let containerDir: string;
   let leaseRoot: string | undefined;
   let scratchRoot: string | undefined;
   let copiedLeaseStat: fs.Stats | undefined;
   let copiedRootStat: fs.Stats | undefined;
+  let copiedOwnerStat: fs.Stats | undefined;
   try {
     if (signal?.aborted) controller.abort(signal.reason);
     throwIfSetupCancelled(controller.signal, signal);
@@ -409,9 +629,18 @@ export async function createScratchWorkspace(
       );
     }
 
-    await sweepStaleScratchLeases(path.dirname(sourceRoot));
+    containerDir = path.join(path.dirname(sourceRoot), SCRATCH_CONTAINER_NAME);
+    const uid = process.getuid?.();
+    await ensureScratchContainer(containerDir, uid);
+    if (uid !== undefined) {
+      await sweepStaleScratchLeases(containerDir);
+      await sweepStaleScratchLeases(path.dirname(sourceRoot), {
+        prefix: SCRATCH_LEGACY_PREFIX,
+      });
+    }
+
     leaseRoot = await fs.promises.mkdtemp(
-      path.join(path.dirname(sourceRoot), SCRATCH_PREFIX),
+      path.join(containerDir, SCRATCH_LEASE_PREFIX),
     );
     await fs.promises.chmod(leaseRoot, 0o700);
     await fs.promises.writeFile(
@@ -494,6 +723,9 @@ export async function createScratchWorkspace(
     // fails, the catch below restores permissions and removes the partial copy.
     copiedLeaseStat = await fs.promises.lstat(leaseRoot);
     copiedRootStat = await fs.promises.lstat(scratchRoot);
+    copiedOwnerStat = await fs.promises.lstat(
+      path.join(leaseRoot, SCRATCH_OWNER_NAME),
+    );
   } catch (error) {
     if (leaseRoot) {
       try {
@@ -532,6 +764,7 @@ export async function createScratchWorkspace(
   const completedRoot = scratchRoot!;
   const completedLeaseStat = copiedLeaseStat!;
   const completedRootStat = copiedRootStat!;
+  const completedOwnerStat = copiedOwnerStat!;
   const relativeCwd = path.relative(sourceRoot!, sourceCwd!);
   let cleaned = false;
   const resolveReportedPath = async (candidate: string): Promise<string> => {
@@ -580,8 +813,8 @@ export async function createScratchWorkspace(
       if (cleaned) return;
       try {
         if (
-          path.dirname(completedLeaseRoot) !== path.dirname(sourceRoot!) ||
-          !path.basename(completedLeaseRoot).startsWith(SCRATCH_PREFIX) ||
+          path.dirname(completedLeaseRoot) !== containerDir ||
+          !path.basename(completedLeaseRoot).startsWith(SCRATCH_LEASE_PREFIX) ||
           path.dirname(completedRoot) !== completedLeaseRoot ||
           path.basename(completedRoot) !== SCRATCH_TREE_NAME
         ) {
@@ -593,7 +826,7 @@ export async function createScratchWorkspace(
         // descriptor identifies the checked directory even if its pathname is
         // renamed or replaced while cleanup is running.
         const parentHandle = await fs.promises.open(
-          path.dirname(completedLeaseRoot),
+          containerDir,
           fs.constants.O_RDONLY | fs.constants.O_DIRECTORY,
         );
         let leaseHandle:
@@ -601,59 +834,51 @@ export async function createScratchWorkspace(
         let rootHandle:
           Awaited<ReturnType<typeof fs.promises.open>> | undefined;
         try {
+          const leaseName = path.basename(completedLeaseRoot);
           leaseHandle = await fs.promises.open(
-            path.join(
-              `/proc/self/fd/${parentHandle.fd}`,
-              path.basename(completedLeaseRoot),
-            ),
+            path.join(`/proc/self/fd/${parentHandle.fd}`, leaseName),
             fs.constants.O_RDONLY | fs.constants.O_DIRECTORY,
           );
           rootHandle = await fs.promises.open(
             path.join(`/proc/self/fd/${leaseHandle.fd}`, SCRATCH_TREE_NAME),
             fs.constants.O_RDONLY | fs.constants.O_DIRECTORY,
           );
-          const currentLeaseStat = await fs.promises.lstat(completedLeaseRoot);
-          const currentRootStat = await fs.promises.lstat(completedRoot);
           const openLeaseStat = await leaseHandle.stat();
           const openRootStat = await rootHandle.stat();
+          const currentLeaseStat = await fs.promises.lstat(
+            path.join(`/proc/self/fd/${parentHandle.fd}`, leaseName),
+          );
+          const currentRootStat = await fs.promises.lstat(
+            path.join(`/proc/self/fd/${leaseHandle.fd}`, SCRATCH_TREE_NAME),
+          );
           if (
-            !currentLeaseStat.isDirectory() ||
-            currentLeaseStat.dev !== completedLeaseStat.dev ||
-            currentLeaseStat.ino !== completedLeaseStat.ino ||
-            !currentRootStat.isDirectory() ||
-            currentRootStat.dev !== completedRootStat.dev ||
-            currentRootStat.ino !== completedRootStat.ino ||
             !openLeaseStat.isDirectory() ||
-            openLeaseStat.dev !== completedLeaseStat.dev ||
-            openLeaseStat.ino !== completedLeaseStat.ino ||
+            !sameFileIdentity(openLeaseStat, completedLeaseStat) ||
+            !sameFileIdentity(currentLeaseStat, completedLeaseStat) ||
             !openRootStat.isDirectory() ||
-            openRootStat.dev !== completedRootStat.dev ||
-            openRootStat.ino !== completedRootStat.ino
+            !sameFileIdentity(openRootStat, completedRootStat) ||
+            !sameFileIdentity(currentRootStat, completedRootStat)
           ) {
             throw new Error(
               "Scratch workspace root was moved or replaced; refusing to report cleanup success.",
             );
           }
-          await leaseHandle.chmod(0o700);
-          // Remove the project through the opened lease descriptor. The
-          // recursive operation never resolves the disposable root pathname.
-          await fs.promises.rm(
-            path.join(`/proc/self/fd/${leaseHandle.fd}`, SCRATCH_TREE_NAME),
-            { recursive: true, force: false },
-          );
-          await fs.promises.rm(
-            path.join(`/proc/self/fd/${leaseHandle.fd}`, SCRATCH_OWNER_NAME),
-            { force: false },
-          );
-          // The lease is empty now. Remove only its directory entry through the
-          // opened parent. This is deliberately non-recursive: if a cooperating
-          // process replaced the lease with a populated directory, rmdir fails
-          // instead of deleting the replacement's contents.
-          await fs.promises.rmdir(
-            path.join(
-              `/proc/self/fd/${parentHandle.fd}`,
-              path.basename(completedLeaseRoot),
-            ),
+
+          // The identity checks are snapshots. The primitive repeats them and
+          // removes project children through its opened descriptor, so a
+          // replacement observed before removal is preserved. This is not an
+          // atomic guarantee against a cooperating process changing the path
+          // after the final check.
+          await deleteLeaseContentsAndRmdir(
+            parentHandle,
+            leaseName,
+            leaseHandle,
+            {
+              hasProject: true,
+              lease: completedLeaseStat,
+              project: completedRootStat,
+              owner: completedOwnerStat,
+            },
           );
           cleaned = true;
         } finally {
@@ -670,3 +895,14 @@ export async function createScratchWorkspace(
     },
   };
 }
+
+export const _testHooks = {
+  sweepStaleScratchLeases,
+  ensureScratchContainer,
+  deleteLeaseContentsAndRmdir,
+  SCRATCH_CONTAINER_NAME,
+  SCRATCH_LEASE_PREFIX,
+  SCRATCH_LEGACY_PREFIX,
+  SCRATCH_TREE_NAME,
+  SCRATCH_OWNER_NAME,
+};