Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

39.4 KB
Raw Blame
/**
 * The data of a confidential session the Swarm ended for good in a Harness Team account (#895): a Product Manager removed
 * or replaced, a private chat's worker stopped (inCore/agents.ts closeMember and closeSwarm). The Swarm keeps its chats; its
 * files in the account, which the account's next agent could read, go. The account stays held until they have
 * (inCore/teamApps.ts, and the backend's `heldFor`).
 *
 * Through the reviewed purge (lib/purgeAgentService.ts), its worktree kept; then a Codex one's own engine home goes whole
 * (superTabs/teamDaemon.ts pmEngineHome), and a Claude Code one's traces are scrubbed from the Team user's shared home, whose
 * transcripts core reads only there. A sweep then looks where Claude Code and Codex write a session's own data, never at
 * other sessions' transcripts, which name the Product Manager when they read its status (security re-check 3 of #2089).
 *
 * The session is kept in a durable record before anything is deleted, and leaves it only once the sweep finds nothing: the
 * reviewed purge drops the session from the stopped catalog, so a retry after a failed sweep had nothing left to scrub from.
 * Everything here reads and writes asynchronously: a Team home holds gigabytes of transcripts, and this runs in the core.
 */
import { buddyTmpFolder, realOfFolder } from '../../lib/agentTmp.js'
import { createReadStream, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, writeFileSync, type Dirent } from 'node:fs'
import { readdir, readFile, rename, rm, stat, unlink, writeFile } from 'node:fs/promises'
import nodePath, { basename, dirname, isAbsolute, join, relative, sep, type PlatformPath } from 'node:path'
import { createInterface } from 'node:readline'
import { PM_HOMES, PM_START_ID } from '../teamDaemon.js'

/** What a purge needs of a session, kept until it finishes. `pastes`: the paste cache files its history lines kept. */
export interface PurgeTarget {
  agentId: string
  sessionId: string | null
  cwd: string | null
  engine: string
  codexHome: string | null
  pastes?: string[]
}

/** The purges still to finish, by agent id, kept in [file] across restarts. One that cannot be read is never written over,
 *  which would forget the purges it names: it is kept aside at `<file>.unreadable` (`.1`, `.2`… when one already is), and while any is there the record is
 *  `unknown` and the account stays held, as it fails closed (inCore/teamApps.ts), until a person clears it (security
 *  re-check 2 of 9e49723b8). */
export function purgeRecord(file: string) {
  const aside = `${file}.unreadable`
  const load = (): Map<string, PurgeTarget> => {
    if (!existsSync(file)) return new Map()
    try {
      const saved: unknown = JSON.parse(readFileSync(file, 'utf8'))
      // One of another shape is set aside as well, never read as fewer purges than it names (security review 2 of #2142).
      if (!saved || typeof saved !== 'object' || Array.isArray(saved)) throw new Error('not a record')
      const held = new Map<string, PurgeTarget>()
      for (const [id, entry] of Object.entries(saved)) {
        if (!isTarget(id, entry)) throw new Error('not a purge')
        held.set(id, entry)
      }
      return held
    } catch {
      let free = aside
      for (let n = 1; existsSync(free); n++) free = `${aside}.${n}`
      renameSync(file, free)
      return new Map()
    }
  }
  /** The records kept aside, in the order they were. No folder yet: no record was ever kept here, let alone kept aside. */
  const keptAsideFiles = (): string[] => existsSync(dirname(file)) ? readdirSync(dirname(file))
    .filter(name => name === basename(aside) || name.startsWith(`${basename(aside)}.`))
    .map(name => [Number(name.slice(basename(aside).length + 1)) || 0, join(dirname(file), name)] as const)
    .sort(([a], [b]) => a - b).map(([, path]) => path) : []
  const keptAside = (): boolean => existsSync(aside) || keptAsideFiles().length > 0
  const state = { held: load() }
  // Said once per start, where each is kept, path only: the refusal points here, and its owner clears it by hand (the PR's
  // risk note; security review 2 of #2142).
  const kept = keptAsideFiles()
  if (kept.length) console.warn(`[super-tabs] the record of purges still to finish could not be read; kept aside at ${kept.join(', ')} until its owner clears it`)
  const save = () => {
    mkdirSync(dirname(file), { recursive: true, mode: 0o700 })
    writeFileSync(`${file}.next`, JSON.stringify(Object.fromEntries(state.held)), { mode: 0o600 })
    renameSync(`${file}.next`, file)
  }
  return {
    pending: (): PurgeTarget[] => [...state.held.values()],
    get: (agentId: string): PurgeTarget | undefined => state.held.get(agentId),
    unknown: keptAside,
    put(target: PurgeTarget): void { state.held.set(target.agentId, target); save() },
    drop(agentId: string): void { if (state.held.delete(agentId)) save() },
  }
}
export type PurgeRecord = ReturnType<typeof purgeRecord>

const nameOrNull = (value: unknown) => value === null || typeof value === 'string'
/** An entry as `put` writes it; `codexHome` absent in records from before Codex PMs had homes of their own. */
function isTarget(id: string, entry: unknown): entry is PurgeTarget {
  if (!entry || typeof entry !== 'object' || Array.isArray(entry)) return false
  const target = entry as Record<string, unknown>
  return target.agentId === id && nameOrNull(target.sessionId) && nameOrNull(target.cwd) && typeof target.engine === 'string'
    && (target.codexHome === undefined || nameOrNull(target.codexHome))
    && (target.pastes === undefined || (Array.isArray(target.pastes) && target.pastes.every(paste => typeof paste === 'string')))
}

/** What a scrub tells its caller: another folder's transcripts share its transcript folder, or what it could not read and
 *  left, by kind alone. */
export type ScrubTold = 'shared' | 'unread' | 'unreadTodos' | 'unreadBackups'
/** [dir]'s names; null when it is there but cannot be listed. Only a folder that is not there is empty: read as empty, an
 *  unlistable todos or backups folder let a Buddy's cleanup, which no sweep follows, finish and leave its todo file and its
 *  folder in the backups (re-check of 8c0b019). The error itself is dropped, as its message names the path. */
const listed = (dir: string) => readdir(dir).catch((error: NodeJS.ErrnoException) => error.code === 'ENOENT' ? [] as string[] : null)

/**
 * Whether [codexHome] is a Product Manager's own Codex home in the Team user's [home], `<home>/.harness-pm-homes/<id>/codex`
 * as superTabs/teamDaemon.ts pmEngineHome makes it, by [paths]' own rules: purge deletes its parent whole. A check for
 * `${homes}/` never matched Windows' `\`, so a purged Codex PM's home stayed for the account's next agent to read, and it took
 * a home one level under the PM homes folder, whose parent is every PM's homes (Windows audit, task #2022).
 */
export function isPmCodexHome(home: string, codexHome: string, paths: Pick<PlatformPath, 'join' | 'relative' | 'isAbsolute' | 'sep'> =
  { join, relative, isAbsolute, sep }): boolean {
  if (!codexHome) return false
  const inside = paths.relative(paths.join(home, PM_HOMES), codexHome)
  if (paths.isAbsolute(inside)) return false
  const [id, last, ...more] = inside.split(paths.sep)
  // pmEngineHome's own rule for the id: `.. ` passed a check for `..`, and Windows reads it as `..`, the whole Team home
  // (security review 1 of #2568).
  return !!id && PM_START_ID.test(id) && last === 'codex' && more.length === 0
}

/** Claude Code's folder name for a project folder: every character but a letter or digit made a dash. */
const claudeSlug = (cwd: string) => cwd.replace(/[^A-Za-z0-9]/g, '-')
const SESSION = /^[A-Za-z0-9_-]{1,160}$/
/** What purge asks of a platform's paths: the host's, or `path.win32` in a test. */
type FolderPaths = Pick<PlatformPath, 'isAbsolute' | 'normalize' | 'parse' | 'sep'>
const onWindows = (paths: FolderPaths) => paths.sep === '\\'
/** [path] as it compares. On Windows any separator names the same folder, in any case, as Claude Code compares them there. Its
 *  forms differ too: a config key has `/` (2.1.316's `U3`), history and transcripts `\` (Windows audit W3). */
const folderKey = (path: string, paths: FolderPaths) =>
  onWindows(paths) ? paths.normalize(path).replaceAll('\\', '/').replace(/\/+$/, '').toLowerCase() : path
/** Whether [cwd], as its key, is [key] or inside it: past a separator, so `C:\a\b-evil` is not inside `C:\a\b`. */
const inFolder = (cwd: string, key: string, paths: FolderPaths) => {
  const candidate = folderKey(cwd, paths)
  return candidate === key || candidate.startsWith(`${key}/`)
}
/** [text] of a file, as folder keys read in it: JSON doubles a `\`. */
const foldedText = (text: string, paths: FolderPaths) =>
  onWindows(paths) ? text.replaceAll('\\\\', '/').replaceAll('\\', '/').toLowerCase() : text
/** Its folder, when it names one that is no root: an empty or root key would match every other session's. On Windows a folder
 *  has a drive or a share: `\Users` and `/Users` are relative to whichever drive is current, so which folder they name is not known. */
function folderOf(target: PurgeTarget, paths: FolderPaths): string | null {
  const cwd = target.cwd
  if (!cwd || !paths.isAbsolute(cwd) || (onWindows(paths) && !/^([A-Za-z]:[\\/]|[\\/]{2}[^\\/]+[\\/]+[^\\/]+)/.test(cwd))) return null
  const bare = (path: string) => path.replace(/[\\/]+$/, '')
  const normal = paths.normalize(cwd)
  return bare(normal) === bare(paths.parse(normal).root) ? null : cwd
}

/**
 * Rewrites [path] through [transform], unless it changed while being rewritten: another agent of the account may write the
 * same file (Claude Code's history, its config) at any moment, and a rewrite from an older copy would lose that write. Then
 * it reads it again and tries again; false when it never stood still. A missing file has nothing to rewrite.
 *
 * What it cannot close without a lock the engines do not take: a write landing between its last check and the rename, one
 * system call wide, is lost to that other agent. It leaves nothing of the session behind: the sweep reads the file again
 * afterwards and fails the purge, closed, while anything still names it.
 */
export async function rewriteIfUnchanged(path: string, transform: (text: string) => string, tries = 5): Promise<boolean> {
  for (let attempt = 0; attempt < tries; attempt++) {
    let before
    try { before = await stat(path) } catch { return true }
    const text = await readFile(path, 'utf8')
    const next = transform(text)
    if (next === text) return true
    const temporary = `${path}.harness-${process.pid}`
    await writeFile(temporary, next, { mode: 0o600 })
    const now = await stat(path)
    if (now.mtimeMs !== before.mtimeMs || now.size !== before.size) { await unlink(temporary); continue }
    await rename(temporary, path)
    return true
  }
  return false
}

/** [config] (Claude Code's `.claude.json`, or a backup of it) without [folder]: its project entry and its repository paths. */
function withoutFolder(text: string, folder: string, paths: FolderPaths): string {
  let config: { projects?: Record<string, unknown>; githubRepoPaths?: Record<string, unknown> }
  try { config = JSON.parse(text) } catch { return text }
  if (!config || typeof config !== 'object') return text
  let changed = false
  const key = folderKey(folder, paths)
  const same = (path: unknown) => typeof path === 'string' && folderKey(path, paths) === key
  for (const name of Object.keys(config.projects ?? {})) if (same(name)) { delete config.projects![name]; changed = true }
  for (const [repository, listed] of Object.entries(config.githubRepoPaths ?? {})) {
    if (!Array.isArray(listed) || !listed.some(same)) continue
    const kept = listed.filter(path => !same(path))
    if (kept.length) config.githubRepoPaths![repository] = kept
    else delete config.githubRepoPaths![repository]
    changed = true
  }
  return changed ? JSON.stringify(config, null, 2) : text
}

/** Whether the transcript [file] records a working folder other than [folder] or one inside it: Claude Code writes the cwd
 *  on every turn, and its folder name makes every '/' and '.' a dash, so a removed worktree `<worktrees>/old/notes` shares its
 *  transcript folder with an unrelated `~/harnesses/worktrees-old/notes` (security review 2 of #2375). */
export async function recordsOtherFolder(file: string, folder: string, paths: FolderPaths = nodePath): Promise<boolean> {
  const key = folderKey(folder, paths)
  const lines = createInterface({ input: createReadStream(file, 'utf8'), crlfDelay: Infinity })
  try {
    for await (const line of lines) {
      if (!line.includes('"cwd"')) continue
      let cwd: unknown
      try { cwd = (JSON.parse(line) as { cwd?: unknown }).cwd } catch { continue }
      if (typeof cwd === 'string' && !inFolder(cwd, key, paths)) return true
    }
    return false
  } finally { lines.close() }
}

/** Whether the transcript [file] records [folder] or a folder inside it as its working folder (`own`), and another (`other`);
 *  `unread` when it could not be read, whose error would name its path (review of #2389). */
async function foldersOf(file: string, folder: string, paths: FolderPaths): Promise<{ own: boolean; other: boolean; unread?: true }> {
  const found = { own: false, other: false }, key = folderKey(folder, paths)
  const lines = createInterface({ input: createReadStream(file, 'utf8'), crlfDelay: Infinity })
  try {
    for await (const line of lines) {
      if (!line.includes('"cwd"')) continue
      let cwd: unknown
      try { cwd = (JSON.parse(line) as { cwd?: unknown } | null)?.cwd } catch { continue }
      if (typeof cwd === 'string') found[inFolder(cwd, key, paths) ? 'own' : 'other'] = true
    }
  } catch { return { own: false, other: false, unread: true } } finally { lines.close() }
  return found
}

/**
 * [dir], the transcript folder Claude Code names for [folder]: whole when no transcript in it is another folder's; else only
 * the transcripts that record [folder] and no other, each with its folder of subagents and tool results, and [onShared] is
 * told. Its memory folder then stays whole: which of its files are the session's no transcript proves (security reviews 1
 * and 2 of #2385: a Bash append, a subagent, a transcript Claude Code pruned, `Notes.md` on a Mac), and the Team purge's
 * sweep holds the account while one is there. A transcript that records no folder, or both, stays too, for the sweep to refuse.
 */
async function removeTranscripts(dir: string, folder: string, paths: FolderPaths, told?: (what: ScrubTold) => void): Promise<void> {
  // Only a folder that is not there is empty. One that cannot be listed stays whole, and its caller is told, by that word
  // alone: read as empty it went whole, its error's path into the log, or another folder's transcripts unread on a passing
  // error such as too many open files (security reviews 1 and 2 of 58b035e). The Team purge's sweep then holds the account;
  // a Buddy's cleanup, which has no sweep, fails and is tried again (host.ts endSession).
  const names = await readdir(dir).catch((error: NodeJS.ErrnoException) => error.code === 'ENOENT' ? [] : null)
  if (!names) { told?.('unread'); return }
  const transcripts = new Map<string, Awaited<ReturnType<typeof foldersOf>>>()
  for (const name of names.filter(name => name.endsWith('.jsonl'))) {
    transcripts.set(name, await foldersOf(join(dir, name), folder, paths))
  }
  // One that could not be read may be another folder's: it and the folder stay, and its caller is told.
  const values = [...transcripts.values()]
  if (values.some(transcript => transcript.unread)) told?.('unread')
  if (!values.some(transcript => transcript.other || transcript.unread)) { await rm(dir, { recursive: true, force: true }); return }
  if (values.some(transcript => transcript.other)) told?.('shared')
  for (const [name, { own, other }] of transcripts) {
    if (!own || other) continue
    await rm(join(dir, name), { force: true })
    await rm(join(dir, name.slice(0, -'.jsonl'.length)), { recursive: true, force: true })
  }
}

/** What in [dir], the transcript folder Claude Code names for [folder], may still be the session's, by its kind only: a path
 *  would name another folder's file (security review 1 of #2385). Null when it holds only transcripts that record other
 *  folders and never [folder], their own folders, and an empty memory folder or none; anything else, a memory file above all,
 *  or the folder itself once no other folder's transcript is left, fails it, closed. */
async function leftInSharedFolder(dir: string, folder: string, paths: FolderPaths): Promise<string | null> {
  // One that cannot be listed holds it by its kind; one gone since its parent was listed holds nothing.
  let entries: Dirent[]
  try { entries = (await readdir(dir, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name)) } catch (error) {
    return (error as NodeJS.ErrnoException).code === 'ENOENT' ? null : SHARED_LEFT.unreadFolder
  }
  const read = new Map<string, Awaited<ReturnType<typeof foldersOf>>>()
  for (const entry of entries.filter(entry => entry.isFile() && entry.name.endsWith('.jsonl'))) read.set(entry.name, await foldersOf(join(dir, entry.name), folder, paths))
  // Said to be shared only when another folder's transcript is there (re-check 2 of 68ec6f0).
  const kinds = [...read.values()].some(transcript => transcript.other) ? SHARED_LEFT : OWN_LEFT
  const transcripts = new Set<string>()
  for (const [name, { own, other, unread }] of read) {
    if (unread) return kinds.unreadTranscript
    if (own || !other) return kinds.transcript
    transcripts.add(name.slice(0, -'.jsonl'.length))
  }
  if (!transcripts.size) return SHARED_LEFT.folder
  for (const entry of entries) {
    if (entry.isFile() && entry.name.endsWith('.jsonl')) continue
    if (entry.isDirectory() && entry.name === 'memory') {
      // One that cannot be read fails it too, by its kind: the read's own error named its path (security review of #2385). One
      // gone since the listing is none.
      const memory = await readdir(join(dir, entry.name)).catch((error: NodeJS.ErrnoException) => error.code === 'ENOENT' ? [] : null)
      if (!memory) return SHARED_LEFT.unreadMemory
      if (memory.length) return SHARED_LEFT.memory
    } else if (!entry.isDirectory() || !transcripts.has(entry.name)) return SHARED_LEFT.other
  }
  return null
}
/** What a held account's owner does about what could not be read: nothing names its path, and the host tries the purge again
 *  by itself (host.ts endSession), so fixing it is the whole of it (security review 1 of 58b035e). [find]: where to look, when
 *  its kind alone does not say (re-check of 8c0b019). */
const makeReadable = (find?: string) =>
  `could not be read: its owner ${find ? `finds it (${find}) and ` : ''}makes it readable for the Team account, and the purge finishes on its next try`
const MAKE_READABLE = makeReadable()
/** What a failed sweep says of its shared transcript folder, in place of a path. */
export const SHARED_LEFT = {
  transcript: 'a transcript in its transcript folder, which another folder shares, that records its folder or none',
  memory: 'a memory file in its transcript folder, which another folder shares: its owner checks it and removes what is not the other folder\'s',
  unreadFolder: `its transcript folder, which ${MAKE_READABLE}`,
  unreadMemory: `a memory folder in its transcript folder, which another folder shares, that ${MAKE_READABLE}`,
  unreadTranscript: `a transcript in its transcript folder, which another folder shares, that ${MAKE_READABLE}`,
  other: 'something in its transcript folder, which another folder shares, that is not another folder\'s transcript',
  folder: 'its transcript folder',
}
/** The same, for a transcript folder no other folder's transcript is in. */
export const OWN_LEFT = {
  transcript: 'a transcript in its transcript folder that records its folder or none',
  unreadTranscript: `a transcript in its transcript folder that ${MAKE_READABLE}`,
}
/** What the sweep names of what it found or could not read, in place of a path: one held the Team home's, and could name another
 *  folder (re-check 2 of 68ec6f0). */
export const SWEEP_LEFT = {
  claudeHistory: 'a line of Claude Code\'s prompt history that names its session or its folder',
  codexHistory: 'a line of Codex\'s prompt history that names its session or its folder',
  paste: 'a paste Claude Code kept from one of its prompts',
  config: 'its folder in Claude Code\'s config, or in a backup of it',
  claudeNamed: 'a file or folder in Claude Code\'s home named for its session or its folder',
  codexNamed: 'a file or folder in Codex\'s home named for its session or its folder',
  unreadFile: `a file in the Team account's Claude Code or Codex home that ${makeReadable('search the Team account\'s Claude Code and Codex homes for files it can\'t read')}`,
  unlistedFolder: `a folder in the Team account's Claude Code or Codex home that ${makeReadable('search the Team account\'s Claude Code and Codex homes for folders it can\'t read')}`,
}

/** The names in [projects] Claude Code uses for [folder]. On Windows that is by any case, as `c:\a` and `C:\a` are one folder there
 *  and their names differ only by it. Elsewhere it is the one name, listed or not, for the caller to find what is there. */
async function transcriptFolders(projects: string, folder: string, paths: FolderPaths): Promise<string[]> {
  const slug = claudeSlug(folderOnDisk(folder, paths))
  if (!onWindows(paths)) return [slug]
  const names = await listed(projects)
  // A listing that failed names only what the slug says: the removal reports it, unread, by its kind.
  return names ? names.filter(name => name.toLowerCase() === slug.toLowerCase()) : [slug]
}
/** [folder] as Claude Code names its project folder from it, by its working folder: no `..` and no trailing separator. */
const folderOnDisk = (folder: string, paths: FolderPaths) => onWindows(paths) ? paths.normalize(folder).replace(/[\\/]+$/, '') : folder

/**
 * Removes from the Team user's shared Claude Code home ([home]/.claude, [home]/.claude.json and its backups) what Claude
 * Code keeps of the session: its prompt history lines and the pastes they kept ([pastes] from an earlier attempt too), its
 * project folder with its transcripts and memory (only the transcripts that record its folder alone when another folder's
 * share it, and [told] 'shared'; [told] 'unread' when its transcript folder or one of its transcripts could not be read, and
 * stays),
 * its file history, todos, session environment and debug log, and its folder's entry and repository paths in the config
 * and in every backup of it ([told] 'unreadTodos' or 'unreadBackups' when that folder could not be listed). The pastes its
 * history named, for the record.
 */
export async function scrubClaudeSession(home: string, target: PurgeTarget, pastes: readonly string[] = [],
  onPastes?: (pastes: string[]) => void, told?: (what: ScrubTold) => void, paths: FolderPaths = nodePath): Promise<string[]> {
  const sessionId = target.sessionId && SESSION.test(target.sessionId) ? target.sessionId : null
  const folder = folderOf(target, paths)
  const key = folder && folderKey(folder, paths)
  if (!sessionId && !folder) return []
  const claude = join(home, '.claude'), history = join(claude, 'history.jsonl')
  /** Its history's lines kept, and the pastes its own lines named. */
  const split = (text: string) => {
    const named: string[] = []
    const kept = text.split('\n').filter(line => {
      if (!line.trim()) return false
      let row: { sessionId?: unknown; project?: unknown; pastedContents?: Record<string, { contentHash?: unknown } | null> }
      try { row = JSON.parse(line) } catch { return !(sessionId && line.includes(sessionId)) && !(key && foldedText(line, paths).includes(key)) }
      const ours = (!!sessionId && row.sessionId === sessionId) || (!!key && typeof row.project === 'string' && folderKey(row.project, paths) === key)
      if (ours) for (const paste of Object.values(row.pastedContents ?? {})) if (typeof paste?.contentHash === 'string' && SESSION.test(paste.contentHash)) named.push(paste.contentHash)
      return !ours
    })
    return { kept, named }
  }
  // Its pastes are handed on before the lines naming them go: a scrub that dies after the rewrite would otherwise lose them,
  // and a paste left behind would pass the sweep (security re-check 2 of 9e49723b8).
  const found = split(await readFile(history, 'utf8').catch(() => '')).named
  if (found.length) onPastes?.([...new Set(found)])
  await rewriteIfUnchanged(history, text => {
    const { kept, named } = split(text)
    found.push(...named)
    return kept.length ? `${kept.join('\n')}\n` : ''
  })
  for (const hash of new Set([...pastes, ...found])) if (SESSION.test(hash)) await rm(join(claude, 'paste-cache', `${hash}.txt`), { force: true })
  if (folder) for (const name of await transcriptFolders(join(claude, 'projects'), folder, paths)) await removeTranscripts(join(claude, 'projects', name), folder, paths, told)
  // Its private temporary folder beside a Team account: command output from its person's private work (lib/agentTmp.ts). A plain
  // session shares its Buddy's folder, and this one's TMPDIR with it, so the whole folder goes only once that folder has; the
  // sweep takes what a tool left meanwhile (review of #2563).
  if (folder) {
    const temp = buddyTmpFolder(folder)
    if (!existsSync(folder)) await rm(temp, { recursive: true, force: true })
    else if (sessionId) await rm(join(temp, `claude-${process.getuid?.() ?? 0}`, claudeSlug(realOfFolder(folder)), sessionId), { recursive: true, force: true })
  }
  if (sessionId) {
    for (const sub of ['file-history', 'session-env']) await rm(join(claude, sub, sessionId), { recursive: true, force: true })
    await rm(join(claude, 'debug', `${sessionId}.txt`), { force: true })
    const todos = await listed(join(claude, 'todos'))
    if (!todos) told?.('unreadTodos')
    // `<session>-agent-<agent>.json`: by prefix alone, a one-character id took every todo starting with it (security review 2 of #2375).
    for (const name of todos ?? []) if (name.startsWith(`${sessionId}-agent-`)) await rm(join(claude, 'todos', name), { force: true })
  }
  if (folder) {
    await rewriteIfUnchanged(join(home, '.claude.json'), text => withoutFolder(text, folder, paths))
    const backups = await listed(join(claude, 'backups'))
    if (!backups) told?.('unreadBackups')
    for (const name of backups ?? []) await rewriteIfUnchanged(join(claude, 'backups', name), text => withoutFolder(text, folder, paths))
  }
  return [...new Set(found)]
}

/**
 * What still names the session where Claude Code and Codex write its own data, or null: a line of the shared prompt history
 * (Claude Code's or Codex's) naming its session or folder; a paste it kept; its folder in the config or a backup of it; and
 * anywhere under their homes, a file or folder named for its session or its folder. Never the contents of other sessions'
 * transcripts: another agent that read the Product Manager's status names both there, and is not its to delete. Its transcript
 * folder, when another folder's transcripts share it, only by the working folders they record.
 */
export async function sweepForSession(home: string, target: PurgeTarget, pastes: readonly string[], paths: FolderPaths = nodePath): Promise<string | null> {
  const sessionId = target.sessionId && SESSION.test(target.sessionId) ? target.sessionId : null
  const folder = folderOf(target, paths), key = folder && folderKey(folder, paths)
  const claude = join(home, '.claude'), codex = join(home, '.codex')
  const names = (text: string) => (!!sessionId && text.includes(`"${sessionId}"`))
    || (!!key && [`"${key}"`, `"${key}/`].some(quoted => foldedText(text, paths).includes(quoted)))
  // Only what is not there is empty: anything else that cannot be read holds the account, by its kind. Read as empty, an
  // unreadable projects folder let the account go with the session's transcript in it (re-checks 1 and 2 of 68ec6f0).
  const gone = (error: NodeJS.ErrnoException) => error.code === 'ENOENT'
  const read = (path: string) => readFile(path, 'utf8').catch((error: NodeJS.ErrnoException) => gone(error) ? '' : null)
  for (const [history, kind] of [[join(claude, 'history.jsonl'), SWEEP_LEFT.claudeHistory], [join(codex, 'history.jsonl'), SWEEP_LEFT.codexHistory]]) {
    const text = await read(history)
    if (text === null) return SWEEP_LEFT.unreadFile
    if (names(text)) return kind
  }
  for (const hash of pastes) if (SESSION.test(hash) && existsSync(join(claude, 'paste-cache', `${hash}.txt`))) return SWEEP_LEFT.paste
  if (folder) {
    const backups = await readdir(join(claude, 'backups')).catch((error: NodeJS.ErrnoException) => gone(error) ? [] : null)
    if (!backups) return SWEEP_LEFT.unlistedFolder
    for (const config of [join(home, '.claude.json'), ...backups.map(name => join(claude, 'backups', name))]) {
      const text = await read(config)
      if (text === null) return SWEEP_LEFT.unreadFile
      if (foldedText(text, paths).includes(`"${key}"`)) return SWEEP_LEFT.config
    }
  }
  const slug = folder ? claudeSlug(folderOnDisk(folder, paths)) : null, projects = join(claude, 'projects')
  const isSlug = (name: string) => slug !== null && (onWindows(paths) ? name.toLowerCase() === slug.toLowerCase() : name === slug)
  const walk = async (path: string, named: string): Promise<string | null> => {
    let entries: Dirent[]
    try { entries = await readdir(path, { withFileTypes: true }) } catch (error) { return gone(error as NodeJS.ErrnoException) ? null : SWEEP_LEFT.unlistedFolder }
    for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
      const child = join(path, entry.name)
      if (sessionId && entry.name.includes(sessionId)) return named
      if (isSlug(entry.name)) {
        // Its transcript folder outlives the scrub when another folder's transcripts share it ('/' and '.' both become '-'),
        // and its name alone held the account for good (follow-up to security review 2 of #2375).
        const left = path === projects && entry.isDirectory() ? await leftInSharedFolder(child, folder!, paths) : named
        if (left) return left
      }
      if (entry.isDirectory()) { const found = await walk(child, named); if (found) return found }
    }
    return null
  }
  for (const [root, named] of [[claude, SWEEP_LEFT.claudeNamed], [codex, SWEEP_LEFT.codexNamed]]) { const found = await walk(root, named); if (found) return found }
  return null
}

/** A purge refused while the record is kept aside; the close that gets it does not say so again (inCore/agents.ts). */
export const PURGE_RECORD_UNREADABLE = 'PURGE_RECORD_UNREADABLE'
export const UNREADABLE_DETAIL = "This machine's record of purges still to finish could not be read and was kept aside, as the daemon's log says at "
  + "each start. The account stays held until its owner clears it as #2142's risk note says, by file names only."

/** The folder of an agent's own engine home `<homes>/<creation>/codex`, to delete whole; null for any other path. Either separator,
 *  as a Windows path has `\\` (Windows pass, task #2022), and never a path that climbs out. */
export function ownHomeFolder(homes: string, codexHome: string | null | undefined): string | null {
  if (!codexHome || !codexHome.startsWith(homes)) return null
  const [first, creation, name, ...rest] = codexHome.slice(homes.length).split(/[\\/]/)
  // pmEngineHome's own rule for the id: `.. ` passed a check for `..`, and Windows reads it as `..`, the whole Team home (#2568).
  if (first !== '' || !creation || !PM_START_ID.test(creation) || name !== 'codex' || rest.length) return null
  return codexHome.slice(0, homes.length + 1 + creation.length)
}

/**
 * The purge of [agentId]'s data, once the Swarm ended it for good, when it was confidential: kept in [record] before the
 * first deletion and dropped once the sweep finds nothing. A retry finishes from the record, the session gone or not.
 */
/** A session as a purge compares it with what it recorded. */
interface HeldRow { agentId: string; sessionId?: string | null; cwd?: string | null; codexHome?: string | null }
/** What this daemon runs now, and what it keeps stopped and may resume. */
export type PurgeSessions = () => { live: readonly HeldRow[]; stopped: readonly HeldRow[] }

/** Whether another session holds what deleting [target] would take: its conversation or engine home, or, while it runs, its
 *  folder, whose transcripts and history lines go by that folder. A stopped one that is itself ending doesn't count, or two
 *  sessions of one conversation would wait on each other for good (security reviews 1 and 2 of #2680). */
function heldByAnother(target: PurgeTarget, sessions: ReturnType<PurgeSessions>, ending: PurgeRecord): boolean {
  const same = (s: HeldRow) => (!!target.sessionId && s.sessionId === target.sessionId) || (!!target.codexHome && s.codexHome === target.codexHome)
  return sessions.live.some(s => s.agentId !== target.agentId && (same(s) || (!!target.cwd && s.cwd === target.cwd)))
    || sessions.stopped.some(s => s.agentId !== target.agentId && !ending.get(s.agentId) && same(s))
}

export function createConfidentialPurge(deps: {
  /** What else is here now: a purge that would take what another session holds is refused, and stays recorded. */
  sessions?: PurgeSessions
  confidential: (agentId: string) => boolean
  session: (agentId: string) => { agentId: string; sessionId?: string | null; registeredAt: number; engine: string; cwd: string | null; codexHome?: string | null } | null
  purge: (request: Record<string, unknown>) => Promise<Record<string, unknown>>
  /** The Team user's home. */
  home: string
  record: PurgeRecord
  /** The platform's paths; a test's `path.win32`. */
  paths?: FolderPaths
}): (agentId: string) => Promise<Record<string, unknown>> {
  return async agentId => {
    // With its record unreadable, which purges are still to finish is not known: none is answered, not even a 'skipped' for a
    // session already gone, so the close fails and the backend keeps the account held until a person clears the record. Its
    // path was logged once, when it was kept aside; this answer, logged on every retry, names neither it nor the agent.
    if (deps.record.unknown()) return { error: PURGE_RECORD_UNREADABLE, detail: UNREADABLE_DETAIL }
    const session = deps.session(agentId)
    let target = deps.record.get(agentId)
    if (!target) {
      // Team-written Codex work has an engine home of its own too (superTabs/start.ts): it goes with the agent, confidential or not.
      if (session && !deps.confidential(agentId)) {
        const own = ownHomeFolder(join(deps.home, PM_HOMES), session.codexHome)
        if (own) await rm(own, { recursive: true, force: true })
        return { skipped: true }
      }
      if (!session) return { skipped: true }
      target = { agentId: session.agentId, sessionId: session.sessionId ?? null, cwd: session.cwd, engine: session.engine, codexHome: session.codexHome ?? null }
      deps.record.put(target)
    }
    if (deps.sessions && heldByAnother(target, deps.sessions(), deps.record)) {
      return { error: 'SESSION_IN_USE', detail: 'Another session holds what this purge would delete.' }
    }
    if (session) {
      const reference = { agentId: session.agentId, sessionId: session.sessionId ?? null, createdAt: session.registeredAt }
      const review = await deps.purge({ ...reference, mode: 'inspect' })
      if (typeof review.reviewId !== 'string') return review
      const deleted = await deps.purge({ ...reference, mode: 'delete', reviewId: review.reviewId, choices: { sessionData: true, worktreeData: false } })
      if (typeof deleted.error === 'string') return deleted
    }
    if (target.codexHome && isPmCodexHome(deps.home, target.codexHome)) await rm(dirname(target.codexHome), { recursive: true, force: true })
    if (target.engine === 'claude') {
      const keep = (found: readonly string[]) => {
        const pastes = [...new Set([...target!.pastes ?? [], ...found])]
        if (pastes.length !== (target!.pastes ?? []).length) { target = { ...target!, pastes }; deps.record.put(target) }
      }
      keep(await scrubClaudeSession(deps.home, target, target.pastes, keep, undefined, deps.paths))
    }
    const left = await sweepForSession(deps.home, target, target.pastes ?? [], deps.paths)
    if (left) return { error: 'SCRUB_INCOMPLETE', detail: `Something still names the session: ${left}` }
    deps.record.drop(agentId)
    return { ok: true }
  }
}

/** How long a purge that did not finish waits for its next try, each try the next, and the last from then on. */
const PURGE_RETRY_MS = [1, 2, 5, 15, 30].map(minutes => minutes * 60_000)

/** What the owner's `harness team status` reads of the purges still to finish (team/privacy.ts). A count: the status file is
 *  the owner's to read, and never names a session of someone else's project. */
export interface PurgeStatus { pending: number; unreadable: boolean; at: number }

/**
 * Tries again what the record still holds (Echo and Reed on #2675): a host's close gives up after a few tries, and one that
 * ended nothing leaves no host trying at all, while the account stays held. At its start, so a restart picks up the record, and
 * after any purge that leaves one, on a growing wait until none is left. Through [purge] alone, with its reviewed delete. A
 * pass skips an agent that is live again: the reviewed delete stops a live session and erases it, which only a host closing it
 * may ask for (security review 2 of #2680). It stays recorded and is tried again. A record that can't be read names nothing to
 * run, and waits for a person, as it always has. Calls for one agent share a run, so a retry and a host's close never scrub at once.
 */
export function withPurgeRetries(purge: (agentId: string) => Promise<Record<string, unknown>>, deps: {
  record: PurgeRecord
  sessions: PurgeSessions
  report: (status: PurgeStatus) => void
  log: (line: string) => void
  now?: () => number
}): ((agentId: string) => Promise<Record<string, unknown>>) & { stop(): void } {
  const running = new Map<string, Promise<Record<string, unknown>>>()
  let timer: ReturnType<typeof setTimeout> | null = null, tries = 0, passing = false, stopped = false
  const run = (agentId: string) => {
    const known = running.get(agentId)
    if (known) return known
    const started = purge(agentId).finally(() => running.delete(agentId))
    running.set(agentId, started)
    return started
  }
  const settle = () => {
    if (!deps.record.pending().length) tries = 0
    try { deps.report({ pending: deps.record.pending().length, unreadable: deps.record.unknown(), at: (deps.now ?? Date.now)() }) }
    catch (error) { deps.log(`could not report the purges still to finish: ${kindOf(error)}`) }
    if (stopped || timer || passing || !deps.record.pending().length) return
    timer = setTimeout(() => void pass(), PURGE_RETRY_MS[Math.min(tries, PURGE_RETRY_MS.length - 1)]!)
    timer.unref?.()
  }
  const pass = async () => {
    timer = null
    passing = true
    for (const { agentId } of deps.record.pending()) {
      if (stopped) break
      if (deps.sessions().live.some(s => s.agentId === agentId)) continue
      // By its kind alone: a detail can name a path, and this goes in the daemon's log.
      const said = await run(agentId).catch((error: unknown) => ({ error: kindOf(error) }))
      if (typeof said.error === 'string') deps.log(`a purge did not finish, and is tried again: ${said.error}`)
    }
    passing = false
    tries++
    settle()
  }
  const retried = async (agentId: string) => {
    try { return await run(agentId) } finally { settle() }
  }
  settle()
  return Object.assign(retried, { stop: () => { stopped = true; if (timer) clearTimeout(timer); timer = null } })
}

const kindOf = (error: unknown): string => error instanceof Error
  ? typeof (error as NodeJS.ErrnoException).code === 'string' ? (error as NodeJS.ErrnoException).code! : error.name
  : 'unknown failure'