@amsterdamdatalabs/adl-agent-control-darwin-arm64 0.1.4

package/packages/agent-settings/src/global-surface-sweep.ts

@@ -0,0 +1,2179 @@
+/**
+ * Safely inventory and remove machine-global agent host wiring (Claude, Codex,
+ * Cursor, OpenCode, Kimi, shell rc blocks, LaunchAgents)
+ * that enact-vps does not ship and that should have been repository-local.
+ *
+ * Discovery is broad. Authorization is narrow: apply mode accepts only a
+ * reviewed plan emitted by this module, matches every operation against the
+ * built-in surface allowlist, and verifies the target's SHA-256 fingerprint
+ * immediately before changing it. Discovery alone never authorizes deletion.
+ */
+
+import { spawnSync } from 'node:child_process'
+import { createHash } from 'node:crypto'
+import {
+  chmodSync,
+  chownSync,
+  cpSync,
+  copyFileSync,
+  lstatSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  readdirSync,
+  readlinkSync,
+  renameSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs'
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { BEGIN as KIMI_BEGIN, END as KIMI_END } from './kimi-hooks.ts'
+import { declaredLaunchAgentPlists } from '../../../packages/fleet/src/launch-agents.ts'
+
+const LAUNCH_AGENTS_DIR = 'Library/LaunchAgents'
+
+/**
+ * LaunchAgent scope is agent tooling only. A `~/Library/LaunchAgents` entry is
+ * a sweep candidate when its file name or its raw plist bytes (Label,
+ * Program/ProgramArguments, environment -- XML and binary plists both store
+ * these strings verbatim) contain, case-insensitively, one of these agent
+ * tool tokens. Everything else (GoogleUpdater, Keystone, other application
+ * updaters) is not an agent surface and is neither a candidate nor reported.
+ * LaunchAgents enact-vps declares in fleet/manifest.json are always in
+ * scope and protected by identity (see loadProtectionList).
+ */
+export const AGENT_TOOL_TOKENS = [
+  'lean-ctx',
+  'leanctx',
+  'adl',
+  'jcode',
+  'claude',
+  'codex',
+  'cursor',
+  'kimi',
+  'opencode',
+  'copilot',
+  'orca',
+] as const
+
+export function isAgentToolingLaunchAgent(name: string, content: string): boolean {
+  const haystack = `${name}\n${content}`.toLowerCase()
+  return AGENT_TOOL_TOKENS.some((token) => haystack.includes(token))
+}
+
+export interface PreservedRegion {
+  readonly begin: string
+  readonly end: string
+}
+
+export type SweepTarget =
+  /** Entries of a JSON object/array. `key` may be a `/`-separated nested path, e.g. `permissions/allow`. */
+  | { readonly kind: 'json-map'; readonly file: string; readonly key: string }
+  /**
+   * A hooks-shaped map: `document[key]` is an object keyed by event name,
+   * each value an array of hook groups (Claude/Codex: `{matcher?, hooks:
+   * [...]}`; Cursor: the group IS the leaf hook, `{command, timeout}`).
+   * Unlike `json-map` (which treats a whole per-event array as one
+   * candidate), this enumerates one candidate per GROUP — selector
+   * `/key/eventName/index` — so a single event can mix a still-sweepable
+   * entry with an entry that must never be a candidate (Orca's own
+   * user-level hook, 2026-09-27 decision: "Orca is allowed for adl", the
+   * managed layer calls it, keep the lock on) without the two fighting for
+   * the same removal unit. An event whose every group is removed loses the
+   * key entirely, matching `json-map`'s own convention.
+   */
+  | { readonly kind: 'json-hook-map'; readonly file: string; readonly key: string }
+  | { readonly kind: 'json-root'; readonly file: string }
+  | {
+      readonly kind: 'toml-tables'
+      readonly file: string
+      readonly prefixes: readonly string[]
+      /** A delimited region owned by another enact-vps deployer; never inspected or changed. */
+      readonly preserve?: PreservedRegion
+    }
+  /** Tool-injected marker-delimited regions (`# >>> x >>>`, `# x — begin`, `<!-- x -->`). */
+  | { readonly kind: 'text-blocks'; readonly file: string }
+  | {
+      readonly kind: 'dir-entries'
+      readonly dir: string
+      readonly ignore?: readonly string[]
+      readonly descend?: readonly string[]
+      /** Scheduled enforcement never removes these; they are reported as pending explicit approval. */
+      readonly requiresApproval?: boolean
+    }
+  | { readonly kind: 'path'; readonly path: string }
+  /**
+   * Directly-contained regular files of `dir` whose content contains `marker`
+   * as an exact full line within the first 5 lines. Unlike `dir-entries`, this
+   * is content-addressed, not membership-addressed: `dir` may hold many
+   * unrelated files (and subdirectories, symlinks) that must never be
+   * candidates just for living there.
+   */
+  | { readonly kind: 'marker-files'; readonly dir: string; readonly marker: string }
+
+const SHELL_RC_FILES = ['.zshenv', '.zprofile', '.zshrc', '.zlogin', '.bashenv', '.bashrc', '.bash_profile', '.profile']
+
+export const SWEEP_TARGETS: readonly SweepTarget[] = [
+  { kind: 'json-hook-map', file: '.claude/settings.json', key: 'hooks' },
+  { kind: 'json-map', file: '.claude/settings.json', key: 'mcpServers' },
+  { kind: 'json-map', file: '.claude/settings.json', key: 'enabledPlugins' },
+  { kind: 'json-map', file: '.claude/settings.json', key: 'extraKnownMarketplaces' },
+  { kind: 'json-map', file: '.claude/settings.json', key: 'permissions/allow' },
+  { kind: 'json-map', file: '.claude/settings.json', key: 'permissions/deny' },
+  { kind: 'json-map', file: '.claude/settings.json', key: 'permissions/ask' },
+  { kind: 'text-blocks', file: '.claude/CLAUDE.md' },
+  { kind: 'json-map', file: '.claude.json', key: 'mcpServers' },
+  { kind: 'dir-entries', dir: '.claude/plugins/cache' },
+  { kind: 'dir-entries', dir: '.claude/skills' },
+  { kind: 'dir-entries', dir: '.claude/commands' },
+  { kind: 'dir-entries', dir: '.claude/agents' },
+  { kind: 'dir-entries', dir: '.claude/plugins/repos' },
+  { kind: 'dir-entries', dir: '.claude/plugins/marketplaces' },
+  { kind: 'json-map', file: '.claude/plugins/installed_plugins.json', key: 'plugins' },
+  { kind: 'json-root', file: '.claude/plugins/known_marketplaces.json' },
+  { kind: 'json-hook-map', file: '.codex/hooks.json', key: 'hooks' },
+  { kind: 'toml-tables', file: '.codex/config.toml', prefixes: ['mcp_servers', 'hooks'] },
+  { kind: 'text-blocks', file: '.codex/AGENTS.md' },
+  { kind: 'dir-entries', dir: '.codex/rules' },
+  { kind: 'dir-entries', dir: '.codex/skills' },
+  { kind: 'dir-entries', dir: '.codex/plugins', descend: ['cache'] },
+  { kind: 'dir-entries', dir: '.codex/plugins/cache' },
+  { kind: 'dir-entries', dir: '.codex/marketplaces' },
+  {
+    kind: 'dir-entries',
+    dir: '.codex/cache',
+    descend: [
+      'bundled_plugin_exclusions',
+      'codex_app_directory',
+      'codex_apps_server_info',
+      'codex_apps_tools',
+      'remote_plugin_catalog',
+    ],
+  },
+  { kind: 'dir-entries', dir: '.codex/cache/bundled_plugin_exclusions' },
+  { kind: 'dir-entries', dir: '.codex/cache/codex_app_directory' },
+  { kind: 'dir-entries', dir: '.codex/cache/codex_apps_server_info' },
+  { kind: 'dir-entries', dir: '.codex/cache/codex_apps_tools' },
+  { kind: 'dir-entries', dir: '.codex/cache/remote_plugin_catalog' },
+  { kind: 'dir-entries', dir: '.codex/vendor_imports' },
+  { kind: 'json-hook-map', file: '.cursor/hooks.json', key: 'hooks' },
+  { kind: 'json-map', file: '.cursor/mcp.json', key: 'mcpServers' },
+  { kind: 'dir-entries', dir: '.cursor/skills' },
+  { kind: 'dir-entries', dir: '.cursor/skills-cursor' },
+  { kind: 'dir-entries', dir: '.cursor/commands' },
+  { kind: 'dir-entries', dir: '.cursor/agents' },
+  { kind: 'dir-entries', dir: '.cursor/plugins' },
+  { kind: 'dir-entries', dir: '.cursor/hooks' },
+  { kind: 'dir-entries', dir: '.cursor/rules' },
+  { kind: 'text-blocks', file: '.cursor/AGENTS.md' },
+  { kind: 'dir-entries', dir: '.agents', ignore: ['GLOBAL-AGENTS.md'], descend: ['skills'] },
+  { kind: 'dir-entries', dir: '.agents/skills' },
+  ...['.config/opencode/opencode.json', '.config/opencode/opencode.jsonc'].flatMap((file): SweepTarget[] => [
+    { kind: 'json-map', file, key: 'mcp' },
+    { kind: 'json-map', file, key: 'permission' },
+    { kind: 'json-map', file, key: 'plugin' },
+  ]),
+  { kind: 'dir-entries', dir: '.config/opencode/plugins' },
+  { kind: 'dir-entries', dir: '.config/opencode/skills' },
+  { kind: 'text-blocks', file: '.config/opencode/AGENTS.md' },
+  {
+    kind: 'toml-tables',
+    file: '.kimi-code/config.toml',
+    prefixes: ['hooks'],
+    preserve: { begin: KIMI_BEGIN, end: KIMI_END },
+  },
+  { kind: 'json-map', file: '.kimi-code/mcp.json', key: 'mcpServers' },
+  { kind: 'dir-entries', dir: '.kimi-code/skills' },
+  { kind: 'dir-entries', dir: '.kimi-code/plugins' },
+  { kind: 'text-blocks', file: '.kimi-code/AGENTS.md' },
+  ...SHELL_RC_FILES.map((file): SweepTarget => ({ kind: 'text-blocks', file })),
+  { kind: 'dir-entries', dir: 'Library/LaunchAgents', requiresApproval: true },
+  {
+    kind: 'marker-files',
+    dir: '.local/bin',
+    marker: '# Generated by .agents/setup/setup.sh -- do not edit.',
+  },
+]
+
+function managedFileTarget(file: string): boolean {
+  return SWEEP_TARGETS.some(
+    (target) =>
+      (target.kind === 'json-map' ||
+        target.kind === 'json-hook-map' ||
+        target.kind === 'json-root' ||
+        target.kind === 'toml-tables' ||
+        target.kind === 'text-blocks') &&
+      target.file === file,
+  )
+}
+
+function preservedRegionFor(file: string): PreservedRegion | undefined {
+  for (const target of SWEEP_TARGETS) {
+    if (target.kind === 'toml-tables' && target.file === file && target.preserve !== undefined) return target.preserve
+  }
+  return undefined
+}
+
+export function operationRequiresApproval(path: string): boolean {
+  return SWEEP_TARGETS.some(
+    (target) => target.kind === 'dir-entries' && target.requiresApproval === true && dirname(path) === target.dir,
+  )
+}
+
+export type RemovalItem =
+  | {
+      readonly kind: 'json-entry'
+      readonly target: string
+      readonly selector: string
+      readonly beforeSha256: string
+    }
+  | {
+      readonly kind: 'toml-table'
+      readonly target: string
+      readonly header: string
+      readonly beforeSha256: string
+    }
+  | {
+      readonly kind: 'toml-key'
+      readonly target: string
+      readonly key: string
+      readonly beforeSha256: string
+    }
+  | {
+      readonly kind: 'text-block'
+      readonly target: string
+      readonly name: string
+      readonly beforeSha256: string
+    }
+  | { readonly kind: 'path'; readonly target: string; readonly beforeSha256: string }
+
+export interface ProtectionList {
+  readonly schema: 1
+  readonly paths: readonly { readonly path: string; readonly reason: string }[]
+  readonly jsonEntries: readonly {
+    readonly target: string
+    readonly selector: string
+    readonly reason: string
+  }[]
+  readonly tomlTables: readonly {
+    readonly target: string
+    readonly header: string
+    readonly reason: string
+  }[]
+  /** Exact marker-block identities (file + block name) that are shipped/owned and must be retained. */
+  readonly textBlocks: readonly {
+    readonly target: string
+    readonly name: string
+    readonly reason: string
+  }[]
+  /**
+   * Declared shipped baseline of top-level keys for a settings file. When a
+   * baseline exists for a file, every other top-level JSON key (or TOML root
+   * key / table whose first segment is undeclared) is foreign and swept.
+   * Files without a baseline never lose root keys.
+   */
+  readonly rootKeys: readonly {
+    readonly target: string
+    readonly keys: readonly string[]
+    readonly reason: string
+  }[]
+}
+
+export interface ProtectedItem {
+  readonly removal: RemovalItem
+  readonly reason: string
+}
+
+export const EMPTY_PROTECTION: ProtectionList = {
+  schema: 1,
+  paths: [],
+  jsonEntries: [],
+  tomlTables: [],
+  textBlocks: [],
+  rootKeys: [],
+}
+
+export const DEFAULT_PROTECTION_PATH = fileURLToPath(new URL('../protected.json', import.meta.url))
+export const DEFAULT_MANIFEST_PATH = fileURLToPath(new URL('../../fleet/manifest.json', import.meta.url))
+
+export interface SweepNote {
+  readonly level: 'warn' | 'ok'
+  readonly text: string
+}
+
+export type SweepOperation =
+  | {
+      readonly id: string
+      readonly kind: 'write-file'
+      readonly path: string
+      readonly absolutePath: string
+      readonly beforeSha256: string
+      readonly removals: readonly RemovalItem[]
+      readonly content: string
+      readonly mode: number
+      readonly uid: number
+      readonly gid: number
+      readonly requiresApproval: false
+    }
+  | {
+      readonly id: string
+      readonly kind: 'remove-path'
+      readonly path: string
+      readonly absolutePath: string
+      readonly beforeSha256: string
+      readonly removals: readonly RemovalItem[]
+      readonly requiresApproval: boolean
+    }
+
+export interface ApprovedOperation {
+  readonly id: string
+  readonly kind: SweepOperation['kind']
+  readonly path: string
+  readonly beforeSha256: string
+  readonly removals: readonly RemovalItem[]
+}
+
+export interface ApprovalPlan {
+  readonly schema: 1
+  readonly home: string
+  readonly generatedAt: string
+  readonly operations: readonly ApprovedOperation[]
+}
+
+export interface SweepPlan {
+  readonly operations: readonly SweepOperation[]
+  readonly protected: readonly ProtectedItem[]
+  readonly notes: readonly SweepNote[]
+}
+
+export interface ApplyResult {
+  readonly applied: readonly ApprovedOperation[]
+  readonly alreadyClean: readonly string[]
+  readonly unapproved: readonly ApprovedOperation[]
+  readonly backupRoot: string | null
+}
+
+export interface EnforceResult extends ApplyResult {
+  readonly protectedItems: number
+  /** Candidates scheduled enforcement must not remove; they need a reviewed plan + apply. */
+  readonly pendingApproval: readonly ApprovedOperation[]
+}
+
+export interface ReviewCopyResult {
+  readonly destination: string
+  readonly copiedPaths: number
+  readonly copiedConfigFiles: number
+  readonly candidateItems: number
+  readonly protectedItems: number
+}
+
+interface DraftFile {
+  readonly path: string
+  readonly relativePath: string
+  readonly original: string
+  content: string
+  readonly mode: number
+  readonly uid: number
+  readonly gid: number
+  readonly removals: RemovalItem[]
+}
+
+export function clearJsonMap(
+  document: unknown,
+  key: string,
+): { readonly document: unknown; readonly cleared: readonly string[] } | null {
+  if (document === null || typeof document !== 'object' || Array.isArray(document)) return null
+  const root = document as Record<string, unknown>
+  const value = root[key]
+  if (value === null || typeof value !== 'object') return null
+
+  const cleared = Array.isArray(value) ? value.map((_, index) => String(index)) : Object.keys(value)
+  if (cleared.length === 0) return null
+
+  return { document: { ...root, [key]: Array.isArray(value) ? [] : {} }, cleared }
+}
+
+export function dropTomlTables(
+  text: string,
+  prefixes: readonly string[],
+): { readonly text: string; readonly dropped: readonly string[] } {
+  const kept: string[] = []
+  const dropped: string[] = []
+  let dropping = false
+
+  for (const line of text.split('\n')) {
+    const trimmed = line.trim()
+    if (trimmed.startsWith('[')) {
+      const name = trimmed.slice(trimmed.startsWith('[[') ? 2 : 1).replace(/\]+$/, '')
+      dropping = prefixes.some((prefix) => name === prefix || name.startsWith(`${prefix}.`))
+      if (dropping) dropped.push(trimmed)
+    }
+    if (!dropping) kept.push(line)
+  }
+
+  if (dropped.length === 0) return { text, dropped }
+  return { text: kept.join('\n').replace(/\n{3,}/g, '\n\n'), dropped }
+}
+
+function messageOf(cause: unknown): string {
+  return cause instanceof Error ? cause.message : String(cause)
+}
+
+function pathExists(path: string): boolean {
+  try {
+    lstatSync(path)
+    return true
+  } catch (cause) {
+    const code =
+      cause !== null && typeof cause === 'object' && 'code' in cause
+        ? (cause as { readonly code?: unknown }).code
+        : undefined
+    if (code === 'ENOENT' || code === 'ENOTDIR') return false
+    throw cause
+  }
+}
+
+function relativeInside(root: string, path: string): string {
+  const value = relative(root, path)
+  if (value.length === 0 || value === '..' || value.startsWith(`..${sep}`) || isAbsolute(value)) {
+    throw new Error(`path escapes its allowed root: ${path}`)
+  }
+  return value.split(sep).join('/')
+}
+
+function insideHome(home: string, relativePath: string): string {
+  if (relativePath.length === 0 || isAbsolute(relativePath)) {
+    throw new Error(`expected a non-empty path relative to home: ${relativePath}`)
+  }
+  const path = resolve(home, relativePath)
+  relativeInside(home, path)
+  return path
+}
+
+function fingerprintPath(path: string): string {
+  const hash = createHash('sha256')
+
+  const visit = (current: string, label: string): void => {
+    const stat = lstatSync(current)
+    if (stat.isSymbolicLink()) {
+      hash.update(`link\0${label}\0${readlinkSync(current)}\0`)
+      return
+    }
+    if (stat.isDirectory()) {
+      hash.update(`dir\0${label}\0`)
+      for (const name of readdirSync(current).sort()) visit(join(current, name), `${label}/${name}`)
+      return
+    }
+    if (stat.isFile()) {
+      hash.update(`file\0${label}\0${stat.mode & 0o777}\0`)
+      hash.update(readFileSync(current))
+      hash.update('\0')
+      return
+    }
+    hash.update(`other\0${label}\0${stat.mode}\0`)
+  }
+
+  visit(path, '.')
+  return `sha256:${hash.digest('hex')}`
+}
+
+function jsonPointerPart(value: string): string {
+  return value.replaceAll('~', '~0').replaceAll('/', '~1')
+}
+
+function assertRelativeProtectionPath(value: string, label: string): void {
+  if (
+    value.length === 0 ||
+    isAbsolute(value) ||
+    value === '..' ||
+    value.startsWith('../') ||
+    value.includes('/../') ||
+    value.endsWith('/..')
+  ) {
+    throw new Error(`${label} must be a path relative to home: ${value}`)
+  }
+}
+
+export function decodeProtectionList(value: unknown): ProtectionList {
+  if (
+    !isRecord(value) ||
+    value.schema !== 1 ||
+    !Array.isArray(value.paths) ||
+    !Array.isArray(value.json_entries) ||
+    !Array.isArray(value.toml_tables)
+  ) {
+    throw new Error('protection list must have schema 1 and paths, json_entries, and toml_tables arrays')
+  }
+
+  const paths = value.paths.map((raw) => {
+    if (
+      !isRecord(raw) ||
+      typeof raw.path !== 'string' ||
+      typeof raw.reason !== 'string' ||
+      raw.reason.length === 0
+    ) {
+      throw new Error('protection list contains an invalid path entry')
+    }
+    assertRelativeProtectionPath(raw.path, 'protected path')
+    if (raw.sha256 !== undefined || raw.mutable_file !== undefined) {
+      throw new Error('protected paths are identity-only and must not contain fingerprints')
+    }
+    return { path: raw.path, reason: raw.reason }
+  })
+  const jsonEntries = value.json_entries.map((raw) => {
+    if (
+      !isRecord(raw) ||
+      typeof raw.target !== 'string' ||
+      typeof raw.selector !== 'string' ||
+      !raw.selector.startsWith('/') ||
+      typeof raw.reason !== 'string' ||
+      raw.reason.length === 0
+    ) {
+      throw new Error('protection list contains an invalid JSON entry')
+    }
+    assertRelativeProtectionPath(raw.target, 'protected JSON target')
+    if (raw.sha256 !== undefined) {
+      throw new Error('protected JSON entries are identity-only and must not contain fingerprints')
+    }
+    return { target: raw.target, selector: raw.selector, reason: raw.reason }
+  })
+  const tomlTables = value.toml_tables.map((raw) => {
+    if (
+      !isRecord(raw) ||
+      typeof raw.target !== 'string' ||
+      typeof raw.header !== 'string' ||
+      !raw.header.startsWith('[') ||
+      typeof raw.reason !== 'string' ||
+      raw.reason.length === 0
+    ) {
+      throw new Error('protection list contains an invalid TOML table entry')
+    }
+    assertRelativeProtectionPath(raw.target, 'protected TOML target')
+    if (raw.sha256 !== undefined) {
+      throw new Error('protected TOML tables are identity-only and must not contain fingerprints')
+    }
+    return { target: raw.target, header: raw.header, reason: raw.reason }
+  })
+  if (value.text_blocks !== undefined && !Array.isArray(value.text_blocks)) {
+    throw new Error('protection list text_blocks must be an array')
+  }
+  const textBlocks = ((value.text_blocks ?? []) as unknown[]).map((raw) => {
+    if (
+      !isRecord(raw) ||
+      typeof raw.target !== 'string' ||
+      typeof raw.name !== 'string' ||
+      raw.name.length === 0 ||
+      typeof raw.reason !== 'string' ||
+      raw.reason.length === 0
+    ) {
+      throw new Error('protection list contains an invalid text block entry')
+    }
+    assertRelativeProtectionPath(raw.target, 'protected text block target')
+    return { target: raw.target, name: raw.name, reason: raw.reason }
+  })
+  if (value.root_keys !== undefined && !Array.isArray(value.root_keys)) {
+    throw new Error('protection list root_keys must be an array')
+  }
+  const rootKeys = ((value.root_keys ?? []) as unknown[]).map((raw) => {
+    if (
+      !isRecord(raw) ||
+      typeof raw.target !== 'string' ||
+      !Array.isArray(raw.keys) ||
+      raw.keys.length === 0 ||
+      !raw.keys.every((key) => typeof key === 'string' && key.length > 0) ||
+      new Set(raw.keys).size !== raw.keys.length ||
+      typeof raw.reason !== 'string' ||
+      raw.reason.length === 0
+    ) {
+      throw new Error('protection list contains an invalid root key baseline')
+    }
+    assertRelativeProtectionPath(raw.target, 'root key baseline target')
+    return { target: raw.target, keys: raw.keys as string[], reason: raw.reason }
+  })
+
+  const identities = [
+    ...paths.map((entry) => `path:${entry.path}`),
+    ...jsonEntries.map((entry) => `json:${entry.target}#${entry.selector}`),
+    ...tomlTables.map((entry) => `toml:${entry.target}#${entry.header}`),
+    ...textBlocks.map((entry) => `block:${entry.target}#${entry.name}`),
+    ...rootKeys.map((entry) => `root-keys:${entry.target}`),
+  ]
+  if (new Set(identities).size !== identities.length) throw new Error('protection list contains duplicate entries')
+
+  return { schema: 1, paths, jsonEntries, tomlTables, textBlocks, rootKeys }
+}
+
+/**
+ * The checked-in protection list plus every LaunchAgent plist enact-vps
+ * itself ships (declared under `launch_agents` in fleet/manifest.json).
+ * Shipped-job protection is derived from the manifest, never hand-listed.
+ */
+export function loadProtectionList(path = DEFAULT_PROTECTION_PATH, manifestPath = DEFAULT_MANIFEST_PATH): ProtectionList {
+  const list = decodeProtectionList(JSON.parse(readFileSync(path, 'utf8')))
+  const declared = declaredLaunchAgentPlists(JSON.parse(readFileSync(manifestPath, 'utf8')))
+  const listed = new Set(list.paths.map((entry) => entry.path))
+  const derived = declared
+    .filter((entry) => !listed.has(entry.path))
+    .map((entry) => ({ path: entry.path, reason: `LaunchAgent shipped by enact-vps (fleet/manifest.json ${entry.declaredAt})` }))
+  return { ...list, paths: [...list.paths, ...derived] }
+}
+
+function tomlHeaderName(header: string): string {
+  const trimmed = header.trim()
+  return trimmed.slice(trimmed.startsWith('[[') ? 2 : 1).replace(/\]+$/, '')
+}
+
+function fingerprintBytes(value: string): string {
+  return `sha256:${createHash('sha256').update(value).digest('hex')}`
+}
+
+function fingerprintJsonValue(value: unknown): string {
+  return fingerprintBytes(JSON.stringify(value))
+}
+
+/**
+ * Orca (2026-09-27 decision: "keep the orca hooks, let orca manage it, Orca
+ * is allowed for adl"; the MANAGED layer calls Orca, the managed-hooks-only
+ * lock stays on) installs its OWN user-level hooks on every hook-capable
+ * surface: Claude `~/.claude/settings.json` (`hooks` + `statusLine`), Codex
+ * `~/.codex/hooks.json`, Kimi `~/.kimi-code/config.toml` (`[[hooks]]`), and
+ * Cursor `~/.cursor/hooks.json`. Those entries must never be swept as
+ * "third-party wiring that should have been repo-local" the way a genuine
+ * foreign tool's hook is.
+ *
+ * Identity is by EXACT reference to the real install path, ground-truthed
+ * against this Mac's own live files (`~/.claude/settings.json`,
+ * `~/.codex/hooks.json`, `~/.cursor/hooks.json`, `~/.kimi-code/config.toml`,
+ * fetched 2026-09-27): Orca renders the path as `${HOME-}/.orca/agent-hooks/`
+ * (Claude), or resolves it to an absolute `<home>/.orca/agent-hooks/` at
+ * install time (Codex, Cursor, Kimi) — never a fixed literal across
+ * machines. The one substring every real form shares is the literal path
+ * segment `.orca/agent-hooks/`, so that is the marker, not a loose token
+ * match on "orca" alone: `/opt/orca/kimi-hook.sh` (a look-alike that merely
+ * mentions "orca" — see `third-party-wiring.test.ts`'s `KIMI_ORCA_HOOK`
+ * fixture) does NOT contain this segment and stays a genuine sweep
+ * candidate.
+ */
+const ORCA_HOOK_REFERENCE_MARKER = '.orca/agent-hooks/'
+
+const ORCA_HOOK_PROTECTION_REASON =
+  "Orca's own user-level agent hook (exact reference to .orca/agent-hooks/); Orca is allowed for adl (Tarun, 2026-09-27) — the managed layer calls it, this user-level copy is not swept"
+
+/** Recursively true iff any string reachable from `value` contains the exact Orca hook path segment. */
+function containsOrcaHookReference(value: unknown): boolean {
+  if (typeof value === 'string') return value.includes(ORCA_HOOK_REFERENCE_MARKER)
+  if (Array.isArray(value)) return value.some(containsOrcaHookReference)
+  if (isRecord(value)) return Object.values(value).some(containsOrcaHookReference)
+  return false
+}
+
+/** Same as `protectionFor`, but checks the live Orca-content identity first, ahead of the static, selector-based `protection` list. */
+function protectionForValue(removal: RemovalItem, value: unknown, protection: ProtectionList): string | null {
+  if (containsOrcaHookReference(value)) return ORCA_HOOK_PROTECTION_REASON
+  return protectionFor(removal, protection)
+}
+
+function protectionFor(
+  removal: RemovalItem,
+  protection: ProtectionList,
+): string | null {
+  if (removal.kind === 'path') {
+    const match = protection.paths.find((entry) => removal.target === entry.path)
+    return match?.reason ?? null
+  }
+  if (removal.kind === 'json-entry') {
+    const match = protection.jsonEntries.find(
+      (entry) => entry.target === removal.target && entry.selector === removal.selector,
+    )
+    return match?.reason ?? null
+  }
+  if (removal.kind === 'text-block') {
+    const match = protection.textBlocks.find((entry) => entry.target === removal.target && entry.name === removal.name)
+    return match?.reason ?? null
+  }
+  if (removal.kind === 'toml-key') return null
+  const match = protection.tomlTables.find(
+    (entry) => entry.target === removal.target && entry.header === removal.header,
+  )
+  return match?.reason ?? null
+}
+
+function valueAtPath(document: Record<string, unknown>, path: readonly string[]): unknown {
+  let current: unknown = document
+  for (const part of path) {
+    if (!isRecord(current) || !Object.hasOwn(current, part)) return undefined
+    current = current[part]
+  }
+  return current
+}
+
+function withValueAtPath(
+  document: Record<string, unknown>,
+  path: readonly string[],
+  value: unknown,
+): Record<string, unknown> {
+  const [head, ...rest] = path
+  if (head === undefined) throw new Error('empty JSON key path')
+  if (rest.length === 0) return { ...document, [head]: value }
+  const child = document[head]
+  if (!isRecord(child)) throw new Error(`JSON key path is not an object: ${path.join('/')}`)
+  return { ...document, [head]: withValueAtPath(child, rest, value) }
+}
+
+function filterJsonMap(
+  document: unknown,
+  key: string,
+  target: string,
+  protection: ProtectionList,
+): {
+  readonly document: unknown
+  readonly removals: readonly RemovalItem[]
+  readonly protected: readonly ProtectedItem[]
+} | null {
+  if (!isRecord(document)) return null
+  const path = key.split('/')
+  const value = valueAtPath(document, path)
+  if (value === null || typeof value !== 'object') return null
+  const pointer = path.map(jsonPointerPart).join('/')
+
+  const removals: RemovalItem[] = []
+  const protectedItems: ProtectedItem[] = []
+  if (Array.isArray(value)) {
+    const kept: unknown[] = []
+    for (const [index, entry] of value.entries()) {
+      const removal: RemovalItem = {
+        kind: 'json-entry',
+        target,
+        selector: `/${pointer}/${index}`,
+        beforeSha256: fingerprintJsonValue(entry),
+      }
+      const reason = protectionForValue(removal, entry, protection)
+      if (reason === null) removals.push(removal)
+      else {
+        kept.push(entry)
+        protectedItems.push({ removal, reason })
+      }
+    }
+    if (removals.length === 0 && protectedItems.length === 0) return null
+    return { document: removals.length === 0 ? document : withValueAtPath(document, path, kept), removals, protected: protectedItems }
+  }
+
+  const kept: Record<string, unknown> = {}
+  for (const [name, entry] of Object.entries(value as Record<string, unknown>)) {
+    const removal: RemovalItem = {
+      kind: 'json-entry',
+      target,
+      selector: `/${pointer}/${jsonPointerPart(name)}`,
+      beforeSha256: fingerprintJsonValue(entry),
+    }
+    const reason = protectionForValue(removal, entry, protection)
+    if (reason === null) removals.push(removal)
+    else {
+      kept[name] = entry
+      protectedItems.push({ removal, reason })
+    }
+  }
+  if (removals.length === 0 && protectedItems.length === 0) return null
+  return { document: removals.length === 0 ? document : withValueAtPath(document, path, kept), removals, protected: protectedItems }
+}
+
+/**
+ * `json-hook-map` filter: `document[key]` is an object keyed by event name,
+ * each value an array of hook groups. One candidate per GROUP (selector
+ * `/key/eventName/index`), not per event — see the `SweepTarget` union
+ * member's own doc comment for why. An event that loses every group loses
+ * the key entirely (same convention as `filterJsonMap`'s object branch); a
+ * malformed event whose value is not an array falls back to whole-value
+ * removal so a hand-edited file never throws instead of sweeping.
+ */
+interface FilteredEntry {
+  readonly kept: unknown
+  readonly removals: readonly RemovalItem[]
+  readonly protected: readonly ProtectedItem[]
+}
+
+/** One event's array of hook groups: one candidate per group (selector `.../<index>`). Extracted from `filterJsonHookMap` to keep both functions under the cognitive-complexity limit. */
+function filterHookGroups(groups: readonly unknown[], selectorPrefix: string, target: string, protection: ProtectionList): FilteredEntry {
+  const removals: RemovalItem[] = []
+  const protectedItems: ProtectedItem[] = []
+  const kept: unknown[] = []
+  for (const [index, group] of groups.entries()) {
+    const removal: RemovalItem = {
+      kind: 'json-entry',
+      target,
+      selector: `${selectorPrefix}/${index}`,
+      beforeSha256: fingerprintJsonValue(group),
+    }
+    const reason = protectionForValue(removal, group, protection)
+    if (reason === null) removals.push(removal)
+    else {
+      kept.push(group)
+      protectedItems.push({ removal, reason })
+    }
+  }
+  return { kept, removals, protected: protectedItems }
+}
+
+function filterJsonHookMap(
+  document: unknown,
+  key: string,
+  target: string,
+  protection: ProtectionList,
+): {
+  readonly document: unknown
+  readonly removals: readonly RemovalItem[]
+  readonly protected: readonly ProtectedItem[]
+} | null {
+  if (!isRecord(document)) return null
+  const path = key.split('/')
+  const value = valueAtPath(document, path)
+  if (!isRecord(value)) return null
+  const pointer = path.map(jsonPointerPart).join('/')
+
+  const removals: RemovalItem[] = []
+  const protectedItems: ProtectedItem[] = []
+  const kept: Record<string, unknown> = {}
+  for (const [eventName, groups] of Object.entries(value)) {
+    const selectorPrefix = `/${pointer}/${jsonPointerPart(eventName)}`
+    if (!Array.isArray(groups)) {
+      const removal: RemovalItem = { kind: 'json-entry', target, selector: selectorPrefix, beforeSha256: fingerprintJsonValue(groups) }
+      const reason = protectionForValue(removal, groups, protection)
+      if (reason === null) removals.push(removal)
+      else {
+        kept[eventName] = groups
+        protectedItems.push({ removal, reason })
+      }
+      continue
+    }
+    const filtered = filterHookGroups(groups, selectorPrefix, target, protection)
+    removals.push(...filtered.removals)
+    protectedItems.push(...filtered.protected)
+    if ((filtered.kept as unknown[]).length > 0) kept[eventName] = filtered.kept
+  }
+  if (removals.length === 0 && protectedItems.length === 0) return null
+  return { document: removals.length === 0 ? document : withValueAtPath(document, path, kept), removals, protected: protectedItems }
+}
+
+function filterJsonRoot(
+  document: unknown,
+  target: string,
+  protection: ProtectionList,
+): {
+  readonly document: unknown
+  readonly removals: readonly RemovalItem[]
+  readonly protected: readonly ProtectedItem[]
+} | null {
+  if (!isRecord(document)) return null
+  const kept: Record<string, unknown> = {}
+  const removals: RemovalItem[] = []
+  const protectedItems: ProtectedItem[] = []
+  for (const [name, entry] of Object.entries(document)) {
+    const removal: RemovalItem = {
+      kind: 'json-entry',
+      target,
+      selector: `/${jsonPointerPart(name)}`,
+      beforeSha256: fingerprintJsonValue(entry),
+    }
+    const reason = protectionForValue(removal, entry, protection)
+    if (reason === null) removals.push(removal)
+    else {
+      kept[name] = entry
+      protectedItems.push({ removal, reason })
+    }
+  }
+  if (removals.length === 0 && protectedItems.length === 0) return null
+  return { document: removals.length === 0 ? document : kept, removals, protected: protectedItems }
+}
+
+interface TomlBlock {
+  readonly header: string | null
+  readonly lines: readonly string[]
+  /** True for a region owned by another deployer (kept verbatim, never inspected). */
+  readonly preserved: boolean
+}
+
+function splitTomlBlocks(text: string, preserve?: PreservedRegion): readonly TomlBlock[] {
+  const blocks: { header: string | null; lines: string[]; preserved: boolean }[] = []
+  let current: { header: string | null; lines: string[]; preserved: boolean } = {
+    header: null,
+    lines: [],
+    preserved: false,
+  }
+  let inRegion = false
+  for (const line of text.split('\n')) {
+    const trimmed = line.trim()
+    if (inRegion) {
+      current.lines.push(line)
+      if (trimmed === preserve?.end) {
+        inRegion = false
+        blocks.push(current)
+        current = { header: null, lines: [], preserved: false }
+      }
+      continue
+    }
+    if (preserve !== undefined && trimmed === preserve.begin) {
+      if (current.lines.length > 0 || current.header !== null) blocks.push(current)
+      current = { header: null, lines: [line], preserved: true }
+      inRegion = true
+      continue
+    }
+    if (trimmed.startsWith('[')) {
+      if (current.lines.length > 0) blocks.push(current)
+      current = { header: trimmed, lines: [line], preserved: false }
+    } else current.lines.push(line)
+  }
+  if (inRegion) throw new Error(`unterminated preserved region: ${preserve?.begin}`)
+  blocks.push(current)
+  return blocks
+}
+
+function tomlFirstSegment(header: string): string {
+  const name = tomlHeaderName(header).trim()
+  const quote = name[0]
+  if (quote === '"' || quote === "'") {
+    const close = name.indexOf(quote, 1)
+    return close === -1 ? name : name.slice(1, close)
+  }
+  return name.split('.')[0]!.trim()
+}
+
+interface TomlRootKey {
+  readonly key: string
+  /** Line indexes inside the root block, inclusive. */
+  readonly start: number
+  readonly end: number
+}
+
+/** Top-level `key = value` statements before the first table, including multi-line arrays/strings. */
+function tomlRootKeys(lines: readonly string[]): readonly TomlRootKey[] {
+  const keys: TomlRootKey[] = []
+  let index = 0
+  while (index < lines.length) {
+    const match = /^\s*("[^"]*"|'[^']*'|[A-Za-z0-9_-]+)\s*(?:\.[^=]*)?=(.*)$/.exec(lines[index]!)
+    if (match === null) {
+      index += 1
+      continue
+    }
+    const rawKey = match[1]!
+    const key = rawKey.startsWith('"') || rawKey.startsWith("'") ? rawKey.slice(1, -1) : rawKey
+    const start = index
+    let depth = 0
+    let multiline: '"""' | "'''" | null = null
+    let text = match[2]!
+    for (;;) {
+      let position = 0
+      while (position < text.length) {
+        if (multiline !== null) {
+          const close = text.indexOf(multiline, position)
+          if (close === -1) {
+            position = text.length
+            break
+          }
+          position = close + 3
+          multiline = null
+          continue
+        }
+        const character = text[position]!
+        if (text.startsWith('"""', position) || text.startsWith("'''", position)) {
+          multiline = text.slice(position, position + 3) as '"""' | "'''"
+          position += 3
+        } else if (character === '"' || character === "'") {
+          let close = position + 1
+          while (close < text.length && text[close] !== character) close += character === '"' && text[close] === '\\' ? 2 : 1
+          position = close + 1
+        } else if (character === '#') {
+          break
+        } else {
+          if (character === '[' || character === '{') depth += 1
+          if (character === ']' || character === '}') depth -= 1
+          position += 1
+        }
+      }
+      if ((depth <= 0 && multiline === null) || index + 1 >= lines.length) break
+      index += 1
+      text = lines[index]!
+    }
+    keys.push({ key, start, end: index })
+    index += 1
+  }
+  return keys
+}
+
+export interface TextBlock {
+  readonly name: string
+  /** Line indexes, inclusive. */
+  readonly start: number
+  readonly end: number
+  readonly text: string
+}
+
+const TEXT_BLOCK_SYNTAXES: readonly { readonly open: RegExp; readonly close: (name: string) => string }[] = [
+  { open: /^# >>> (.+?) >>>$/, close: (name) => `# <<< ${name} <<<` },
+  { open: /^# (.+?) — begin$/, close: (name) => `# ${name} — end` },
+  { open: /^<!-- (?!\/)(.+?) -->$/, close: (name) => `<!-- /${name} -->` },
+]
+
+/** Outermost tool-injected marker-delimited regions. Unterminated openers are ordinary lines. */
+export function findTextBlocks(text: string): readonly TextBlock[] {
+  const lines = text.split('\n')
+  const blocks: TextBlock[] = []
+  let index = 0
+  while (index < lines.length) {
+    const trimmed = lines[index]!.trim()
+    let found: TextBlock | null = null
+    for (const syntax of TEXT_BLOCK_SYNTAXES) {
+      const match = syntax.open.exec(trimmed)
+      if (match === null) continue
+      const name = match[1]!
+      const closer = syntax.close(name)
+      const end = lines.findIndex((line, candidate) => candidate > index && line.trim() === closer)
+      if (end === -1) continue
+      found = { name, start: index, end, text: lines.slice(index, end + 1).join('\n') }
+      break
+    }
+    if (found === null) {
+      index += 1
+      continue
+    }
+    blocks.push(found)
+    index = found.end + 1
+  }
+  return blocks
+}
+
+function filterTextBlocks(
+  text: string,
+  target: string,
+  protection: ProtectionList,
+): { readonly text: string; readonly removals: readonly RemovalItem[]; readonly protected: readonly ProtectedItem[] } {
+  const lines = text.split('\n')
+  const drop = new Set<number>()
+  const removals: RemovalItem[] = []
+  const protectedItems: ProtectedItem[] = []
+  for (const block of findTextBlocks(text)) {
+    const removal: RemovalItem = { kind: 'text-block', target, name: block.name, beforeSha256: fingerprintBytes(block.text) }
+    const reason = protectionFor(removal, protection)
+    if (reason !== null) {
+      protectedItems.push({ removal, reason })
+      continue
+    }
+    removals.push(removal)
+    for (let line = block.start; line <= block.end; line += 1) drop.add(line)
+    let previous = block.start - 1
+    while (previous >= 0 && drop.has(previous)) previous -= 1
+    const next = block.end + 1
+    if (next < lines.length && lines[next]!.trim() === '' && (previous < 0 || lines[previous]!.trim() === '')) {
+      drop.add(next)
+    }
+  }
+  if (removals.length === 0) return { text, removals, protected: protectedItems }
+  return { text: lines.filter((_, index) => !drop.has(index)).join('\n'), removals, protected: protectedItems }
+}
+
+function filterJsonRootKeys(
+  document: unknown,
+  target: string,
+  allowed: readonly string[],
+  protection: ProtectionList,
+): { readonly document: unknown; readonly removals: readonly RemovalItem[] } | null {
+  if (!isRecord(document)) return null
+  const kept: Record<string, unknown> = {}
+  const removals: RemovalItem[] = []
+  for (const [name, entry] of Object.entries(document)) {
+    const removal: RemovalItem = {
+      kind: 'json-entry',
+      target,
+      selector: `/${jsonPointerPart(name)}`,
+      beforeSha256: fingerprintJsonValue(entry),
+    }
+    if (allowed.includes(name) || protectionForValue(removal, entry, protection) !== null) kept[name] = entry
+    else removals.push(removal)
+  }
+  if (removals.length === 0) return null
+  return { document: kept, removals }
+}
+
+function filterTomlRootKeys(
+  text: string,
+  target: string,
+  allowed: readonly string[],
+  protection: ProtectionList,
+): { readonly text: string; readonly removals: readonly RemovalItem[] } {
+  const blocks = splitTomlBlocks(text, preservedRegionFor(target))
+  const kept: string[][] = []
+  const removals: RemovalItem[] = []
+  for (const [position, block] of blocks.entries()) {
+    if (block.preserved) {
+      kept.push([...block.lines])
+      continue
+    }
+    if (block.header === null) {
+      if (position !== 0) {
+        kept.push([...block.lines])
+        continue
+      }
+      const drop = new Set<number>()
+      for (const rootKey of tomlRootKeys(block.lines)) {
+        if (allowed.includes(rootKey.key)) continue
+        const removed = block.lines.slice(rootKey.start, rootKey.end + 1)
+        removals.push({ kind: 'toml-key', target, key: rootKey.key, beforeSha256: fingerprintBytes(removed.join('\n')) })
+        for (let line = rootKey.start; line <= rootKey.end; line += 1) drop.add(line)
+      }
+      kept.push(block.lines.filter((_, index) => !drop.has(index)))
+      continue
+    }
+    const removal: RemovalItem = {
+      kind: 'toml-table',
+      target,
+      header: block.header,
+      beforeSha256: fingerprintBytes(block.lines.join('\n')),
+    }
+    if (
+      allowed.includes(tomlFirstSegment(block.header)) ||
+      protectionForValue(removal, block.lines.join('\n'), protection) !== null
+    ) {
+      kept.push([...block.lines])
+    } else removals.push(removal)
+  }
+  return {
+    text: removals.length === 0 ? text : kept.flat().join('\n').replace(/\n{3,}/g, '\n\n'),
+    removals,
+  }
+}
+
+function filterTomlTables(
+  text: string,
+  prefixes: readonly string[],
+  target: string,
+  protection: ProtectionList,
+): { readonly text: string; readonly removals: readonly RemovalItem[]; readonly protected: readonly ProtectedItem[] } {
+  const blocks = splitTomlBlocks(text, preservedRegionFor(target))
+  const kept: string[][] = []
+  const removals: RemovalItem[] = []
+  const protectedItems: ProtectedItem[] = []
+  for (const block of blocks) {
+    if (block.header === null || block.preserved) {
+      kept.push([...block.lines])
+      continue
+    }
+    const name = tomlHeaderName(block.header)
+    const selected = prefixes.some((prefix) => name === prefix || name.startsWith(`${prefix}.`))
+    if (!selected) {
+      kept.push([...block.lines])
+      continue
+    }
+    const removal: RemovalItem = {
+      kind: 'toml-table',
+      target,
+      header: block.header,
+      beforeSha256: fingerprintBytes(block.lines.join('\n')),
+    }
+    const reason = protectionForValue(removal, block.lines.join('\n'), protection)
+    if (reason === null) removals.push(removal)
+    else {
+      kept.push([...block.lines])
+      protectedItems.push({ removal, reason })
+    }
+  }
+
+  return {
+    text: removals.length === 0 ? text : kept.flat().join('\n').replace(/\n{3,}/g, '\n\n'),
+    removals,
+    protected: protectedItems,
+  }
+}
+
+function entriesOf(dir: string, notes: SweepNote[]): readonly string[] {
+  if (!pathExists(dir)) return []
+  try {
+    if (!lstatSync(dir).isDirectory()) {
+      notes.push({ level: 'warn', text: `${dir} is not a directory; left untouched` })
+      return []
+    }
+    return readdirSync(dir).filter((name) => name !== '.DS_Store')
+  } catch (cause) {
+    notes.push({ level: 'warn', text: `${dir} could not be read; left untouched (${messageOf(cause)})` })
+    return []
+  }
+}
+
+/** True iff `marker` appears as an exact, standalone line within the first 5 lines of `content`. */
+function hasMarkerLine(content: string, marker: string): boolean {
+  return content.split('\n').slice(0, 5).includes(marker)
+}
+
+function launchAgentInScope(path: string, name: string): boolean {
+  const stat = lstatSync(path)
+  return isAgentToolingLaunchAgent(name, stat.isFile() ? readFileSync(path).toString('latin1') : '')
+}
+
+function editableFile(
+  home: string,
+  relativePath: string,
+  drafts: Map<string, DraftFile>,
+  notes: SweepNote[],
+): DraftFile | null {
+  const path = insideHome(home, relativePath)
+  const existing = drafts.get(path)
+  if (existing !== undefined) return existing
+  if (!pathExists(path)) return null
+
+  const stat = lstatSync(path)
+  if (!stat.isFile()) {
+    notes.push({ level: 'warn', text: `${path} is not a regular file; left untouched` })
+    return null
+  }
+  const content = readFileSync(path, 'utf8')
+  const draft: DraftFile = {
+    path,
+    relativePath,
+    original: content,
+    content,
+    mode: stat.mode & 0o777,
+    uid: stat.uid,
+    gid: stat.gid,
+    removals: [],
+  }
+  drafts.set(path, draft)
+  return draft
+}
+
+export function planGlobalSweep(
+  homeInput: string,
+  protection: ProtectionList = loadProtectionList(),
+): SweepPlan {
+  if (!isAbsolute(homeInput)) throw new Error(`--home must be absolute: ${homeInput}`)
+  const home = resolve(homeInput)
+  const drafts = new Map<string, DraftFile>()
+  const removals = new Map<string, SweepOperation>()
+  const protectedItems: ProtectedItem[] = []
+  const notes: SweepNote[] = []
+
+  // Declared shipped baselines run first, so a wholly foreign container key is
+  // reported once as a root removal instead of entry-by-entry.
+  for (const baseline of protection.rootKeys) {
+    if (!managedFileTarget(baseline.target)) {
+      throw new Error(`root key baseline targets an unmanaged file: ${baseline.target}`)
+    }
+    const draft = editableFile(home, baseline.target, drafts, notes)
+    if (draft === null) continue
+    if (baseline.target.endsWith('.toml')) {
+      const result = filterTomlRootKeys(draft.content, baseline.target, baseline.keys, protection)
+      if (result.removals.length === 0) continue
+      draft.content = result.text
+      draft.removals.push(...result.removals)
+      continue
+    }
+    let parsed: unknown
+    try {
+      parsed = JSON.parse(draft.content)
+    } catch {
+      notes.push({ level: 'warn', text: `${draft.path} is not valid JSON; left untouched` })
+      continue
+    }
+    const result = filterJsonRootKeys(parsed, baseline.target, baseline.keys, protection)
+    if (result === null) continue
+    draft.content = `${JSON.stringify(result.document, null, 2)}\n`
+    draft.removals.push(...result.removals)
+  }
+
+  for (const target of SWEEP_TARGETS) {
+    if (target.kind === 'text-blocks') {
+      const draft = editableFile(home, target.file, drafts, notes)
+      if (draft === null) continue
+      const result = filterTextBlocks(draft.content, target.file, protection)
+      protectedItems.push(...result.protected)
+      if (result.removals.length === 0) continue
+      draft.content = result.text
+      draft.removals.push(...result.removals)
+      continue
+    }
+
+    if (target.kind === 'json-map' || target.kind === 'json-hook-map' || target.kind === 'json-root') {
+      const draft = editableFile(home, target.file, drafts, notes)
+      if (draft === null) continue
+      let parsed: unknown
+      try {
+        parsed = JSON.parse(draft.content)
+      } catch {
+        notes.push({ level: 'warn', text: `${draft.path} is not valid JSON; left untouched` })
+        continue
+      }
+
+      if (target.kind === 'json-map') {
+        const result = filterJsonMap(parsed, target.key, target.file, protection)
+        if (result === null) continue
+        protectedItems.push(...result.protected)
+        if (result.removals.length === 0) continue
+        draft.content = `${JSON.stringify(result.document, null, 2)}\n`
+        draft.removals.push(...result.removals)
+      } else if (target.kind === 'json-hook-map') {
+        const result = filterJsonHookMap(parsed, target.key, target.file, protection)
+        if (result === null) continue
+        protectedItems.push(...result.protected)
+        if (result.removals.length === 0) continue
+        draft.content = `${JSON.stringify(result.document, null, 2)}\n`
+        draft.removals.push(...result.removals)
+      } else {
+        const result = filterJsonRoot(parsed, target.file, protection)
+        if (result === null) continue
+        protectedItems.push(...result.protected)
+        if (result.removals.length === 0) continue
+        draft.content = `${JSON.stringify(result.document, null, 2)}\n`
+        draft.removals.push(...result.removals)
+      }
+      continue
+    }
+
+    if (target.kind === 'toml-tables') {
+      const draft = editableFile(home, target.file, drafts, notes)
+      if (draft === null) continue
+      const result = filterTomlTables(draft.content, target.prefixes, target.file, protection)
+      protectedItems.push(...result.protected)
+      if (result.removals.length === 0) continue
+      draft.content = result.text
+      draft.removals.push(...result.removals)
+      continue
+    }
+
+    if (target.kind === 'dir-entries') {
+      const dir = insideHome(home, target.dir)
+      for (const name of entriesOf(dir, notes)) {
+        const path = join(dir, name)
+        if (target.ignore?.includes(name) === true) continue
+        if (target.descend?.includes(name) === true && lstatSync(path).isDirectory()) continue
+        const relativePath = relativeInside(home, path)
+        const beforeSha256 = fingerprintPath(path)
+        const removal: RemovalItem = { kind: 'path', target: relativePath, beforeSha256 }
+        const reason = protectionFor(removal, protection)
+        if (reason !== null) {
+          protectedItems.push({ removal, reason })
+          continue
+        }
+        if (target.dir === LAUNCH_AGENTS_DIR && !launchAgentInScope(path, name)) continue
+        removals.set(relativePath, {
+          id: `remove-path:${relativePath}`,
+          kind: 'remove-path',
+          path: relativePath,
+          absolutePath: path,
+          beforeSha256,
+          removals: [removal],
+          requiresApproval: target.requiresApproval === true,
+        })
+      }
+      continue
+    }
+
+    if (target.kind === 'marker-files') {
+      const dir = insideHome(home, target.dir)
+      for (const name of entriesOf(dir, notes)) {
+        const path = join(dir, name)
+        if (!lstatSync(path).isFile()) continue
+        if (!hasMarkerLine(readFileSync(path, 'utf8'), target.marker)) continue
+        const relativePath = relativeInside(home, path)
+        const beforeSha256 = fingerprintPath(path)
+        const removal: RemovalItem = { kind: 'path', target: relativePath, beforeSha256 }
+        const reason = protectionFor(removal, protection)
+        if (reason !== null) {
+          protectedItems.push({ removal, reason })
+          continue
+        }
+        removals.set(relativePath, {
+          id: `remove-path:${relativePath}`,
+          kind: 'remove-path',
+          path: relativePath,
+          absolutePath: path,
+          beforeSha256,
+          removals: [removal],
+          requiresApproval: false,
+        })
+      }
+      continue
+    }
+
+    const path = insideHome(home, target.path)
+    if (!pathExists(path)) continue
+    const relativePath = relativeInside(home, path)
+    const beforeSha256 = fingerprintPath(path)
+    const removal: RemovalItem = { kind: 'path', target: relativePath, beforeSha256 }
+    const reason = protectionFor(removal, protection)
+    if (reason !== null) {
+      protectedItems.push({ removal, reason })
+      continue
+    }
+    removals.set(relativePath, {
+      id: `remove-path:${relativePath}`,
+      kind: 'remove-path',
+      path: relativePath,
+      absolutePath: path,
+      beforeSha256,
+      removals: [removal],
+      requiresApproval: false,
+    })
+  }
+
+  const writes: SweepOperation[] = []
+  for (const draft of drafts.values()) {
+    if (draft.content === draft.original) continue
+    writes.push({
+      id: `write-file:${draft.relativePath}`,
+      kind: 'write-file',
+      path: draft.relativePath,
+      absolutePath: draft.path,
+      beforeSha256: fingerprintPath(draft.path),
+      removals: [...draft.removals].sort((a, b) => describeRemoval(a).localeCompare(describeRemoval(b))),
+      content: draft.content,
+      mode: draft.mode,
+      uid: draft.uid,
+      gid: draft.gid,
+      requiresApproval: false,
+    })
+  }
+
+  const operations = [...writes, ...removals.values()].sort((a, b) => a.id.localeCompare(b.id))
+  protectedItems.sort((a, b) => describeRemoval(a.removal).localeCompare(describeRemoval(b.removal)))
+  if (operations.length === 0 && notes.length === 0) {
+    notes.push({
+      level: 'ok',
+      text:
+        protectedItems.length === 0
+          ? 'global agent surfaces are already clean'
+          : 'no unprotected global agent surface candidates found',
+    })
+  }
+  const uniqueNotes = notes.filter(
+    (note, index) => notes.findIndex((other) => other.level === note.level && other.text === note.text) === index,
+  )
+  return { operations, protected: protectedItems, notes: uniqueNotes }
+}
+
+function publicOperation(operation: SweepOperation): ApprovedOperation {
+  return {
+    id: operation.id,
+    kind: operation.kind,
+    path: operation.path,
+    beforeSha256: operation.beforeSha256,
+    removals: operation.removals,
+  }
+}
+
+export function createApprovalPlan(
+  home: string,
+  generatedAt = new Date().toISOString(),
+  protection: ProtectionList = loadProtectionList(),
+): ApprovalPlan {
+  const resolvedHome = resolve(home)
+  return {
+    schema: 1,
+    home: resolvedHome,
+    generatedAt,
+    operations: planGlobalSweep(resolvedHome, protection).operations.map(publicOperation),
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+function decodeRemovalItem(value: unknown): RemovalItem {
+  if (
+    !isRecord(value) ||
+    typeof value.target !== 'string' ||
+    typeof value.beforeSha256 !== 'string' ||
+    !/^sha256:[0-9a-f]{64}$/.test(value.beforeSha256)
+  ) {
+    throw new Error('invalid removal item')
+  }
+  if (value.kind === 'path') {
+    return { kind: 'path', target: value.target, beforeSha256: value.beforeSha256 }
+  }
+  if (value.kind === 'json-entry' && typeof value.selector === 'string') {
+    return {
+      kind: 'json-entry',
+      target: value.target,
+      selector: value.selector,
+      beforeSha256: value.beforeSha256,
+    }
+  }
+  if (value.kind === 'toml-key' && typeof value.key === 'string') {
+    return { kind: 'toml-key', target: value.target, key: value.key, beforeSha256: value.beforeSha256 }
+  }
+  if (value.kind === 'text-block' && typeof value.name === 'string') {
+    return { kind: 'text-block', target: value.target, name: value.name, beforeSha256: value.beforeSha256 }
+  }
+  if (value.kind === 'toml-table' && typeof value.header === 'string') {
+    return {
+      kind: 'toml-table',
+      target: value.target,
+      header: value.header,
+      beforeSha256: value.beforeSha256,
+    }
+  }
+  throw new Error('invalid removal item')
+}
+
+export function decodeApprovalPlan(value: unknown): ApprovalPlan {
+  if (!isRecord(value) || value.schema !== 1 || typeof value.home !== 'string' || !isAbsolute(value.home)) {
+    throw new Error('approval plan must have schema 1 and an absolute home')
+  }
+  if (typeof value.generatedAt !== 'string' || !Array.isArray(value.operations)) {
+    throw new Error('approval plan is missing generatedAt or operations')
+  }
+
+  const operations: ApprovedOperation[] = []
+  const ids = new Set<string>()
+  for (const raw of value.operations) {
+    if (
+      !isRecord(raw) ||
+      (raw.kind !== 'write-file' && raw.kind !== 'remove-path') ||
+      typeof raw.path !== 'string' ||
+      typeof raw.id !== 'string' ||
+      raw.id !== `${raw.kind}:${raw.path}` ||
+      typeof raw.beforeSha256 !== 'string' ||
+      !/^sha256:[0-9a-f]{64}$/.test(raw.beforeSha256) ||
+      !Array.isArray(raw.removals)
+    ) {
+      throw new Error('approval plan contains an invalid operation')
+    }
+    if (ids.has(raw.id)) throw new Error(`approval plan contains duplicate operation: ${raw.id}`)
+    ids.add(raw.id)
+    operations.push({
+      id: raw.id,
+      kind: raw.kind,
+      path: raw.path,
+      beforeSha256: raw.beforeSha256,
+      removals: raw.removals.map(decodeRemovalItem),
+    })
+  }
+
+  return { schema: 1, home: resolve(value.home), generatedAt: value.generatedAt, operations }
+}
+
+function knownOperation(operation: ApprovedOperation): boolean {
+  if (operation.kind === 'write-file') return managedFileTarget(operation.path)
+  return SWEEP_TARGETS.some(
+    (target) =>
+      (target.kind === 'path' && target.path === operation.path) ||
+      (target.kind === 'dir-entries' && dirname(operation.path) === target.dir) ||
+      (target.kind === 'marker-files' && dirname(operation.path) === target.dir),
+  )
+}
+
+function sameRemovals(left: readonly RemovalItem[], right: readonly RemovalItem[]): boolean {
+  return JSON.stringify(left) === JSON.stringify(right)
+}
+
+function atomicWrite(path: string, content: string, mode: number, uid?: number, gid?: number): void {
+  const temporary = join(dirname(path), `.global-surface-sweep.${process.pid}.${Date.now()}.tmp`)
+  try {
+    writeFileSync(temporary, content, { mode })
+    chmodSync(temporary, mode)
+    if (uid !== undefined && gid !== undefined) {
+      const temporaryStat = lstatSync(temporary)
+      if (temporaryStat.uid !== uid || temporaryStat.gid !== gid) chownSync(temporary, uid, gid)
+    }
+    renameSync(temporary, path)
+  } catch (cause) {
+    rmSync(temporary, { force: true })
+    throw cause
+  }
+}
+
+/**
+ * Best-effort unload of a LaunchAgent immediately before its plist is removed
+ * (moved to backup), so an approved removal never leaves an orphaned running
+ * job. `launchctl bootout` on a job that is not currently loaded is expected
+ * and harmless (the overwhelmingly common case for a stale/foreign plist); we
+ * only fail loud when the job is verifiably still loaded afterward, since
+ * deleting the plist out from under a still-running job is the unsafe outcome
+ * this exists to prevent. macOS-only: this directory only exists on Darwin.
+ */
+function bootOutLaunchAgentIfPresent(relativePath: string): void {
+  if (process.platform !== 'darwin') return
+  if (dirname(relativePath) !== LAUNCH_AGENTS_DIR) return
+  const base = relativePath.slice(relativePath.lastIndexOf('/') + 1)
+  const label = base.endsWith('.plist') ? base.slice(0, -'.plist'.length) : base
+  const uid = typeof process.getuid === 'function' ? process.getuid() : 0
+  spawnSync('launchctl', ['bootout', `gui/${uid}/${label}`], { encoding: 'utf8' })
+  const stillLoaded = spawnSync('launchctl', ['list', label], { encoding: 'utf8' })
+  if (stillLoaded.status === 0) {
+    throw new Error(`LaunchAgent ${label} is still loaded after bootout; refusing to remove ${relativePath}`)
+  }
+}
+
+function backupPath(backupRoot: string, relativePath: string): string {
+  const path = resolve(backupRoot, relativePath)
+  relativeInside(backupRoot, path)
+  return path
+}
+
+/**
+ * CLI-only reporting (Tarun, 2026-09-28): print the exact original -> backup
+ * mapping for every file this run copied (write-file) or moved (remove-path)
+ * into the backup root `applyApprovedSweep` already creates before touching
+ * anything -- see the `selected` loop there, which backs up every operation
+ * it applies and fails loudly (throws, and rolls back what it already
+ * applied) if a backup step itself fails. When the run applied nothing
+ * (report-only audit, or an already-clean apply/enforce), there is no
+ * backup root at all, so this prints the explicit "no backups" line instead
+ * of an empty block.
+ */
+function printBackupsThisRun(home: string, applied: readonly ApprovedOperation[], backupRoot: string | null): void {
+  if (backupRoot === null || applied.length === 0) {
+    console.log('global-surface-sweep: no files changed; no backups')
+    return
+  }
+  console.log('global-surface-sweep: backups this run:')
+  for (const operation of applied) {
+    console.log(`  ${resolve(home, operation.path)} -> ${backupPath(backupRoot, operation.path)}`)
+  }
+}
+
+function reviewSurface(relativePath: string): { readonly surface: string; readonly path: string } {
+  for (const [prefix, surface] of [
+    ['.agents/', 'agents'],
+    ['.claude/', 'claude'],
+    ['.codex/', 'codex'],
+    ['.cursor/', 'cursor'],
+    ['.config/opencode/', 'opencode'],
+    ['.kimi-code/', 'kimi'],
+    ['Library/LaunchAgents/', 'launchagents'],
+    ['.local/bin/', 'localbin'],
+  ] as const) {
+    if (relativePath.startsWith(prefix)) return { surface, path: relativePath.slice(prefix.length) }
+  }
+  if (relativePath === '.claude.json') return { surface: 'claude', path: 'home-.claude.json' }
+  if (SHELL_RC_FILES.includes(relativePath)) return { surface: 'shell', path: relativePath }
+  throw new Error(`cannot classify review-copy surface: ${relativePath}`)
+}
+
+function reviewPath(destination: string, relativePath: string, category: string, suffix = ''): string {
+  const classified = reviewSurface(relativePath)
+  const path = resolve(destination, classified.surface, category, `${classified.path}${suffix}`)
+  relativeInside(destination, path)
+  return path
+}
+
+function writeReviewFile(path: string, content: string, mode = 0o600): void {
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 })
+  writeFileSync(path, content, { mode })
+  chmodSync(path, mode)
+}
+
+function jsonPointerValue(document: unknown, selector: string): unknown {
+  let current = document
+  for (const encoded of selector.split('/').slice(1)) {
+    const key = encoded.replaceAll('~1', '/').replaceAll('~0', '~')
+    if (current === null || typeof current !== 'object' || !(key in current)) {
+      throw new Error(`JSON selector no longer exists: ${selector}`)
+    }
+    current = (current as Record<string, unknown>)[key]
+  }
+  return current
+}
+
+export function copyReviewBundle(
+  homeInput: string,
+  destinationInput: string,
+  protection: ProtectionList = loadProtectionList(),
+  generatedAt = new Date().toISOString(),
+): ReviewCopyResult {
+  if (!isAbsolute(homeInput) || !isAbsolute(destinationInput)) {
+    throw new Error('--home and --destination must be absolute')
+  }
+  const home = resolve(homeInput)
+  const destination = resolve(destinationInput)
+  if (destination === home) throw new Error('review-copy destination cannot be the home directory')
+  if (pathExists(destination)) {
+    if (!lstatSync(destination).isDirectory()) throw new Error('review-copy destination is not a directory')
+    if (readdirSync(destination).length > 0) throw new Error('review-copy destination must be empty')
+  } else mkdirSync(destination, { recursive: true, mode: 0o700 })
+  chmodSync(destination, 0o700)
+
+  const plan = planGlobalSweep(home, protection)
+  for (const operation of plan.operations) {
+    if (destination === operation.absolutePath || destination.startsWith(`${operation.absolutePath}${sep}`)) {
+      throw new Error(`review-copy destination is inside candidate: ${operation.path}`)
+    }
+    if (!pathExists(operation.absolutePath) || fingerprintPath(operation.absolutePath) !== operation.beforeSha256) {
+      throw new Error(`candidate drifted before review copy: ${operation.path}`)
+    }
+  }
+
+  const copies: {
+    readonly source: string
+    readonly destination: string
+    readonly kind: 'path' | 'config-original' | 'proposed-after' | 'removed-fragment'
+  }[] = []
+  let copiedPaths = 0
+  let copiedConfigFiles = 0
+
+  for (const operation of plan.operations) {
+    if (operation.kind === 'remove-path') {
+      const copy = reviewPath(destination, operation.path, 'paths')
+      mkdirSync(dirname(copy), { recursive: true, mode: 0o700 })
+      cpSync(operation.absolutePath, copy, {
+        recursive: true,
+        dereference: false,
+        errorOnExist: true,
+        preserveTimestamps: true,
+        verbatimSymlinks: true,
+      })
+      if (fingerprintPath(copy) !== operation.beforeSha256) {
+        throw new Error(`review copy fingerprint mismatch: ${operation.path}`)
+      }
+      copies.push({ source: operation.path, destination: relativeInside(destination, copy), kind: 'path' })
+      copiedPaths += 1
+      continue
+    }
+
+    const original = reviewPath(destination, operation.path, 'config-originals')
+    mkdirSync(dirname(original), { recursive: true, mode: 0o700 })
+    copyFileSync(operation.absolutePath, original)
+    chmodSync(original, operation.mode)
+    if (fingerprintPath(original) !== operation.beforeSha256) {
+      throw new Error(`review config copy fingerprint mismatch: ${operation.path}`)
+    }
+    copies.push({
+      source: operation.path,
+      destination: relativeInside(destination, original),
+      kind: 'config-original',
+    })
+
+    const proposed = reviewPath(destination, operation.path, 'proposed-after')
+    writeReviewFile(proposed, operation.content)
+    copies.push({
+      source: operation.path,
+      destination: relativeInside(destination, proposed),
+      kind: 'proposed-after',
+    })
+
+    const jsonRemovals = operation.removals.filter(
+      (removal): removal is Extract<RemovalItem, { readonly kind: 'json-entry' }> =>
+        removal.kind === 'json-entry',
+    )
+    if (jsonRemovals.length > 0) {
+      const document = JSON.parse(readFileSync(operation.absolutePath, 'utf8'))
+      const entries = jsonRemovals.map((removal) => {
+        const value = jsonPointerValue(document, removal.selector)
+        if (fingerprintJsonValue(value) !== removal.beforeSha256) {
+          throw new Error(`JSON removal drifted during review copy: ${operation.path}#${removal.selector}`)
+        }
+        return { selector: removal.selector, beforeSha256: removal.beforeSha256, value }
+      })
+      const removed = reviewPath(destination, operation.path, 'removed-fragments', '.removed.json')
+      writeReviewFile(removed, `${JSON.stringify({ source: operation.path, entries }, null, 2)}\n`)
+      copies.push({
+        source: operation.path,
+        destination: relativeInside(destination, removed),
+        kind: 'removed-fragment',
+      })
+    }
+
+    const tomlRemovals = operation.removals.filter(
+      (removal): removal is Extract<RemovalItem, { readonly kind: 'toml-table' | 'toml-key' }> =>
+        removal.kind === 'toml-table' || removal.kind === 'toml-key',
+    )
+    if (tomlRemovals.length > 0) {
+      const blocks = splitTomlBlocks(readFileSync(operation.absolutePath, 'utf8'), preservedRegionFor(operation.path))
+      const rootBlock = blocks[0]?.header === null && blocks[0]?.preserved === false ? blocks[0] : null
+      const rootKeyTexts = rootBlock === null
+        ? []
+        : tomlRootKeys(rootBlock.lines).map((rootKey) => ({
+            key: rootKey.key,
+            text: rootBlock.lines.slice(rootKey.start, rootKey.end + 1).join('\n'),
+          }))
+      const removedBlocks = tomlRemovals.map((removal) => {
+        if (removal.kind === 'toml-key') {
+          const match = rootKeyTexts.find(
+            (candidate) => candidate.key === removal.key && fingerprintBytes(candidate.text) === removal.beforeSha256,
+          )
+          if (match === undefined) {
+            throw new Error(`TOML key removal drifted during review copy: ${operation.path} ${removal.key}`)
+          }
+          return match.text
+        }
+        const block = blocks.find(
+          (candidate) =>
+            candidate.header === removal.header &&
+            fingerprintBytes(candidate.lines.join('\n')) === removal.beforeSha256,
+        )
+        if (block === undefined) {
+          throw new Error(`TOML removal drifted during review copy: ${operation.path} ${removal.header}`)
+        }
+        return block.lines.join('\n')
+      })
+      const removed = reviewPath(destination, operation.path, 'removed-fragments', '.removed.toml')
+      writeReviewFile(removed, removedBlocks.join('\n'))
+      copies.push({
+        source: operation.path,
+        destination: relativeInside(destination, removed),
+        kind: 'removed-fragment',
+      })
+    }
+    const blockRemovals = operation.removals.filter(
+      (removal): removal is Extract<RemovalItem, { readonly kind: 'text-block' }> => removal.kind === 'text-block',
+    )
+    if (blockRemovals.length > 0) {
+      const blocks = findTextBlocks(readFileSync(operation.absolutePath, 'utf8'))
+      const removedTexts = blockRemovals.map((removal) => {
+        const block = blocks.find(
+          (candidate) => candidate.name === removal.name && fingerprintBytes(candidate.text) === removal.beforeSha256,
+        )
+        if (block === undefined) {
+          throw new Error(`text block removal drifted during review copy: ${operation.path} ${removal.name}`)
+        }
+        return block.text
+      })
+      const removed = reviewPath(destination, operation.path, 'removed-fragments', '.removed.txt')
+      writeReviewFile(removed, `${removedTexts.join('\n\n')}\n`)
+      copies.push({
+        source: operation.path,
+        destination: relativeInside(destination, removed),
+        kind: 'removed-fragment',
+      })
+    }
+    copiedConfigFiles += 1
+  }
+
+  for (const operation of plan.operations) {
+    if (!pathExists(operation.absolutePath) || fingerprintPath(operation.absolutePath) !== operation.beforeSha256) {
+      throw new Error(`candidate drifted during review copy: ${operation.path}`)
+    }
+  }
+
+  const candidateItems = plan.operations.reduce((count, operation) => count + operation.removals.length, 0)
+  writeReviewFile(
+    join(destination, 'manifest.json'),
+    `${JSON.stringify(
+      {
+        schema: 1,
+        generatedAt,
+        sourceHome: home,
+        notice: 'Review copy only. No live agent surface was changed or deleted.',
+        candidateOperations: plan.operations.length,
+        candidateItems,
+        protectedItems: plan.protected.length,
+        copies,
+        operations: plan.operations.map(publicOperation),
+        protected: plan.protected,
+      },
+      null,
+      2,
+    )}\n`,
+  )
+  writeReviewFile(
+    join(destination, 'README.md'),
+    [
+      '# Global surface sweep review copy',
+      '',
+      'This directory is a non-destructive snapshot. No live agent surface was changed or deleted.',
+      '',
+      `- Candidate operations: ${plan.operations.length}`,
+      `- Candidate items: ${candidateItems}`,
+      `- Protected items not copied as candidates: ${plan.protected.length}`,
+      '',
+      'Each surface contains `paths/` for exact filesystem candidates, `config-originals/` for the',
+      'full source configuration, `proposed-after/` for the planned result, and `removed-fragments/`',
+      'for the exact JSON values or TOML blocks selected for removal. `manifest.json` records hashes',
+      'and source-to-copy mappings. Some removed fragments may contain credentials; keep this directory private.',
+      '',
+    ].join('\n'),
+  )
+
+  return {
+    destination,
+    copiedPaths,
+    copiedConfigFiles,
+    candidateItems,
+    protectedItems: plan.protected.length,
+  }
+}
+
+export function applyApprovedSweep(
+  homeInput: string,
+  approvalInput: ApprovalPlan,
+  stateDirInput: string,
+  now = new Date().toISOString(),
+  protection: ProtectionList = loadProtectionList(),
+): ApplyResult {
+  if (!isAbsolute(homeInput) || !isAbsolute(stateDirInput)) {
+    throw new Error('--home and --state-dir must be absolute')
+  }
+  const home = resolve(homeInput)
+  const stateDir = resolve(stateDirInput)
+  const approval = decodeApprovalPlan(approvalInput)
+  if (approval.home !== home) throw new Error(`approval plan is for ${approval.home}, not ${home}`)
+
+  const currentPlan = planGlobalSweep(home, protection)
+  const currentById = new Map(currentPlan.operations.map((operation) => [operation.id, operation]))
+  const approvedIds = new Set(approval.operations.map((operation) => operation.id))
+  const selected: SweepOperation[] = []
+  const alreadyClean: string[] = []
+
+  for (const approved of approval.operations) {
+    if (!knownOperation(approved)) throw new Error(`approval operation is outside managed surfaces: ${approved.id}`)
+    const current = currentById.get(approved.id)
+    if (current === undefined) {
+      const path = insideHome(home, approved.path)
+      if (approved.kind === 'remove-path' && pathExists(path)) {
+        throw new Error(`approved removal is no longer a direct managed entry: ${approved.path}`)
+      }
+      const unreadable = currentPlan.notes.some(
+        (note) => note.level === 'warn' && note.text.startsWith(`${path} `) && note.text.includes('left untouched'),
+      )
+      if (unreadable) throw new Error(`approved target can no longer be read safely: ${approved.path}`)
+      alreadyClean.push(approved.id)
+      continue
+    }
+    if (
+      current.kind !== approved.kind ||
+      current.path !== approved.path ||
+      current.beforeSha256 !== approved.beforeSha256 ||
+      !sameRemovals(current.removals, approved.removals)
+    ) {
+      throw new Error(`approved target drifted after review: ${approved.path}`)
+    }
+    selected.push(current)
+  }
+
+  const unapproved = currentPlan.operations
+    .filter((operation) => !approvedIds.has(operation.id))
+    .map(publicOperation)
+  if (selected.length === 0) return { applied: [], alreadyClean, unapproved, backupRoot: null }
+
+  const stamp = now.replaceAll(/[^0-9A-Za-z_-]/g, '-')
+  const backupParent = join(stateDir, 'global-surface-sweep', 'backups')
+  for (const operation of selected) {
+    const target = resolve(operation.absolutePath)
+    if (stateDir === target || stateDir.startsWith(`${target}${sep}`)) {
+      throw new Error(`state directory cannot be inside a removal target: ${operation.path}`)
+    }
+  }
+  mkdirSync(backupParent, { recursive: true, mode: 0o700 })
+  const backupRoot = mkdtempSync(join(backupParent, `${stamp}-`))
+  chmodSync(backupRoot, 0o700)
+
+  const applied: { readonly operation: SweepOperation; readonly backup: string }[] = []
+  try {
+    for (const operation of selected) {
+      if (!pathExists(operation.absolutePath) || fingerprintPath(operation.absolutePath) !== operation.beforeSha256) {
+        throw new Error(`approved target drifted immediately before apply: ${operation.path}`)
+      }
+      const backup = backupPath(backupRoot, operation.path)
+      mkdirSync(dirname(backup), { recursive: true, mode: 0o700 })
+      if (operation.kind === 'write-file') {
+        copyFileSync(operation.absolutePath, backup)
+        chmodSync(backup, operation.mode)
+        const backupStat = lstatSync(backup)
+        if (backupStat.uid !== operation.uid || backupStat.gid !== operation.gid) {
+          chownSync(backup, operation.uid, operation.gid)
+        }
+        atomicWrite(operation.absolutePath, operation.content, operation.mode, operation.uid, operation.gid)
+      } else {
+        bootOutLaunchAgentIfPresent(operation.path)
+        renameSync(operation.absolutePath, backup)
+      }
+      applied.push({ operation, backup })
+    }
+
+    atomicWrite(
+      join(backupRoot, 'applied-plan.json'),
+      `${JSON.stringify(
+        {
+          schema: 1,
+          appliedAt: now,
+          home,
+          operations: applied.map(({ operation }) => publicOperation(operation)),
+        },
+        null,
+        2,
+      )}\n`,
+      0o600,
+    )
+  } catch (cause) {
+    for (const { operation, backup } of [...applied].reverse()) {
+      if (operation.kind === 'write-file') {
+        atomicWrite(
+          operation.absolutePath,
+          readFileSync(backup, 'utf8'),
+          operation.mode,
+          operation.uid,
+          operation.gid,
+        )
+      } else {
+        mkdirSync(dirname(operation.absolutePath), { recursive: true })
+        renameSync(backup, operation.absolutePath)
+      }
+    }
+    throw cause
+  }
+
+  return {
+    applied: applied.map(({ operation }) => publicOperation(operation)),
+    alreadyClean,
+    unapproved,
+    backupRoot,
+  }
+}
+
+export function enforceGlobalSweep(
+  homeInput: string,
+  stateDirInput: string,
+  now = new Date().toISOString(),
+  protection: ProtectionList = loadProtectionList(),
+): EnforceResult {
+  if (!isAbsolute(homeInput) || !isAbsolute(stateDirInput)) {
+    throw new Error('--home and --state-dir must be absolute')
+  }
+  const home = resolve(homeInput)
+  const plan = planGlobalSweep(home, protection)
+  const result = applyApprovedSweep(
+    home,
+    {
+      schema: 1,
+      home,
+      generatedAt: now,
+      operations: plan.operations.filter((operation) => !operation.requiresApproval).map(publicOperation),
+    },
+    resolve(stateDirInput),
+    now,
+    protection,
+  )
+  const pendingApproval = result.unapproved.filter((operation) => operationRequiresApproval(operation.path))
+  return { ...result, protectedItems: plan.protected.length, pendingApproval }
+}
+
+export function describeRemoval(removal: RemovalItem): string {
+  if (removal.kind === 'json-entry') {
+    return `JSON ${removal.target}#${removal.selector} (${removal.beforeSha256})`
+  }
+  if (removal.kind === 'toml-table') {
+    return `TOML ${removal.target} ${removal.header} (${removal.beforeSha256})`
+  }
+  if (removal.kind === 'toml-key') {
+    return `TOML-KEY ${removal.target} ${removal.key} (${removal.beforeSha256})`
+  }
+  if (removal.kind === 'text-block') {
+    return `BLOCK ${removal.target} «${removal.name}» (${removal.beforeSha256})`
+  }
+  return `PATH ${removal.target} (${removal.beforeSha256})`
+}
+
+function usage(): never {
+  throw new Error(
+    'usage: global-surface-sweep --home ABSOLUTE_PATH --mode audit|plan|copy-review|apply|enforce ' +
+      '[--protection FILE --destination ABSOLUTE_PATH --approval PLAN.json --state-dir ABSOLUTE_PATH]',
+  )
+}
+
+export function main(argv: readonly string[]): void {
+  let home = ''
+  let mode = 'audit'
+  let approvalPath = ''
+  let stateDir = '/var/lib/adl'
+  let protectionPath = DEFAULT_PROTECTION_PATH
+  let destination = ''
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const argument = argv[index]
+    if (argument === '--home') home = argv[++index] ?? ''
+    else if (argument === '--mode') mode = argv[++index] ?? ''
+    else if (argument === '--approval') approvalPath = argv[++index] ?? ''
+    else if (argument === '--state-dir') stateDir = argv[++index] ?? ''
+    else if (argument === '--protection') protectionPath = argv[++index] ?? ''
+    else if (argument === '--destination') destination = argv[++index] ?? ''
+    else usage()
+  }
+  if (home.length === 0 || !['audit', 'plan', 'copy-review', 'apply', 'enforce'].includes(mode)) usage()
+  const protection = loadProtectionList(protectionPath)
+
+  if (mode === 'plan') {
+    console.log(JSON.stringify(createApprovalPlan(home, new Date().toISOString(), protection), null, 2))
+    return
+  }
+
+  if (mode === 'copy-review') {
+    if (destination.length === 0) throw new Error('copy-review mode requires --destination')
+    const result = copyReviewBundle(home, destination, protection)
+    console.log(`review copy: ${result.destination}`)
+    console.log(`copied path candidates: ${result.copiedPaths}`)
+    console.log(`copied configuration originals: ${result.copiedConfigFiles}`)
+    console.log(`candidate items: ${result.candidateItems}`)
+    console.log(`protected items not copied as candidates: ${result.protectedItems}`)
+    console.log('global-surface-sweep: review copy complete; no live files changed')
+    return
+  }
+
+  if (mode === 'enforce') {
+    const result = enforceGlobalSweep(home, stateDir, new Date().toISOString(), protection)
+    for (const operation of result.applied) {
+      console.log(`applied: ${operation.id}`)
+      for (const removal of operation.removals) console.log(`  removed: ${describeRemoval(removal)}`)
+    }
+    for (const operation of result.pendingApproval) {
+      console.log(`pending approval: ${operation.id}`)
+      for (const removal of operation.removals) console.log(`  retained until approved: ${describeRemoval(removal)}`)
+    }
+    printBackupsThisRun(home, result.applied, result.backupRoot)
+    console.log(
+      `global-surface-sweep: enforced ${result.applied.length} operation(s); ` +
+        `${result.protectedItems} exact protected item(s) retained; ` +
+        `${result.pendingApproval.length} operation(s) pending approval`,
+    )
+    if (result.pendingApproval.length > 0) {
+      console.error(
+        `global-surface-sweep: WARNING ${result.pendingApproval.length} removal operation(s) pending explicit approval ` +
+          '(generate with --mode plan, review, then --mode apply --approval PLAN.json)',
+      )
+    }
+    return
+  }
+
+  const plan = planGlobalSweep(home, protection)
+  if (mode === 'audit') {
+    for (const note of plan.notes) console.log(`${note.level}: ${note.text}`)
+    for (const item of plan.protected) {
+      console.log(`protected: ${describeRemoval(item.removal)} — ${item.reason}`)
+    }
+    for (const operation of plan.operations) {
+      const suffix = operation.requiresApproval ? ' [requires explicit approval]' : ''
+      for (const removal of operation.removals) console.log(`remove: ${describeRemoval(removal)}${suffix}`)
+    }
+    // Audit is report-only: it never writes or moves a file, so there is
+    // never a backup root to point at (Tarun, 2026-09-28).
+    printBackupsThisRun(home, [], null)
+    console.log(
+      `global-surface-sweep: ${plan.operations.length} candidate(s), ` +
+        `${plan.protected.length} exact protected item(s); no changes applied`,
+    )
+    return
+  }
+
+  if (approvalPath.length === 0) {
+    throw new Error('apply mode requires --approval; discovery alone never authorizes deletion')
+  }
+  const approval = decodeApprovalPlan(JSON.parse(readFileSync(approvalPath, 'utf8')))
+  const result = applyApprovedSweep(home, approval, stateDir, new Date().toISOString(), protection)
+  for (const operation of result.applied) {
+    console.log(`applied: ${operation.id}`)
+    for (const removal of operation.removals) console.log(`  removed: ${describeRemoval(removal)}`)
+  }
+  for (const id of result.alreadyClean) console.log(`already clean: ${id}`)
+  for (const operation of result.unapproved) {
+    console.log(`left unapproved: ${operation.id}`)
+    for (const removal of operation.removals) console.log(`  retained: ${describeRemoval(removal)}`)
+  }
+  printBackupsThisRun(home, result.applied, result.backupRoot)
+  console.log('global-surface-sweep: apply complete')
+}
+
+if (import.meta.main) {
+  try {
+    main(process.argv.slice(2))
+  } catch (cause) {
+    console.error(`global-surface-sweep: ${messageOf(cause)}`)
+    process.exitCode = 1
+  }
+}