opensocrates 1.2.0 → 1.3.0

package/installer/opensocrates.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-import { spawnSync } from "node:child_process";
+import { spawn, spawnSync } from "node:child_process";
 import { createHash, randomInt, randomUUID } from "node:crypto";
 import {
   constants as fsConstants,
@@ -13,6 +13,7 @@ import {
 import {
   access,
   chmod,
+  chown,
   cp,
   lstat,
   mkdir,
@@ -20,8 +21,10 @@ import {
   open,
   readFile,
   readdir,
+  realpath,
   rename,
   rm,
+  rmdir,
   stat,
   writeFile,
 } from "node:fs/promises";
@@ -31,7 +34,7 @@ import { Readable } from "node:stream";
 import { pipeline } from "node:stream/promises";
 import { fileURLToPath } from "node:url";
 
-export const PRODUCT_VERSION = "1.2.0";
+export const PRODUCT_VERSION = "1.3.0";
 export const REPOSITORY = "ParkerHwang/OpenSocrates";
 export const MARKETPLACE_NAME = "opensocrates";
 export const PLUGIN_NAME = "opensocrates";
@@ -149,6 +152,1057 @@ const AUTO_UPDATE_MAX_INTERVAL_HOURS = 24 * 7;
 const AUTO_UPDATE_DEFAULT_INTERVAL_HOURS = 24;
 const AUTO_UPDATE_POLL_SECONDS = 60 * 60;
 const LOCK_STALE_MILLISECONDS = 2 * 60 * 60 * 1000;
+export const PURGE_RESULT_SCHEMA = "opensocrates.purge-result/1.0.0";
+export const CODEX_TRUST_EVENTS = Object.freeze([
+  "pre_tool_use",
+  "post_tool_use",
+  "pre_compact",
+  "session_start",
+  "session_end",
+  "user_prompt_submit",
+  "stop",
+]);
+const CODEX_TRUST_KEY_PREFIX = `${PLUGIN_ID}:hooks/hooks.json:`;
+const MAX_CODEX_CONFIG_BYTES = 16 * 1024 * 1024;
+const CODEX_APP_SERVER_ARGS = Object.freeze(["app-server", "--stdio"]);
+const CODEX_APP_SERVER_TIMEOUT_MILLISECONDS = 15_000;
+const CODEX_APP_SERVER_TERMINATION_MILLISECONDS = 1_000;
+const MAX_CODEX_APP_SERVER_LINE_BYTES = 256 * 1024;
+const MAX_CODEX_APP_SERVER_OUTPUT_BYTES = 1024 * 1024;
+const MAX_CODEX_APP_SERVER_NOTIFICATIONS = 128;
+
+// Keep host security state separate from installer-owned payload cleanup so an
+// explicit trust reset can fail without weakening purge path-ownership checks.
+export function purgeExtensionResult(host, resetTrust = false) {
+  return host === "codex"
+    ? {
+        component: "host-security-trust",
+        status: resetTrust ? "pending" : "preserved",
+        nextAction: resetTrust ? null : "rerun-purge-with-reset-trust",
+      }
+    : {
+        component: "host-security-trust",
+        status: "not-applicable",
+        nextAction: null,
+      };
+}
+
+export function createPurgeResult(hosts, { resetTrust = false } = {}) {
+  return {
+    schema: PURGE_RESULT_SCHEMA,
+    status: "pending",
+    hosts: [...hosts].sort().map((host) => ({
+      host,
+      status: "pending",
+      registration: "not-checked",
+      registrationDetail: null,
+      components: [],
+      extension: purgeExtensionResult(host, resetTrust),
+      errors: [],
+    })),
+    finalization: {
+      status: "pending",
+      components: [],
+      errors: [],
+    },
+  };
+}
+
+function trustResetFailure(message) {
+  fail(`Codex OpenSocrates hook trust was not reset: ${message}`);
+}
+
+function decodeTomlBasicString(source, start) {
+  let value = "";
+  let index = start + 1;
+  while (index < source.length) {
+    const character = source[index];
+    if (character === '"') {
+      return { value, next: index + 1, kind: "basic", raw: source.slice(start, index + 1) };
+    }
+    if (character === "\\") {
+      const escaped = source[index + 1];
+      const simple = new Map([
+        ['"', '"'],
+        ["\\", "\\"],
+        ["b", "\b"],
+        ["t", "\t"],
+        ["n", "\n"],
+        ["f", "\f"],
+        ["r", "\r"],
+      ]);
+      if (simple.has(escaped)) {
+        value += simple.get(escaped);
+        index += 2;
+        continue;
+      }
+      const digits = escaped === "u" ? 4 : escaped === "U" ? 8 : 0;
+      if (digits > 0) {
+        const encoded = source.slice(index + 2, index + 2 + digits);
+        if (!new RegExp(`^[0-9A-Fa-f]{${digits}}$`, "u").test(encoded)) return null;
+        const codePoint = Number.parseInt(encoded, 16);
+        if (codePoint > 0x10ffff || (codePoint >= 0xd800 && codePoint <= 0xdfff)) return null;
+        value += String.fromCodePoint(codePoint);
+        index += 2 + digits;
+        continue;
+      }
+      return null;
+    }
+    if (character.codePointAt(0) < 0x20 || character.codePointAt(0) === 0x7f) return null;
+    value += character;
+    index += 1;
+  }
+  return null;
+}
+
+function decodeTomlLiteralString(source, start) {
+  const end = source.indexOf("'", start + 1);
+  if (end < 0) return null;
+  const value = source.slice(start + 1, end);
+  if ([...value].some((character) => character.codePointAt(0) < 0x20 || character.codePointAt(0) === 0x7f)) {
+    return null;
+  }
+  return { value, next: end + 1, kind: "literal", raw: source.slice(start, end + 1) };
+}
+
+function parseTomlDottedKey(source) {
+  const segments = [];
+  let index = 0;
+  const skipWhitespace = () => {
+    while (source[index] === " " || source[index] === "\t") index += 1;
+  };
+  skipWhitespace();
+  while (index < source.length) {
+    let segment;
+    if (source[index] === '"') {
+      segment = decodeTomlBasicString(source, index);
+    } else if (source[index] === "'") {
+      segment = decodeTomlLiteralString(source, index);
+    } else {
+      const match = source.slice(index).match(/^[A-Za-z0-9_-]+/u);
+      if (!match) return null;
+      segment = {
+        value: match[0],
+        next: index + match[0].length,
+        kind: "bare",
+        raw: match[0],
+      };
+    }
+    if (segment === null) return null;
+    segments.push(segment);
+    index = segment.next;
+    skipWhitespace();
+    if (index === source.length) return segments;
+    if (source[index] !== ".") return null;
+    index += 1;
+    skipWhitespace();
+    if (index === source.length) return null;
+  }
+  return null;
+}
+
+function scanTomlLine(line, carriedContext) {
+  let state = carriedContext.stringState;
+  let arrayDepth = carriedContext.arrayDepth;
+  let inlineTableDepth = carriedContext.inlineTableDepth;
+  let commentIndex = -1;
+  for (let index = 0; index < line.length; index += 1) {
+    if (state === "multiline-basic") {
+      if (line[index] === "\\") {
+        index += 1;
+      } else if (line.startsWith('"""', index)) {
+        state = null;
+        index += 2;
+      }
+      continue;
+    }
+    if (state === "multiline-literal") {
+      if (line.startsWith("'''", index)) {
+        state = null;
+        index += 2;
+      }
+      continue;
+    }
+    if (state === "basic") {
+      if (line[index] === "\\") index += 1;
+      else if (line[index] === '"') state = null;
+      continue;
+    }
+    if (state === "literal") {
+      if (line[index] === "'") state = null;
+      continue;
+    }
+    if (line[index] === "#") {
+      commentIndex = index;
+      break;
+    }
+    if (line.startsWith('"""', index)) {
+      state = "multiline-basic";
+      index += 2;
+    } else if (line.startsWith("'''", index)) {
+      state = "multiline-literal";
+      index += 2;
+    } else if (line[index] === '"') {
+      state = "basic";
+    } else if (line[index] === "'") {
+      state = "literal";
+    } else if (line[index] === "[") {
+      arrayDepth += 1;
+    } else if (line[index] === "]") {
+      arrayDepth -= 1;
+      if (arrayDepth < 0) return { invalid: true, commentIndex, context: carriedContext };
+    } else if (line[index] === "{") {
+      inlineTableDepth += 1;
+    } else if (line[index] === "}") {
+      inlineTableDepth -= 1;
+      if (inlineTableDepth < 0) return { invalid: true, commentIndex, context: carriedContext };
+    }
+  }
+  if (state === "basic" || state === "literal") {
+    return { invalid: true, commentIndex, context: carriedContext };
+  }
+  return {
+    invalid: false,
+    commentIndex,
+    context: { stringState: state, arrayDepth, inlineTableDepth },
+  };
+}
+
+function tomlLines(source) {
+  const lines = [];
+  let start = 0;
+  while (start < source.length) {
+    const newline = source.indexOf("\n", start);
+    const end = newline < 0 ? source.length : newline + 1;
+    const contentEnd = newline < 0 ? source.length : newline > start && source[newline - 1] === "\r" ? newline - 1 : newline;
+    lines.push({ start, end, contentEnd, body: source.slice(start, contentEnd) });
+    start = end;
+  }
+  return lines;
+}
+
+function parseTomlTableHeader(code) {
+  const leading = code.match(/^[\t ]*/u)?.[0].length ?? 0;
+  const trimmedEnd = code.trimEnd().length;
+  const candidate = code.slice(leading, trimmedEnd);
+  const array = candidate.startsWith("[[");
+  if (!candidate.startsWith("[") || (array ? !candidate.endsWith("]]") : !candidate.endsWith("]"))) {
+    return null;
+  }
+  const openWidth = array ? 2 : 1;
+  const closeWidth = array ? 2 : 1;
+  const keySource = candidate.slice(openWidth, candidate.length - closeWidth);
+  const segments = parseTomlDottedKey(keySource);
+  if (segments === null) return null;
+  return {
+    array,
+    raw: candidate,
+    segments,
+    syntaxStart: leading,
+    syntaxEnd: leading + candidate.length,
+  };
+}
+
+function matchingTrustKey(segments) {
+  if (
+    segments.length < 3 ||
+    segments[0].value !== "hooks" ||
+    segments[1].value !== "state" ||
+    !segments[2].value.startsWith(CODEX_TRUST_KEY_PREFIX)
+  ) {
+    return null;
+  }
+  return segments[2].value;
+}
+
+function isCanonicalTrustHeader(header, key) {
+  return !header.array && header.raw === `[hooks.state.${JSON.stringify(key)}]`;
+}
+
+function assignmentKeySegments(code) {
+  let state = null;
+  for (let index = 0; index < code.length; index += 1) {
+    if (state === "basic") {
+      if (code[index] === "\\") index += 1;
+      else if (code[index] === '"') state = null;
+      continue;
+    }
+    if (state === "literal") {
+      if (code[index] === "'") state = null;
+      continue;
+    }
+    if (code[index] === '"') state = "basic";
+    else if (code[index] === "'") state = "literal";
+    else if (code[index] === "=") return parseTomlDottedKey(code.slice(0, index));
+  }
+  return null;
+}
+
+function lineContainsTrustNamespaceString(code) {
+  for (let index = 0; index < code.length; index += 1) {
+    let decoded = null;
+    if (code[index] === '"') decoded = decodeTomlBasicString(code, index);
+    else if (code[index] === "'") decoded = decodeTomlLiteralString(code, index);
+    if (decoded === null) continue;
+    if (decoded.value.startsWith(CODEX_TRUST_KEY_PREFIX)) return true;
+    index = decoded.next - 1;
+  }
+  return false;
+}
+
+function pathContainsTrustNamespace(segments) {
+  return matchingTrustKey(segments) !== null;
+}
+
+function trustEventFromKey(key) {
+  const suffix = key.slice(CODEX_TRUST_KEY_PREFIX.length);
+  const match = suffix.match(/^([a-z_]+):(\d+):(\d+)$/u);
+  if (!match || !CODEX_TRUST_EVENTS.includes(match[1]) || match[2] !== "0" || match[3] !== "0") {
+    trustResetFailure("the matching trust namespace has a noncanonical event or index");
+  }
+  return match[1];
+}
+
+function addRemovalSpan(spans, line, start, end) {
+  if (start >= end) trustResetFailure("the matching trust section has an unsupported shape");
+  spans.push({ start: line.start + start, end: line.start + end });
+}
+
+/**
+ * Remove only the syntax bytes owned by canonical OpenSocrates hook trust
+ * sections. Comments, whitespace, newline style, unrelated keys, and the
+ * parent hooks.state table are retained byte-for-byte.
+ */
+export function stripCodexOpenSocratesTrustSections(contents) {
+  const original = Buffer.isBuffer(contents) ? contents : Buffer.from(contents);
+  const utf8Bom = original.subarray(0, 3).equals(Buffer.from([0xef, 0xbb, 0xbf]));
+  const encodedSource = utf8Bom ? original.subarray(3) : original;
+  let source;
+  try {
+    source = new TextDecoder("utf-8", { fatal: true }).decode(encodedSource);
+  } catch {
+    trustResetFailure("the configuration is not valid UTF-8");
+  }
+  const spans = [];
+  const found = new Map();
+  let currentTarget = null;
+  let currentTableSegments = [];
+  let context = { stringState: null, arrayDepth: 0, inlineTableDepth: 0 };
+  for (const line of tomlLines(source)) {
+    const startContext = { ...context };
+    const scanned = scanTomlLine(line.body, context);
+    if (scanned.invalid) trustResetFailure("the configuration has an unsupported string shape");
+    context = scanned.context;
+    const code = scanned.commentIndex < 0 ? line.body : line.body.slice(0, scanned.commentIndex);
+    const firstNonWhitespace = code.search(/[^\t ]/u);
+    let header = null;
+    if (
+      startContext.stringState === null &&
+      startContext.arrayDepth === 0 &&
+      startContext.inlineTableDepth === 0 &&
+      firstNonWhitespace >= 0 &&
+      code[firstNonWhitespace] === "["
+    ) {
+      header = parseTomlTableHeader(code);
+      if (header === null) trustResetFailure("the configuration has an unsupported table header");
+    }
+    if (header !== null) {
+      if (currentTarget !== null && !currentTarget.hashSeen) {
+        trustResetFailure("a matching trust section is missing its canonical trusted_hash key");
+      }
+      currentTarget = null;
+      currentTableSegments = header.segments;
+      const key = matchingTrustKey(header.segments);
+      if (key !== null) {
+        if (!isCanonicalTrustHeader(header, key)) {
+          trustResetFailure("the matching trust namespace uses a noncanonical table shape");
+        }
+        const event = trustEventFromKey(key);
+        if (found.has(event)) trustResetFailure("a matching trust event appears more than once");
+        currentTarget = { event, hashSeen: false };
+        found.set(event, currentTarget);
+        addRemovalSpan(spans, line, header.syntaxStart, header.syntaxEnd);
+      }
+      continue;
+    }
+    if (currentTarget === null) {
+      if (code.trim().length === 0 || startContext.stringState !== null) continue;
+      const assignment = assignmentKeySegments(code);
+      const semanticPath = assignment === null ? [] : [...currentTableSegments, ...assignment];
+      if (
+        pathContainsTrustNamespace(semanticPath) ||
+        ((semanticPath[0]?.value === "hooks" ||
+          (currentTableSegments[0]?.value === "hooks" && currentTableSegments[1]?.value === "state")) &&
+          lineContainsTrustNamespaceString(code))
+      ) {
+        trustResetFailure("the matching trust namespace uses a noncanonical assignment shape");
+      }
+      continue;
+    }
+    if (code.trim().length === 0) continue;
+    if (
+      startContext.stringState !== null ||
+      context.stringState !== null ||
+      startContext.arrayDepth !== 0 ||
+      startContext.inlineTableDepth !== 0 ||
+      context.arrayDepth !== 0 ||
+      context.inlineTableDepth !== 0
+    ) {
+      trustResetFailure("a matching trust section contains a multiline value");
+    }
+    const assignment = code.match(/^(\s*)trusted_hash\s*=\s*"(?:[^"\\\r\n]|\\.)*"(\s*)$/u);
+    if (assignment === null || currentTarget.hashSeen) {
+      trustResetFailure("a matching trust section contains an unexpected or duplicate key");
+    }
+    currentTarget.hashSeen = true;
+    const syntaxStart = assignment[1].length;
+    const syntaxEnd = code.length - assignment[2].length;
+    addRemovalSpan(spans, line, syntaxStart, syntaxEnd);
+  }
+  if (context.stringState !== null || context.arrayDepth !== 0 || context.inlineTableDepth !== 0) {
+    trustResetFailure("the configuration has an unterminated multiline value");
+  }
+  if (currentTarget !== null && !currentTarget.hashSeen) {
+    trustResetFailure("a matching trust section is missing its canonical trusted_hash key");
+  }
+  spans.sort((left, right) => left.start - right.start);
+  let cursor = 0;
+  let updated = "";
+  for (const span of spans) {
+    if (span.start < cursor) trustResetFailure("matching trust syntax overlaps unexpectedly");
+    updated += source.slice(cursor, span.start);
+    cursor = span.end;
+  }
+  updated += source.slice(cursor);
+  const updatedBytes = Buffer.from(updated, "utf8");
+  return {
+    contents: utf8Bom ? Buffer.concat([original.subarray(0, 3), updatedBytes]) : updatedBytes,
+    removedEvents: CODEX_TRUST_EVENTS.filter((event) => found.has(event)),
+  };
+}
+
+function currentUid() {
+  if (typeof process.getuid !== "function") {
+    trustResetFailure("file ownership cannot be verified on this platform");
+  }
+  return process.getuid();
+}
+
+function assertOwnedDirectory(info) {
+  if (!info.isDirectory() || info.isSymbolicLink() || info.uid !== currentUid() || (info.mode & 0o022) !== 0) {
+    trustResetFailure("the Codex configuration directory is not a safe owner-controlled directory");
+  }
+}
+
+function assertOwnedConfigFile(info) {
+  if (!info.isFile() || info.isSymbolicLink() || info.uid !== currentUid() || info.nlink !== 1) {
+    trustResetFailure("the Codex configuration is not a safe owner-controlled regular file");
+  }
+  if (info.size > MAX_CODEX_CONFIG_BYTES) {
+    trustResetFailure("the Codex configuration is too large for a bounded trust reset");
+  }
+}
+
+function sameSnapshot(left, right) {
+  return (
+    left.dev === right.dev &&
+    left.ino === right.ino &&
+    left.size === right.size &&
+    left.mtimeNs === right.mtimeNs &&
+    left.ctimeNs === right.ctimeNs &&
+    left.mode === right.mode &&
+    left.uid === right.uid &&
+    left.gid === right.gid &&
+    left.nlink === right.nlink
+  );
+}
+
+async function readConfigSnapshot(target) {
+  const noFollow = fsConstants.O_NOFOLLOW ?? 0;
+  let handle;
+  let operationFailed = false;
+  try {
+    handle = await open(target, fsConstants.O_RDONLY | noFollow);
+    const before = await handle.stat({ bigint: true });
+    if (
+      !before.isFile() ||
+      before.isSymbolicLink() ||
+      before.uid !== BigInt(currentUid()) ||
+      before.nlink !== 1n
+    ) {
+      trustResetFailure("the Codex configuration changed to an unsafe file");
+    }
+    if (before.size > BigInt(MAX_CODEX_CONFIG_BYTES)) {
+      trustResetFailure("the Codex configuration is too large for a bounded trust reset");
+    }
+    const contents = await handle.readFile();
+    const after = await handle.stat({ bigint: true });
+    if (!sameSnapshot(before, after) || BigInt(contents.length) !== after.size) {
+      trustResetFailure("the Codex configuration changed while it was being inspected");
+    }
+    return { info: after, contents };
+  } catch (error) {
+    operationFailed = true;
+    if (error instanceof InstallerError) throw error;
+    trustResetFailure("the Codex configuration could not be inspected safely");
+  } finally {
+    try {
+      await handle?.close();
+    } catch {
+      if (!operationFailed) {
+        trustResetFailure("the Codex configuration handle could not be closed safely");
+      }
+    }
+  }
+}
+
+async function writeSyncedOwnerOnlyFile(target, contents) {
+  let handle;
+  let operationFailed = false;
+  try {
+    handle = await open(target, "wx", 0o600);
+    await handle.writeFile(contents);
+    await handle.chmod(0o600);
+    await handle.sync();
+  } catch (error) {
+    operationFailed = true;
+    if (error instanceof InstallerError) throw error;
+    trustResetFailure("an owner-only Codex transaction file could not be written safely");
+  } finally {
+    try {
+      await handle?.close();
+    } catch {
+      if (!operationFailed) {
+        trustResetFailure("an owner-only Codex transaction file could not be closed safely");
+      }
+    }
+  }
+}
+
+async function fsyncFile(target) {
+  let handle;
+  let operationFailed = false;
+  try {
+    handle = await open(target, "r");
+    await handle.sync();
+  } catch (error) {
+    operationFailed = true;
+    if (error instanceof InstallerError) throw error;
+    trustResetFailure("the Codex configuration could not be synchronized safely");
+  } finally {
+    try {
+      await handle?.close();
+    } catch {
+      if (!operationFailed) {
+        trustResetFailure("the Codex configuration handle could not be closed safely");
+      }
+    }
+  }
+}
+
+async function fsyncDirectory(target) {
+  let handle;
+  let operationFailed = false;
+  try {
+    handle = await open(target, "r");
+    await handle.sync();
+  } catch (error) {
+    operationFailed = true;
+    if (error instanceof InstallerError) throw error;
+    trustResetFailure("the Codex configuration directory could not be synchronized safely");
+  } finally {
+    try {
+      await handle?.close();
+    } catch {
+      if (!operationFailed) {
+        trustResetFailure("the Codex configuration directory handle could not be closed safely");
+      }
+    }
+  }
+}
+
+function exactCodexInitializeResponse(message, requestId, codexHome) {
+  if (message === null || typeof message !== "object" || Array.isArray(message)) return false;
+  const responseKeys = Object.keys(message).sort();
+  if (responseKeys.length !== 2 || responseKeys[0] !== "id" || responseKeys[1] !== "result") {
+    return false;
+  }
+  if (message.id !== requestId) return false;
+  const result = message.result;
+  if (result === null || typeof result !== "object" || Array.isArray(result)) return false;
+  const resultKeys = Object.keys(result).sort();
+  if (
+    resultKeys.length !== 4 ||
+    resultKeys[0] !== "codexHome" ||
+    resultKeys[1] !== "platformFamily" ||
+    resultKeys[2] !== "platformOs" ||
+    resultKeys[3] !== "userAgent"
+  ) {
+    return false;
+  }
+  return (
+    result.codexHome === codexHome &&
+    typeof result.platformFamily === "string" &&
+    result.platformFamily.length > 0 &&
+    typeof result.platformOs === "string" &&
+    result.platformOs.length > 0 &&
+    typeof result.userAgent === "string" &&
+    result.userAgent.length > 0
+  );
+}
+
+function exactCodexAppServerNotification(message) {
+  if (message === null || typeof message !== "object" || Array.isArray(message)) return false;
+  const keys = Object.keys(message).sort();
+  const withoutTimestamp = keys.length === 2 && keys[0] === "method" && keys[1] === "params";
+  const withTimestamp =
+    keys.length === 3 &&
+    keys[0] === "emittedAtMs" &&
+    keys[1] === "method" &&
+    keys[2] === "params";
+  if (!withoutTimestamp && !withTimestamp) return false;
+  if (typeof message.method !== "string" || message.method.length === 0) return false;
+  if (message.params === null || typeof message.params !== "object" || Array.isArray(message.params)) {
+    return false;
+  }
+  return !withTimestamp || (typeof message.emittedAtMs === "number" && Number.isFinite(message.emittedAtMs));
+}
+
+function codexAppServerValidationError() {
+  return new InstallerError(
+    "Codex OpenSocrates hook trust was not reset: the installed Codex app server did not accept the isolated configuration",
+  );
+}
+
+function isolatedCodexValidationEnvironment(codexHome) {
+  const environment = {
+    PATH: process.env.PATH ?? "",
+    HOME: codexHome,
+    CODEX_HOME: codexHome,
+    XDG_CACHE_HOME: join(codexHome, "xdg-cache"),
+    XDG_CONFIG_HOME: join(codexHome, "xdg-config"),
+    XDG_DATA_HOME: join(codexHome, "xdg-data"),
+    XDG_STATE_HOME: join(codexHome, "xdg-state"),
+    TMPDIR: join(codexHome, "tmp"),
+    NO_COLOR: "1",
+  };
+  if (process.platform === "win32") {
+    for (const key of ["ComSpec", "PATHEXT", "SystemRoot", "WINDIR"]) {
+      if (typeof process.env[key] === "string") environment[key] = process.env[key];
+    }
+  }
+  return environment;
+}
+
+async function runCodexAppServerConfigCheck(
+  codexBin,
+  codexHome,
+  {
+    spawnAppServer = spawn,
+    timeoutMilliseconds = CODEX_APP_SERVER_TIMEOUT_MILLISECONDS,
+    terminationMilliseconds = CODEX_APP_SERVER_TERMINATION_MILLISECONDS,
+  } = {},
+) {
+  const requestId = 1;
+  const request = Buffer.from(
+    `${JSON.stringify({
+      id: requestId,
+      method: "initialize",
+      params: {
+        clientInfo: {
+          name: "opensocrates_installer",
+          title: "OpenSocrates Installer",
+          version: PRODUCT_VERSION,
+        },
+        capabilities: { experimentalApi: false },
+      },
+    })}\n`,
+    "utf8",
+  );
+  let child;
+  try {
+    child = spawnAppServer(codexBin, CODEX_APP_SERVER_ARGS, {
+      cwd: codexHome,
+      env: isolatedCodexValidationEnvironment(codexHome),
+      stdio: ["pipe", "pipe", "pipe"],
+      windowsHide: true,
+    });
+  } catch {
+    throw codexAppServerValidationError();
+  }
+
+  await new Promise((resolvePromise, rejectPromise) => {
+    const timeoutDelay =
+      Number.isFinite(timeoutMilliseconds) && timeoutMilliseconds > 0
+        ? timeoutMilliseconds
+        : CODEX_APP_SERVER_TIMEOUT_MILLISECONDS;
+    const terminationDelay =
+      Number.isFinite(terminationMilliseconds) && terminationMilliseconds > 0
+        ? terminationMilliseconds
+        : CODEX_APP_SERVER_TERMINATION_MILLISECONDS;
+    let closed = false;
+    let failed = false;
+    let settled = false;
+    let responseCount = 0;
+    let notificationCount = 0;
+    let responseAccepted = false;
+    let requestWriteCompleted = false;
+    let outputBytes = 0;
+    let lineBuffer = Buffer.alloc(0);
+    let inputEndRequested = false;
+    let terminationTimer;
+    let forcedFinishTimer;
+
+    const clearTimers = () => {
+      clearTimeout(deadlineTimer);
+      if (terminationTimer !== undefined) clearTimeout(terminationTimer);
+      if (forcedFinishTimer !== undefined) clearTimeout(forcedFinishTimer);
+    };
+    const finish = (accepted) => {
+      if (settled) return;
+      settled = true;
+      clearTimers();
+      if (accepted) resolvePromise();
+      else rejectPromise(codexAppServerValidationError());
+    };
+    const endInput = () => {
+      if (inputEndRequested) return true;
+      inputEndRequested = true;
+      try {
+        child.stdin.end();
+        return true;
+      } catch {
+        return false;
+      }
+    };
+    const terminate = () => {
+      if (failed || settled) return;
+      failed = true;
+      // The stream may already be closed; process termination below remains bounded.
+      endInput();
+      if (closed) {
+        finish(false);
+        return;
+      }
+      try {
+        child.kill("SIGTERM");
+      } catch {
+        // A failed signal is followed by the bounded SIGKILL/final failure timers.
+      }
+      terminationTimer = setTimeout(() => {
+        if (closed || settled) return;
+        try {
+          child.kill("SIGKILL");
+        } catch {
+          // The final timer still prevents an unbounded validator wait.
+        }
+        forcedFinishTimer = setTimeout(() => finish(false), terminationDelay);
+      }, terminationDelay);
+    };
+    const consumeLine = (line) => {
+      if (failed || settled) return;
+      if (line.length > MAX_CODEX_APP_SERVER_LINE_BYTES || line.length === 0) {
+        terminate();
+        return;
+      }
+      const normalized = line.at(-1) === 0x0d ? line.subarray(0, -1) : line;
+      let message;
+      try {
+        message = JSON.parse(normalized.toString("utf8"));
+      } catch {
+        terminate();
+        return;
+      }
+      if (exactCodexInitializeResponse(message, requestId, codexHome)) {
+        responseCount += 1;
+        if (responseCount !== 1) {
+          terminate();
+          return;
+        }
+        responseAccepted = true;
+        if (!endInput()) terminate();
+        return;
+      }
+      if (!exactCodexAppServerNotification(message)) {
+        terminate();
+        return;
+      }
+      notificationCount += 1;
+      if (notificationCount > MAX_CODEX_APP_SERVER_NOTIFICATIONS) terminate();
+    };
+    const deadlineTimer = setTimeout(terminate, timeoutDelay);
+
+    child.stdout.on("data", (chunk) => {
+      if (failed || settled) return;
+      const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+      outputBytes += bytes.length;
+      if (outputBytes > MAX_CODEX_APP_SERVER_OUTPUT_BYTES) {
+        terminate();
+        return;
+      }
+      lineBuffer = Buffer.concat([lineBuffer, bytes]);
+      for (;;) {
+        const newline = lineBuffer.indexOf(0x0a);
+        if (newline < 0) break;
+        const line = lineBuffer.subarray(0, newline);
+        lineBuffer = lineBuffer.subarray(newline + 1);
+        consumeLine(line);
+        if (failed || settled) return;
+      }
+      if (lineBuffer.length > MAX_CODEX_APP_SERVER_LINE_BYTES) terminate();
+    });
+    child.stderr.on("data", (chunk) => {
+      if (failed || settled) return;
+      const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+      outputBytes += bytes.length;
+      if (outputBytes > MAX_CODEX_APP_SERVER_OUTPUT_BYTES) terminate();
+    });
+    child.once("error", terminate);
+    child.stdin.once("error", terminate);
+    child.once("close", (code, signal) => {
+      closed = true;
+      finish(
+        !failed &&
+          code === 0 &&
+          signal === null &&
+          responseCount === 1 &&
+          responseAccepted &&
+          requestWriteCompleted &&
+          lineBuffer.length === 0,
+      );
+    });
+
+    try {
+      const accepted = child.stdin.write(request, (error) => {
+        if (error !== undefined && error !== null) {
+          terminate();
+          return;
+        }
+        requestWriteCompleted = true;
+      });
+      if (!accepted) {
+        // This is the only bounded write. A false return means it is queued;
+        // the response/deadline path bounds a child that never drains it.
+        child.stdin.once("drain", () => {});
+      }
+    } catch {
+      terminate();
+    }
+  });
+}
+
+async function validateCodexConfigBytes(
+  codexBin,
+  contents,
+  {
+    removeValidationHome = rm,
+    spawnAppServer = spawn,
+    validationTimeoutMilliseconds = CODEX_APP_SERVER_TIMEOUT_MILLISECONDS,
+    validationTerminationMilliseconds = CODEX_APP_SERVER_TERMINATION_MILLISECONDS,
+  } = {},
+) {
+  let validationHome;
+  let operationFailed = false;
+  try {
+    validationHome = await mkdtemp(join(tmpdir(), "opensocrates-codex-config-check-"));
+    await chmod(validationHome, 0o700);
+    // macOS commonly exposes the temporary directory through /var while
+    // Codex reports its canonical /private/var spelling. Use one canonical
+    // identity for the environment, cwd, and initialize-response comparison.
+    validationHome = await realpath(validationHome);
+    for (const directory of ["tmp", "xdg-cache", "xdg-config", "xdg-data", "xdg-state"]) {
+      await mkdir(join(validationHome, directory), { mode: 0o700 });
+    }
+    const target = join(validationHome, "config.toml");
+    await writeSyncedOwnerOnlyFile(target, contents);
+    await runCodexAppServerConfigCheck(codexBin, validationHome, {
+      spawnAppServer,
+      timeoutMilliseconds: validationTimeoutMilliseconds,
+      terminationMilliseconds: validationTerminationMilliseconds,
+    });
+  } catch (error) {
+    operationFailed = true;
+    if (error instanceof InstallerError) throw error;
+    trustResetFailure("the Codex configuration could not be validated in isolation");
+  } finally {
+    if (validationHome !== undefined) {
+      try {
+        await removeValidationHome(validationHome, { recursive: true, force: true });
+      } catch {
+        if (!operationFailed) {
+          trustResetFailure("the isolated Codex validation environment could not be removed safely");
+        }
+      }
+    }
+  }
+}
+
+async function restoreTrustConfig({
+  rollback,
+  target,
+  parent,
+  original,
+  originalMode,
+  originalUid,
+  originalGid,
+}) {
+  try {
+    if (!(await entryExists(rollback))) trustResetFailure("the rollback copy is unavailable");
+    await rename(rollback, target);
+    await chown(target, originalUid, originalGid);
+    await chmod(target, originalMode);
+    await fsyncFile(target);
+    await fsyncDirectory(parent);
+    const restored = await readConfigSnapshot(target);
+    if (
+      !restored.contents.equals(original) ||
+      Number(restored.info.mode & 0o7777n) !== originalMode ||
+      restored.info.uid !== BigInt(originalUid) ||
+      restored.info.gid !== BigInt(originalGid)
+    ) {
+      trustResetFailure("the original configuration was not restored");
+    }
+  } catch (error) {
+    if (error instanceof InstallerError) throw error;
+    trustResetFailure("the original configuration could not be restored automatically");
+  }
+}
+
+/**
+ * Reset only OpenSocrates Codex hook trust. Optional hooks are dependency
+ * injection seams for isolated failure/race tests; production callers pass no
+ * hooks and always use the installed Codex CLI for validation.
+ */
+export async function resetCodexOpenSocratesHookTrust({
+  codexHome = process.env.CODEX_HOME || join(homedir(), ".codex"),
+  codexBin = codexBinary(),
+  hooks = {},
+} = {}) {
+  const lexicalHome = resolve(codexHome);
+  if (!(await entryExists(lexicalHome))) return { status: "absent", removedEvents: [] };
+  const lexicalInfo = await lstat(lexicalHome);
+  assertOwnedDirectory(lexicalInfo);
+  let parent;
+  try {
+    parent = await realpath(lexicalHome);
+  } catch {
+    trustResetFailure("the Codex configuration directory could not be canonicalized");
+  }
+  const parentInfo = await lstat(parent);
+  assertOwnedDirectory(parentInfo);
+  const target = join(parent, "config.toml");
+  if (!(await entryExists(target))) return { status: "absent", removedEvents: [] };
+  const targetInfo = await lstat(target);
+  assertOwnedConfigFile(targetInfo);
+  const snapshot = await readConfigSnapshot(target);
+  const originalMode = Number(snapshot.info.mode & 0o7777n);
+  const originalUid = Number(snapshot.info.uid);
+  const originalGid = Number(snapshot.info.gid);
+  const validationOptions = {
+    removeValidationHome: hooks.removeValidationHome,
+    spawnAppServer: hooks.spawnAppServer,
+    validationTimeoutMilliseconds: hooks.validationTimeoutMilliseconds,
+    validationTerminationMilliseconds: hooks.validationTerminationMilliseconds,
+  };
+  await validateCodexConfigBytes(codexBin, snapshot.contents, validationOptions);
+  const stripped = stripCodexOpenSocratesTrustSections(snapshot.contents);
+  if (stripped.removedEvents.length === 0) {
+    const current = await readConfigSnapshot(target);
+    if (!sameSnapshot(snapshot.info, current.info) || !current.contents.equals(snapshot.contents)) {
+      trustResetFailure("the Codex configuration changed during isolated validation");
+    }
+    return { status: "absent", removedEvents: [] };
+  }
+  await validateCodexConfigBytes(codexBin, stripped.contents, validationOptions);
+
+  const token = randomUUID();
+  const temporary = join(parent, `.config.toml.opensocrates-trust-reset-${token}.tmp`);
+  const rollback = join(parent, `.config.toml.opensocrates-trust-reset-${token}.rollback`);
+  let replaced = false;
+  let preserveRollback = false;
+  let transactionFailed = false;
+  let transactionCommitted = false;
+  let cleanupRequired = true;
+  try {
+    await hooks.beforeWrite?.({ target });
+    await writeSyncedOwnerOnlyFile(temporary, stripped.contents);
+    await writeSyncedOwnerOnlyFile(rollback, snapshot.contents);
+    await fsyncDirectory(parent);
+    await hooks.beforeRename?.({ target, temporary, rollback });
+    const current = await readConfigSnapshot(target);
+    if (!sameSnapshot(snapshot.info, current.info) || !current.contents.equals(snapshot.contents)) {
+      trustResetFailure("the Codex configuration changed before the atomic update");
+    }
+    await rename(temporary, target);
+    replaced = true;
+    await chown(target, originalUid, originalGid);
+    await chmod(target, originalMode);
+    await fsyncFile(target);
+    await fsyncDirectory(parent);
+    await hooks.afterRename?.({ target, rollback });
+    const committed = await readConfigSnapshot(target);
+    if (
+      !committed.contents.equals(stripped.contents) ||
+      Number(committed.info.mode & 0o7777n) !== originalMode ||
+      committed.info.uid !== BigInt(originalUid) ||
+      committed.info.gid !== BigInt(originalGid)
+    ) {
+      trustResetFailure("the committed Codex configuration did not match the validated candidate");
+    }
+    await validateCodexConfigBytes(codexBin, committed.contents, validationOptions);
+    await (hooks.removeRollback ?? rm)(rollback);
+    // The candidate and parent rename are already fsynced and post-validated.
+    // Keep rollback unlink as the final fallible commit step; another directory
+    // fsync would only create a failure point after the recovery source is gone.
+    transactionCommitted = true;
+    cleanupRequired = false;
+    return { status: "reset", removedEvents: stripped.removedEvents };
+  } catch (error) {
+    transactionFailed = true;
+    if (replaced) {
+      let canRollback = false;
+      try {
+        const current = await readConfigSnapshot(target);
+        canRollback = current.contents.equals(stripped.contents);
+      } catch {
+        canRollback = false;
+      }
+      if (!canRollback) {
+        preserveRollback = true;
+        trustResetFailure(
+          "the Codex configuration changed after replacement; automatic rollback was withheld and the owner-only recovery copy was preserved",
+        );
+      }
+      await restoreTrustConfig({
+        rollback,
+        target,
+        parent,
+        original: snapshot.contents,
+        originalMode,
+        originalUid,
+        originalGid,
+      });
+    }
+    if (error instanceof InstallerError) throw error;
+    trustResetFailure("the atomic configuration update failed; the original configuration was preserved");
+  } finally {
+    let cleanupFailed = false;
+    if (cleanupRequired) {
+      for (const residue of [temporary, rollback]) {
+        try {
+          if (residue === rollback && preserveRollback) continue;
+          await hooks.beforeResidueCleanup?.({ residue });
+          if (await entryExists(residue)) await rm(residue);
+        } catch {
+          cleanupFailed = true;
+        }
+      }
+    }
+    if (cleanupFailed && !transactionFailed && !transactionCommitted) {
+      trustResetFailure("owner-only Codex transaction residue could not be removed safely");
+    }
+  }
+}
 
 export class InstallerError extends Error {}
 
@@ -169,6 +1223,27 @@ async function exists(target) {
   }
 }
 
+// Destructive paths must distinguish a missing entry from a dangling symlink.
+// access() follows links, so it is intentionally insufficient at deletion
+// boundaries where an unresolvable link must be refused rather than reported
+// as already absent.
+async function entryExists(target) {
+  try {
+    await lstat(target);
+    return true;
+  } catch (error) {
+    if (error?.code === "ENOENT") return false;
+    throw error;
+  }
+}
+
+async function requireRegularFileEntry(target, label) {
+  const info = await lstat(target);
+  if (!info.isFile() || info.isSymbolicLink()) {
+    fail(`refusing an unsafe ${label}: ${target}`);
+  }
+}
+
 export function statePaths() {
   const stateDirectory = resolve(process.env.OPENSOCRATES_STATE_DIR || join(homedir(), ".opensocrates"));
   const launchAgentsDirectory = resolve(
@@ -260,9 +1335,10 @@ function normalizeDesiredState(value) {
 
 export async function readDesiredState() {
   const { desiredState } = statePaths();
-  if (!(await exists(desiredState))) {
+  if (!(await entryExists(desiredState))) {
     return defaultDesiredState();
   }
+  await requireRegularFileEntry(desiredState, "OpenSocrates desired-state file");
   let value;
   try {
     value = JSON.parse(await readFile(desiredState, "utf8"));
@@ -428,6 +1504,34 @@ function jsonEqual(left, right) {
   );
 }
 
+function jsonDeepEqual(left, right) {
+  if (left === right) return true;
+  if (Array.isArray(left) || Array.isArray(right)) {
+    return (
+      Array.isArray(left) &&
+      Array.isArray(right) &&
+      left.length === right.length &&
+      left.every((item, index) => jsonDeepEqual(item, right[index]))
+    );
+  }
+  if (
+    left === null ||
+    right === null ||
+    typeof left !== "object" ||
+    typeof right !== "object"
+  ) {
+    return false;
+  }
+  const leftKeys = Object.keys(left).sort();
+  const rightKeys = Object.keys(right).sort();
+  return (
+    leftKeys.length === rightKeys.length &&
+    leftKeys.every(
+      (key, index) => key === rightKeys[index] && jsonDeepEqual(left[key], right[key]),
+    )
+  );
+}
+
 function markerFor(host) {
   if (host === "cursor") return CURSOR_MARKER;
   if (host === "antigravity") return ANTIGRAVITY_MARKER;
@@ -509,6 +1613,8 @@ export function parseCli(argv) {
     intervalHours: AUTO_UPDATE_DEFAULT_INTERVAL_HOURS,
     allowMajor: false,
     force: false,
+    purge: false,
+    resetTrust: false,
   };
   const seenOptions = new Set();
   while (args.length > 0) {
@@ -536,6 +1642,16 @@ export function parseCli(argv) {
       options.force = true;
       continue;
     }
+    if (flag === "--purge") {
+      seenOptions.add("purge");
+      options.purge = true;
+      continue;
+    }
+    if (flag === "--reset-trust") {
+      seenOptions.add("reset-trust");
+      options.resetTrust = true;
+      continue;
+    }
     if (flag === "--channel") {
       seenOptions.add("channel");
       const channel = args.shift();
@@ -623,6 +1739,15 @@ export function parseCli(argv) {
   if (seenOptions.has("force") && !autoUpdateRun) {
     fail("--force is only valid with auto-update run");
   }
+  if (seenOptions.has("purge") && options.action !== "remove") {
+    fail("--purge is only valid with remove");
+  }
+  if (seenOptions.has("reset-trust") && (options.action !== "remove" || !options.purge)) {
+    fail("--reset-trust requires remove --purge");
+  }
+  if (seenOptions.has("reset-trust") && !new Set([ALL_HOST, "codex"]).has(options.host)) {
+    fail("--reset-trust is only valid with --host codex or --host all");
+  }
   if (
     seenOptions.has("host") &&
     options.action === "auto-update" &&
@@ -640,11 +1765,11 @@ function showHelp() {
   console.log(`OpenSocrates ${PRODUCT_VERSION}
 
 Usage:
-  opensocrates install [--host all|antigravity|claude|codex|cursor|grok|opencode] [--asset ZIP --checksum SHA256]
+  opensocrates install [--host all|antigravity|claude|codex|cursor|grok|opencode] [--asset ZIP --checksum FILE]
   opensocrates status [--host all|antigravity|claude|codex|cursor|grok|opencode]
-  opensocrates update [--host all|antigravity|claude|codex|cursor|grok|opencode] [--asset ZIP --checksum SHA256]
-  opensocrates remove [--host all|antigravity|claude|codex|cursor|grok|opencode]
-  opensocrates verify [--host all|antigravity|claude|codex|cursor|grok|opencode] [--asset ZIP --checksum SHA256]
+  opensocrates update [--host all|antigravity|claude|codex|cursor|grok|opencode] [--asset ZIP --checksum FILE]
+  opensocrates remove [--host all|antigravity|claude|codex|cursor|grok|opencode] [--purge [--reset-trust]]
+  opensocrates verify [--host all|antigravity|claude|codex|cursor|grok|opencode] [--asset ZIP --checksum FILE]
   opensocrates auto-update enable [--host all|antigravity|claude|codex|cursor|grok|opencode]
       [--channel stable|next] [--interval-hours ${AUTO_UPDATE_DEFAULT_INTERVAL_HOURS}]
       [--allow-major]
@@ -656,6 +1781,15 @@ package and checksum from GitHub Releases. The default lifecycle host is codex.
 With --host all, supplied host-qualified asset/checksum pairs define the exact
 transaction set and are never mixed with downloads for other hosts. Without
 qualified assets, every ready host participates. Automatic updates are opt-in.
+
+Ordinary remove unregisters the selected host and removes installer-managed
+files, but may leave host-owned caches, installer state, and Codex hook trust.
+Add --purge for an explicit payload/data cleanup attempt. Purge preserves Codex
+hook trust unless --reset-trust is also supplied for codex or all; that explicit
+option removes only the seven canonical OpenSocrates trust entries. Registration,
+payload cleanup, host security trust, and user history are reported separately.
+User history is always preserved. Any unverified, unsafe, or in-use component is
+reported as pending.
 `);
 }
 
@@ -715,6 +1849,28 @@ function managedPaths(host) {
   };
 }
 
+export function purgePathsFor(host) {
+  if (!SUPPORTED_HOSTS.includes(host)) {
+    fail(`unsupported host ${JSON.stringify(host)}`);
+  }
+  const paths = managedPaths(host);
+  const cacheRoot = ["claude", "codex"].includes(host)
+    ? join(paths.hostHome, "plugins", "cache", MARKETPLACE_NAME, PLUGIN_NAME)
+    : null;
+  return {
+    ...paths,
+    cacheRoot,
+    cacheMarketplaceRoot: cacheRoot === null ? null : dirname(cacheRoot),
+    pluginData:
+      host === "claude"
+        ? [
+            join(paths.hostHome, "plugins", "data", "opensocrates-inline"),
+            join(paths.hostHome, "plugins", "data", "opensocrates-opensocrates"),
+          ]
+        : [],
+  };
+}
+
 // Directory that holds staging trees and rollback backups for one host.
 //
 // Grok scans every directory below ~/.grok/plugins, including dot-prefixed
@@ -1194,7 +2350,9 @@ async function requireOwnedRoot(root, host) {
   if (!info.isDirectory() || info.isSymbolicLink()) {
     fail(`managed marketplace path is not an owned directory: ${root}`);
   }
-  const marker = await readJsonObject(join(root, MARKER_NAME));
+  const markerPath = join(root, MARKER_NAME);
+  await requireRegularFileEntry(markerPath, `${host} ownership marker`);
+  const marker = await readJsonObject(markerPath);
   if (!markerMatches(marker, host)) {
     fail(`managed marketplace path has no valid ownership marker: ${root}`);
   }
@@ -1437,46 +2595,514 @@ async function verifyExtractedPackage(pluginRoot, host) {
         `got ${String(manifest.name)} ${String(manifest.version)}`,
     );
   }
-  const release = await readJsonObject(join(pluginRoot, "release-manifest.json"));
+  const release = await readJsonObject(join(pluginRoot, "release-manifest.json"));
+  if (
+    release.product_version !== PRODUCT_VERSION ||
+    release.host !== host ||
+    release.schema !== "opensocrates.plugin-release-manifest/1.0.0"
+  ) {
+    fail("package release manifest does not match this installer");
+  }
+  if (HOST_LAYOUTS[host].requiresRuntime) {
+    const runtime = join(pluginRoot, "runtime", "darwin-arm64", "opensocrates-runtime", "opensocrates-runtime");
+    const runtimeInfo = await stat(runtime);
+    if (!runtimeInfo.isFile() || (runtimeInfo.mode & 0o111) === 0) {
+      fail("package is missing the executable darwin-arm64 runtime");
+    }
+  } else if (
+    release.launchers?.length !== 0 ||
+    release.runtime_targets?.length !== 0 ||
+    (await exists(join(pluginRoot, "runtime"))) ||
+    (await exists(join(pluginRoot, "hooks"))) ||
+    (await exists(join(pluginRoot, "bin"))) ||
+    ((host === "cursor" || host === "grok") && (await exists(join(pluginRoot, "mcp.json")))) ||
+    (host === "grok" &&
+      ((await exists(join(pluginRoot, "commands"))) ||
+        (await exists(join(pluginRoot, "agents"))) ||
+        (await exists(join(pluginRoot, ".mcp.json")))))
+  ) {
+    fail(`${host} package contains an unexpected native runtime or launcher surface`);
+  }
+  if (host === "opencode") {
+    if (
+      manifest.minimum_opencode_version !== "1.18.18" ||
+      manifest.stable_plugin_hook !== "chat.message" ||
+      manifest.beta_v2_api !== false ||
+      !(await exists(join(pluginRoot, "plugins", "opensocrates.js"))) ||
+      !(await exists(join(pluginRoot, "skills", "opensocrates", "SKILL.md")))
+    ) {
+      fail("OpenCode package does not match the verified stable bridge contract");
+    }
+  }
+  return verifyPackageChecksums(pluginRoot);
+}
+
+async function requireSafePathBelow(root, target, label, { allowRoot = false } = {}) {
+  const resolvedRoot = resolve(root);
+  const resolvedTarget = resolve(target);
+  if (await entryExists(resolvedRoot)) {
+    const rootInfo = await lstat(resolvedRoot);
+    if (!rootInfo.isDirectory() || rootInfo.isSymbolicLink()) {
+      fail(`refusing an unsafe ${label} root: ${root}`);
+    }
+  }
+  const suffix = relative(resolvedRoot, resolvedTarget);
+  if (
+    (!allowRoot && !suffix) ||
+    suffix === ".." ||
+    suffix.startsWith(`..${sep}`) ||
+    resolve(resolvedRoot, suffix) !== resolvedTarget
+  ) {
+    fail(`refusing an unsafe ${label} path: ${target}`);
+  }
+  let current = resolvedRoot;
+  for (const component of suffix.split(sep)) {
+    current = join(current, component);
+    if (!(await entryExists(current))) continue;
+    const info = await lstat(current);
+    if (info.isSymbolicLink()) {
+      fail(`refusing a symbolic-link ${label} path: ${current}`);
+    }
+  }
+  if (await entryExists(resolvedTarget)) {
+    let canonical;
+    let canonicalRoot = resolvedRoot;
+    try {
+      canonical = realpathSync(resolvedTarget);
+      if (await entryExists(resolvedRoot)) canonicalRoot = realpathSync(resolvedRoot);
+    } catch (error) {
+      fail(`cannot canonicalize ${label}: ${error.message}`);
+    }
+    if (canonical !== resolve(canonicalRoot, suffix)) {
+      fail(`refusing a non-canonical ${label} path: ${target}`);
+    }
+  }
+}
+
+async function packageIdentityForPurge(pluginRoot, host, { allowedExtra = () => false } = {}) {
+  const rootInfo = await lstat(pluginRoot);
+  if (!rootInfo.isDirectory() || rootInfo.isSymbolicLink()) {
+    fail(`OpenSocrates ${host} payload is not a real directory: ${pluginRoot}`);
+  }
+  const releasePath = join(pluginRoot, "release-manifest.json");
+  const manifestPath = join(pluginRoot, HOST_LAYOUTS[host].manifestRelative);
+  const checksumPath = join(pluginRoot, "checksums.sha256");
+  for (const [target, label] of [
+    [releasePath, `${host} release manifest`],
+    [manifestPath, `${host} plugin manifest`],
+    [checksumPath, `${host} checksum inventory`],
+  ]) {
+    await requireRegularFileEntry(target, label);
+  }
+  const release = await readJsonObject(releasePath);
+  const version = release.product_version;
+  if (
+    release.schema !== "opensocrates.plugin-release-manifest/1.0.0" ||
+    release.host !== host ||
+    typeof version !== "string" ||
+    version.trim().length === 0 ||
+    !Number.isInteger(release.content_revision) ||
+    release.content_revision < 1
+  ) {
+    fail(`OpenSocrates ${host} payload has an invalid release identity`);
+  }
+  const manifest = await readJsonObject(manifestPath);
+  if (manifest.name !== PLUGIN_NAME || manifest.version !== version) {
+    fail(`OpenSocrates ${host} payload has a mismatched plugin identity`);
+  }
+
+  const lines = (await readFile(checksumPath, "utf8"))
+    .split(/\r?\n/u)
+    .map((line) => line.trim())
+    .filter(Boolean);
+  if (lines.length === 0) fail(`OpenSocrates ${host} payload has an empty checksum inventory`);
+  const declared = new Set();
+  for (const line of lines) {
+    const match = line.match(/^([a-fA-F0-9]{64})\s+[*]?(.+)$/u);
+    if (!match) fail(`OpenSocrates ${host} payload has an invalid checksum inventory`);
+    const item = match[2].trim();
+    if (!isSafeArchivePath(item) || item === "checksums.sha256" || declared.has(item)) {
+      fail(`OpenSocrates ${host} payload has an unsafe checksum path`);
+    }
+    const target = join(pluginRoot, ...item.split("/"));
+    if (!(await entryExists(target))) fail(`OpenSocrates ${host} payload is missing a declared file`);
+    const info = await lstat(target);
+    if (!info.isFile() || info.isSymbolicLink()) {
+      fail(`OpenSocrates ${host} payload contains an unsafe declared file`);
+    }
+    if ((await sha256File(target)) !== match[1].toLowerCase()) {
+      fail(`OpenSocrates ${host} payload checksum verification failed`);
+    }
+    declared.add(item);
+  }
+  const actual = await walkFiles(pluginRoot);
+  for (const item of actual) {
+    if (item === "checksums.sha256" || declared.has(item) || allowedExtra(item)) continue;
+    fail(`OpenSocrates ${host} payload contains an unowned file: ${item}`);
+  }
+  return { version, files: actual };
+}
+
+async function cacheHasLiveUser(versionRoot) {
+  const marker = join(versionRoot, ".in_use");
+  if (!(await entryExists(marker))) return false;
+  const markerInfo = await lstat(marker);
+  if (!markerInfo.isDirectory() || markerInfo.isSymbolicLink()) {
+    fail("OpenSocrates cache has an unsafe .in_use marker");
+  }
+  const entries = await readdir(marker, { withFileTypes: true });
+  for (const entry of entries) {
+    if (entry.isSymbolicLink() || !entry.isFile() || !/^[1-9]\d*$/u.test(entry.name)) {
+      fail("OpenSocrates cache has an unrecognized .in_use entry");
+    }
+    const pid = Number(entry.name);
+    if (!Number.isSafeInteger(pid)) fail("OpenSocrates cache has an invalid .in_use process ID");
+    try {
+      process.kill(pid, 0);
+      return true;
+    } catch (error) {
+      if (error?.code === "EPERM") return true;
+      if (error?.code !== "ESRCH") {
+        fail("OpenSocrates cache use could not be determined safely");
+      }
+    }
+  }
+  return false;
+}
+
+async function removeDirectoryIfEmpty(target) {
+  if (!(await entryExists(target))) return false;
+  try {
+    await rmdir(target);
+    return true;
+  } catch (error) {
+    if (error?.code === "ENOTEMPTY" || error?.code === "EEXIST") return false;
+    throw error;
+  }
+}
+
+async function purgeHostCache(host, paths) {
+  if (paths.cacheRoot === null) {
+    return { component: "plugin-cache", status: "absent", path: paths.cacheRoot };
+  }
+  if (!(await entryExists(paths.cacheRoot))) {
+    let removedEmptyMarketplace = false;
+    if (await entryExists(paths.cacheMarketplaceRoot)) {
+      await requireSafePathBelow(paths.hostHome, paths.cacheMarketplaceRoot, `${host} cache marketplace`);
+      const info = await lstat(paths.cacheMarketplaceRoot);
+      if (!info.isDirectory() || info.isSymbolicLink()) {
+        fail(`refusing an unsafe ${host} OpenSocrates cache marketplace`);
+      }
+      if ((await readdir(paths.cacheMarketplaceRoot)).length !== 0) {
+        fail(`refusing an unrecognized entry in the ${host} OpenSocrates cache marketplace`);
+      }
+      await rmdir(paths.cacheMarketplaceRoot);
+      removedEmptyMarketplace = true;
+    }
+    return {
+      component: "plugin-cache",
+      status: removedEmptyMarketplace ? "removed" : "absent",
+      path: paths.cacheMarketplaceRoot,
+    };
+  }
+  await requireSafePathBelow(paths.hostHome, paths.cacheRoot, `${host} plugin cache`);
+  const rootInfo = await lstat(paths.cacheRoot);
+  if (!rootInfo.isDirectory() || rootInfo.isSymbolicLink()) {
+    fail(`refusing an unsafe ${host} OpenSocrates plugin-cache root`);
+  }
+  const versions = await readdir(paths.cacheRoot, { withFileTypes: true });
+  let removed = 0;
+  let pending = 0;
+  for (const version of versions) {
+    if (!version.isDirectory() || version.isSymbolicLink()) {
+      fail(`refusing an unrecognized entry in the ${host} OpenSocrates plugin cache`);
+    }
+    const versionRoot = join(paths.cacheRoot, version.name);
+    await requireSafePathBelow(paths.cacheRoot, versionRoot, `${host} cached plugin version`);
+    const identity = await packageIdentityForPurge(versionRoot, host, {
+      allowedExtra: (item) => item === ".orphaned_at" || item.startsWith(".in_use/"),
+    });
+    if (identity.version !== version.name) {
+      fail(`refusing a ${host} cache directory whose version does not match its manifests`);
+    }
+    if (await cacheHasLiveUser(versionRoot)) {
+      pending += 1;
+      continue;
+    }
+    await rm(versionRoot, { recursive: true });
+    removed += 1;
+  }
+  if (pending === 0) {
+    const cacheRootRemoved = await removeDirectoryIfEmpty(paths.cacheRoot);
+    if (!cacheRootRemoved && (await entryExists(paths.cacheRoot))) {
+      return {
+        component: "plugin-cache",
+        status: "pending",
+        path: paths.cacheRoot,
+        detail: "cache-changed-during-purge",
+      };
+    }
+    const marketplaceRemoved = await removeDirectoryIfEmpty(paths.cacheMarketplaceRoot);
+    if (!marketplaceRemoved && (await entryExists(paths.cacheMarketplaceRoot))) {
+      return {
+        component: "plugin-cache",
+        status: "pending",
+        path: paths.cacheMarketplaceRoot,
+        detail: "unrecognized-cache-marketplace-content",
+      };
+    }
+  }
+  return {
+    component: "plugin-cache",
+    status: pending > 0 ? "pending" : removed > 0 ? "removed" : "absent",
+    path: paths.cacheRoot,
+    detail: pending > 0 ? "host-in-use" : null,
+  };
+}
+
+async function purgeClaudePluginData(paths) {
+  const results = [];
+  for (const target of paths.pluginData) {
+    if (!(await entryExists(target))) {
+      results.push({ component: "plugin-data", status: "absent", path: target });
+      continue;
+    }
+    await requireSafePathBelow(paths.hostHome, target, "Claude OpenSocrates plugin data");
+    const info = await lstat(target);
+    if (!info.isDirectory() || info.isSymbolicLink()) {
+      fail(`refusing an unsafe Claude OpenSocrates plugin-data path: ${target}`);
+    }
+    if ((await readdir(target)).length !== 0) {
+      results.push({
+        component: "plugin-data",
+        status: "pending",
+        path: target,
+        detail: "nonempty-unverified-data",
+      });
+      continue;
+    }
+    await rmdir(target);
+    results.push({ component: "plugin-data", status: "removed", path: target });
+  }
+  return results;
+}
+
+async function verifyOpenCodePurgeRoot(root) {
+  await requireOwnedRoot(root, "opencode");
+  const manifestPath = join(root, OPENCODE_INSTALL_MANIFEST);
+  await requireRegularFileEntry(manifestPath, "OpenCode installation inventory");
+  const manifest = await readJsonObject(manifestPath);
+  const manifestKeys = Object.keys(manifest).sort();
+  if (
+    !jsonDeepEqual(manifestKeys, ["bridgeSha256", "files", "schema", "version"]) ||
+    manifest.schema !== "opensocrates.opencode-installation/1.0.0" ||
+    typeof manifest.version !== "string" ||
+    manifest.version.trim().length === 0 ||
+    !/^[a-f0-9]{64}$/u.test(manifest.bridgeSha256) ||
+    manifest.files === null ||
+    typeof manifest.files !== "object" ||
+    Array.isArray(manifest.files)
+  ) {
+    fail("OpenCode installation inventory is invalid");
+  }
+  const declared = Object.keys(manifest.files);
+  const actual = new Set(await walkFiles(root));
+  actual.delete(OPENCODE_INSTALL_MANIFEST);
+  if (
+    actual.size !== declared.length ||
+    declared.some((item) => !isSafeArchivePath(item) || !actual.has(item) || !/^[a-f0-9]{64}$/u.test(manifest.files[item]))
+  ) {
+    fail("OpenCode installation inventory does not cover the complete managed skill");
+  }
+  for (const item of declared) {
+    if ((await sha256File(join(root, ...item.split("/")))) !== manifest.files[item]) {
+      fail(`OpenCode installed file checksum mismatch for ${item}`);
+    }
+  }
+  return manifest;
+}
+
+async function verifyManagedTreeForPurge(host, root) {
+  if (host === "opencode") return verifyOpenCodePurgeRoot(root);
+  await requireOwnedRoot(root, host);
+  const layout = HOST_LAYOUTS[host];
+  const pluginRoot = join(root, layout.pluginRelative);
+  const identity = await packageIdentityForPurge(pluginRoot, host, {
+    allowedExtra: (item) => FILE_DROP_HOSTS.includes(host) && item === MARKER_NAME,
+  });
+  if (FILE_DROP_HOSTS.includes(host)) return identity;
+
+  const marketplacePath = join(root, layout.marketplaceRelative);
+  await requireRegularFileEntry(marketplacePath, `${host} marketplace manifest`);
+  const marketplace = await readJsonObject(marketplacePath);
+  const expected = expectedMarketplace(host);
+  if (host === "claude") expected.metadata.version = identity.version;
+  if (!jsonDeepEqual(marketplace, expected)) {
+    fail(`${host} managed marketplace does not match the exact owned plugin inventory`);
+  }
+  const allowed = new Set([
+    MARKER_NAME,
+    layout.marketplaceRelative.split(sep).join("/"),
+    ...identity.files.map((item) => join(layout.pluginRelative, ...item.split("/")).split(sep).join("/")),
+  ]);
+  for (const item of await walkFiles(root)) {
+    if (!allowed.has(item)) fail(`${host} managed marketplace contains an unowned file: ${item}`);
+  }
+  return identity;
+}
+
+async function removeOwnedManagedRoot(host, paths) {
+  if (!(await entryExists(paths.root))) {
+    return { component: "managed-root", status: "absent", path: paths.root };
+  }
+  await requireSafePathBelow(paths.hostHome, paths.root, `${host} managed root`);
+  await verifyManagedTreeForPurge(host, paths.root);
+  const backup = join(transientParent(host, paths), `.opensocrates.removed-${randomUUID()}`);
+  await requireSafePathBelow(paths.hostHome, backup, `${host} removal backup`);
+  await rename(paths.root, backup);
+  try {
+    await verifyManagedTreeForPurge(host, backup);
+    await rm(backup, { recursive: true });
+  } catch (error) {
+    if ((await entryExists(backup)) && !(await entryExists(paths.root))) {
+      const restored = await recoveryStep(`restore the ${host} managed root after purge cleanup failed`, async () => {
+        await verifyManagedTreeForPurge(host, backup);
+        await rename(backup, paths.root);
+      });
+      if (!restored) {
+        console.error(`error: recoverable ${host} files remain at: ${backup}`);
+        console.error(`error: retry command: opensocrates remove --host ${host} --purge`);
+      }
+    }
+    throw error;
+  }
+  return { component: "managed-root", status: "removed", path: paths.root };
+}
+
+async function cleanupTransientRootResidue(host, paths) {
+  const parent = transientParent(host, paths);
+  if (!(await entryExists(parent))) {
+    return { component: "transaction-residue", status: "absent", path: parent };
+  }
+  await requireSafePathBelow(paths.hostHome, parent, `${host} transient parent`, { allowRoot: true });
+  const names = (await readdir(parent)).filter((name) =>
+    /^\.opensocrates\.(?:staging|backup|removed)-[A-Za-z0-9-]+$/u.test(name),
+  );
+  let removed = 0;
+  for (const name of names) {
+    const target = join(parent, name);
+    await requireSafePathBelow(parent, target, `${host} transaction residue`);
+    const info = await lstat(target);
+    if (!info.isDirectory() || info.isSymbolicLink()) {
+      fail(`refusing unsafe ${host} transaction residue: ${target}`);
+    }
+    if ((await readdir(target)).length !== 0) {
+      try {
+        await verifyManagedTreeForPurge(host, target);
+      } catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        fail(`refusing unverifiable ${host} transaction residue at ${target}: ${detail}`);
+      }
+    }
+    await rm(target, { recursive: true });
+    removed += 1;
+  }
+  return {
+    component: "transaction-residue",
+    status: removed > 0 ? "removed" : "absent",
+    path: parent,
+  };
+}
+
+async function readOpenCodeBridgeSidecar(target) {
+  const info = await lstat(target);
+  if (!info.isFile() || info.isSymbolicLink()) {
+    fail(`OpenCode bridge ownership sidecar is unsafe: ${target}`);
+  }
+  const sidecar = await readJsonObject(target);
+  const expectedKeys = [...Object.keys(OPENCODE_MARKER), "version", "bridgeSha256"].sort();
+  const observedKeys = Object.keys(sidecar).sort();
+  const marker = Object.fromEntries(Object.keys(OPENCODE_MARKER).map((key) => [key, sidecar[key]]));
   if (
-    release.product_version !== PRODUCT_VERSION ||
-    release.host !== host ||
-    release.schema !== "opensocrates.plugin-release-manifest/1.0.0"
+    expectedKeys.length !== observedKeys.length ||
+    expectedKeys.some((key, index) => key !== observedKeys[index]) ||
+    !markerMatches(marker, "opencode") ||
+    typeof sidecar.version !== "string" ||
+    sidecar.version.trim().length === 0 ||
+    !/^[a-f0-9]{64}$/u.test(sidecar.bridgeSha256)
   ) {
-    fail("package release manifest does not match this installer");
+    fail(`OpenCode bridge ownership sidecar is invalid: ${target}`);
   }
-  if (HOST_LAYOUTS[host].requiresRuntime) {
-    const runtime = join(pluginRoot, "runtime", "darwin-arm64", "opensocrates-runtime", "opensocrates-runtime");
-    const runtimeInfo = await stat(runtime);
-    if (!runtimeInfo.isFile() || (runtimeInfo.mode & 0o111) === 0) {
-      fail("package is missing the executable darwin-arm64 runtime");
+  return sidecar;
+}
+
+async function purgeOpenCodeBridge(paths) {
+  const bridgePresent = await entryExists(paths.bridge);
+  const markerPresent = await entryExists(paths.bridgeMarker);
+  if (!bridgePresent && !markerPresent) {
+    return { component: "opencode-bridge", status: "absent", path: paths.bridge };
+  }
+  await requireSafePathBelow(paths.hostHome, paths.bridge, "OpenCode bridge");
+  await requireSafePathBelow(paths.hostHome, paths.bridgeMarker, "OpenCode bridge sidecar");
+  if (bridgePresent && !markerPresent) {
+    fail("refusing to remove an OpenCode bridge without its ownership sidecar");
+  }
+  const sidecar = await readOpenCodeBridgeSidecar(paths.bridgeMarker);
+  if (bridgePresent) {
+    const bridgeInfo = await lstat(paths.bridge);
+    if (!bridgeInfo.isFile() || bridgeInfo.isSymbolicLink() || (await sha256File(paths.bridge)) !== sidecar.bridgeSha256) {
+      fail("refusing to remove an OpenCode bridge whose ownership checksum does not match");
     }
-  } else if (
-    release.launchers?.length !== 0 ||
-    release.runtime_targets?.length !== 0 ||
-    (await exists(join(pluginRoot, "runtime"))) ||
-    (await exists(join(pluginRoot, "hooks"))) ||
-    (await exists(join(pluginRoot, "bin"))) ||
-    ((host === "cursor" || host === "grok") && (await exists(join(pluginRoot, "mcp.json")))) ||
-    (host === "grok" &&
-      ((await exists(join(pluginRoot, "commands"))) ||
-        (await exists(join(pluginRoot, "agents"))) ||
-        (await exists(join(pluginRoot, ".mcp.json")))))
-  ) {
-    fail(`${host} package contains an unexpected native runtime or launcher surface`);
+    await rm(paths.bridge);
   }
-  if (host === "opencode") {
-    if (
-      manifest.minimum_opencode_version !== "1.18.18" ||
-      manifest.stable_plugin_hook !== "chat.message" ||
-      manifest.beta_v2_api !== false ||
-      !(await exists(join(pluginRoot, "plugins", "opensocrates.js"))) ||
-      !(await exists(join(pluginRoot, "skills", "opensocrates", "SKILL.md")))
-    ) {
-      fail("OpenCode package does not match the verified stable bridge contract");
+  await rm(paths.bridgeMarker);
+  return { component: "opencode-bridge", status: "removed", path: paths.bridge };
+}
+
+async function purgeOpenCodeBridgeResidue(paths) {
+  if (!(await entryExists(paths.bridgeParent))) {
+    return { component: "opencode-bridge-residue", status: "absent", path: paths.bridgeParent };
+  }
+  await requireSafePathBelow(paths.hostHome, paths.bridgeParent, "OpenCode bridge parent");
+  const entries = await readdir(paths.bridgeParent, { withFileTypes: true });
+  const bridgeNames = entries
+    .filter((entry) => /^\.opensocrates\.js\.(?:staging|backup|removed)-[A-Za-z0-9-]+$/u.test(entry.name))
+    .map((entry) => entry.name);
+  const markerNames = entries
+    .filter((entry) =>
+      /^\.opensocrates-managed\.json\.(?:staging|backup|removed)-[A-Za-z0-9-]+$/u.test(entry.name),
+    )
+    .map((entry) => entry.name);
+  const bridges = new Map();
+  for (const name of bridgeNames) {
+    const target = join(paths.bridgeParent, name);
+    await requireSafePathBelow(paths.bridgeParent, target, "OpenCode bridge residue");
+    const info = await lstat(target);
+    if (!info.isFile() || info.isSymbolicLink()) fail(`unsafe OpenCode bridge residue: ${target}`);
+    bridges.set(target, await sha256File(target));
+  }
+  let removed = 0;
+  for (const name of markerNames) {
+    const marker = join(paths.bridgeParent, name);
+    await requireSafePathBelow(paths.bridgeParent, marker, "OpenCode bridge sidecar residue");
+    const sidecar = await readOpenCodeBridgeSidecar(marker);
+    const matches = [...bridges].filter(([, digest]) => digest === sidecar.bridgeSha256);
+    if (matches.length > 1) fail("ambiguous OpenCode bridge transaction residue");
+    if (matches.length === 1) {
+      const [[bridge]] = matches;
+      await rm(bridge);
+      bridges.delete(bridge);
+      removed += 1;
     }
+    await rm(marker);
+    removed += 1;
   }
-  return verifyPackageChecksums(pluginRoot);
+  if (bridges.size > 0) fail("refusing OpenCode bridge residue without an ownership sidecar");
+  return {
+    component: "opencode-bridge-residue",
+    status: removed > 0 ? "removed" : "absent",
+    path: paths.bridgeParent,
+  };
 }
 
 async function prepareVerifiedPackage(options, host = options.host) {
@@ -1781,7 +3407,9 @@ async function preflightHost(host, action) {
   }
   const paths = managedPaths(host);
   if (host === "opencode") {
-    const presence = await Promise.all([paths.root, paths.bridge, paths.bridgeMarker].map((target) => exists(target)));
+    const presence = await Promise.all(
+      [paths.root, paths.bridge, paths.bridgeMarker].map((target) => entryExists(target)),
+    );
     if (presence.some(Boolean) && !presence.every(Boolean)) {
       fail("OpenCode has a partial or unowned OpenSocrates installation; refusing to replace it");
     }
@@ -1803,7 +3431,7 @@ async function preflightHost(host, action) {
         "refusing to overwrite an unmanaged location",
     );
   }
-  const rootExists = await exists(paths.root);
+  const rootExists = await entryExists(paths.root);
   if (rootExists) {
     await requireOwnedRoot(paths.root, host);
   }
@@ -1830,7 +3458,7 @@ async function preflightSelectedHosts(options, action, desiredState) {
   const candidates = assetHosts.length > 0 ? assetHosts : SUPPORTED_HOSTS;
   const desiredHosts = new Set(desiredState.installedHosts);
   const rootPresence = Object.fromEntries(
-    await Promise.all(candidates.map(async (host) => [host, await exists(managedPaths(host).root)])),
+    await Promise.all(candidates.map(async (host) => [host, await entryExists(managedPaths(host).root)])),
   );
   const settled = await Promise.allSettled(candidates.map((host) => preflightHost(host, action)));
   const successes = new Map();
@@ -1924,15 +3552,15 @@ async function activateInstallation(transaction) {
     transaction.registrationRemoved = true;
     removeRegistration(host, previousEntry, previousState);
   }
-  if (await exists(paths.root)) {
+  if (await entryExists(paths.root)) {
     await rename(paths.root, transaction.backup);
     transaction.backupCreated = true;
   }
-  if (host === "opencode" && (await exists(paths.bridge))) {
+  if (host === "opencode" && (await entryExists(paths.bridge))) {
     await rename(paths.bridge, transaction.bridgeBackup);
     transaction.bridgeBackupCreated = true;
   }
-  if (host === "opencode" && (await exists(paths.bridgeMarker))) {
+  if (host === "opencode" && (await entryExists(paths.bridgeMarker))) {
     await rename(paths.bridgeMarker, transaction.bridgeMarkerBackup);
     transaction.bridgeMarkerBackupCreated = true;
   }
@@ -2251,8 +3879,11 @@ function removalTransaction(preflight) {
         : null,
     registrationRemoved: false,
     backupCreated: false,
+    rootCommitted: false,
     bridgeBackupCreated: false,
+    bridgeCommitted: false,
     bridgeMarkerBackupCreated: false,
+    bridgeMarkerCommitted: false,
   };
 }
 
@@ -2262,30 +3893,57 @@ async function activateRemoval(transaction) {
     transaction.registrationRemoved = true;
     removeRegistration(host, previousEntry, previousState);
   }
-  if (await exists(paths.root)) {
+  if (await entryExists(paths.root)) {
     await rename(paths.root, transaction.backup);
     transaction.backupCreated = true;
   }
-  if (host === "opencode" && (await exists(paths.bridge))) {
+  if (host === "opencode" && (await entryExists(paths.bridge))) {
     await rename(paths.bridge, transaction.bridgeBackup);
     transaction.bridgeBackupCreated = true;
   }
-  if (host === "opencode" && (await exists(paths.bridgeMarker))) {
+  if (host === "opencode" && (await entryExists(paths.bridgeMarker))) {
     await rename(paths.bridgeMarker, transaction.bridgeMarkerBackup);
     transaction.bridgeMarkerBackupCreated = true;
   }
 }
 
 async function rollbackRemoval(transaction) {
-  let restored = !transaction.backupCreated;
-  if (transaction.backupCreated && (await exists(transaction.backup))) {
+  let complete = true;
+  let restored = !transaction.rootExists;
+  if (transaction.rootExists && transaction.backupCreated && (await entryExists(transaction.backup))) {
     restored = await recoveryStep(`restore the removed ${transaction.host} files`, async () => {
-      await requireOwnedRoot(transaction.backup, transaction.host);
+      await verifyManagedTreeForPurge(transaction.host, transaction.backup);
       await rename(transaction.backup, transaction.paths.root);
+      try {
+        await verifyManagedTreeForPurge(transaction.host, transaction.paths.root);
+      } catch (error) {
+        try {
+          await rename(transaction.paths.root, transaction.backup);
+        } catch (requarantineError) {
+          const detail = requarantineError instanceof Error ? requarantineError.message : String(requarantineError);
+          transaction.backupCreated = await entryExists(transaction.backup);
+          fail(
+            `the restored ${transaction.host} tree failed verification and could not be returned to ` +
+              `${transaction.backup}: ${detail}`,
+          );
+        }
+        throw error;
+      }
+      transaction.backupCreated = false;
+    });
+  } else if (transaction.rootExists && !transaction.rootCommitted && !transaction.backupCreated) {
+    restored = await recoveryStep(`verify the existing ${transaction.host} files`, async () => {
+      await verifyManagedTreeForPurge(transaction.host, transaction.paths.root);
     });
   }
-  if (transaction.registrationRemoved && transaction.previousEntry !== null && restored) {
-    await recoveryStep(`restore the removed ${transaction.host} registration`, async () => {
+  complete = restored && complete;
+  if (
+    transaction.registrationRemoved &&
+    transaction.previousEntry !== null &&
+    restored &&
+    (await entryExists(transaction.paths.root))
+  ) {
+    const registrationRestored = await recoveryStep(`restore the removed ${transaction.host} registration`, async () => {
       addRegistration(
         transaction.host,
         transaction.paths.root,
@@ -2293,37 +3951,92 @@ async function rollbackRemoval(transaction) {
         { enabled: transaction.previousState.kind !== "disabled" },
       );
     });
+    complete = registrationRestored && complete;
+  } else if (transaction.registrationRemoved && transaction.previousEntry !== null) {
+    complete = false;
   }
   if (transaction.host === "opencode") {
-    if (transaction.bridgeBackupCreated && (await exists(transaction.bridgeBackup))) {
-      await recoveryStep("restore the removed OpenCode bridge", async () => {
+    let bridgeRestored = !transaction.rootExists;
+    if (
+      transaction.rootExists &&
+      transaction.bridgeBackupCreated &&
+      (await entryExists(transaction.bridgeBackup))
+    ) {
+      bridgeRestored = await recoveryStep("restore the removed OpenCode bridge", async () => {
         await rename(transaction.bridgeBackup, transaction.paths.bridge);
+        transaction.bridgeBackupCreated = false;
       });
+    } else if (transaction.rootExists && !transaction.bridgeCommitted && !transaction.bridgeBackupCreated) {
+      bridgeRestored = await entryExists(transaction.paths.bridge);
     }
-    if (transaction.bridgeMarkerBackupCreated && (await exists(transaction.bridgeMarkerBackup))) {
-      await recoveryStep("restore the removed OpenCode bridge sidecar", async () => {
+    complete = bridgeRestored && complete;
+    let markerRestored = !transaction.rootExists;
+    if (
+      transaction.rootExists &&
+      transaction.bridgeMarkerBackupCreated &&
+      (await entryExists(transaction.bridgeMarkerBackup))
+    ) {
+      markerRestored = await recoveryStep("restore the removed OpenCode bridge sidecar", async () => {
         await rename(transaction.bridgeMarkerBackup, transaction.paths.bridgeMarker);
+        transaction.bridgeMarkerBackupCreated = false;
       });
+    } else if (
+      transaction.rootExists &&
+      !transaction.bridgeMarkerCommitted &&
+      !transaction.bridgeMarkerBackupCreated
+    ) {
+      markerRestored = await entryExists(transaction.paths.bridgeMarker);
     }
+    complete = markerRestored && complete;
   }
+  transaction.originalStateRestored = complete;
+  return complete;
 }
 
-async function commitRemoval(transaction) {
-  if (transaction.backupCreated && (await exists(transaction.backup))) {
-    await requireOwnedRoot(transaction.backup, transaction.host);
+async function commitRemoval(transaction, { beforeBackupDelete = null } = {}) {
+  if (transaction.backupCreated && (await entryExists(transaction.backup))) {
+    await verifyManagedTreeForPurge(transaction.host, transaction.backup);
+    if (beforeBackupDelete !== null) {
+      await beforeBackupDelete(Object.freeze({
+        host: transaction.host,
+        backup: transaction.backup,
+      }));
+    }
     await rm(transaction.backup, { recursive: true });
+    transaction.backupCreated = false;
+    transaction.rootCommitted = true;
   }
   if (transaction.host === "opencode") {
-    for (const [created, backup, label] of [
-      [transaction.bridgeBackupCreated, transaction.bridgeBackup, "bridge"],
-      [transaction.bridgeMarkerBackupCreated, transaction.bridgeMarkerBackup, "bridge sidecar"],
+    for (const [flag, backup, label] of [
+      ["bridgeBackupCreated", transaction.bridgeBackup, "bridge"],
+      ["bridgeMarkerBackupCreated", transaction.bridgeMarkerBackup, "bridge sidecar"],
     ]) {
-      if (!created || !(await exists(backup))) continue;
+      if (!transaction[flag] || !(await entryExists(backup))) continue;
       const info = await lstat(backup);
       if (!info.isFile() || info.isSymbolicLink()) {
         fail(`refusing to remove an unsafe OpenCode ${label} backup: ${backup}`);
       }
       await rm(backup);
+      transaction[flag] = false;
+      if (flag === "bridgeBackupCreated") transaction.bridgeCommitted = true;
+      else transaction.bridgeMarkerCommitted = true;
+    }
+  }
+}
+
+async function validateRemovalCommit(transaction) {
+  if (transaction.backupCreated && (await entryExists(transaction.backup))) {
+    await verifyManagedTreeForPurge(transaction.host, transaction.backup);
+  }
+  if (transaction.host !== "opencode") return;
+  for (const [created, backup, label] of [
+    [transaction.bridgeBackupCreated, transaction.bridgeBackup, "bridge"],
+    [transaction.bridgeMarkerBackupCreated, transaction.bridgeMarkerBackup, "bridge sidecar"],
+  ]) {
+    if (!created || !(await entryExists(backup))) continue;
+    const info = await lstat(backup);
+    if (!info.isFile() || info.isSymbolicLink()) {
+      fail(`refusing to remove an unsafe OpenCode ${label} backup: ${backup}`);
     }
   }
 }
@@ -2539,14 +4252,42 @@ async function installLaunchAgent(channel, hosts) {
   }
 }
 
+async function requireOwnedLaunchAgent(target) {
+  const info = await lstat(target);
+  if (!info.isFile() || info.isSymbolicLink()) {
+    fail(`refusing to remove an unsafe LaunchAgent path: ${target}`);
+  }
+  const document = await readFile(target, "utf8");
+  const labelPattern = new RegExp(
+    `<key>\\s*Label\\s*</key>\\s*<string>\\s*${AUTO_UPDATE_LABEL.replaceAll(".", "\\.")}\\s*</string>`,
+    "gu",
+  );
+  const argumentBlocks = [
+    ...document.matchAll(/<key>\s*ProgramArguments\s*<\/key>\s*<array>([\s\S]*?)<\/array>/gu),
+  ];
+  const arguments_ =
+    argumentBlocks.length === 1
+      ? [...argumentBlocks[0][1].matchAll(/<string>([\s\S]*?)<\/string>/gu)].map((match) => match[1].trim())
+      : [];
+  if (
+    [...document.matchAll(labelPattern)].length !== 1 ||
+    arguments_.length !== 5 ||
+    !arguments_[0].startsWith("/") ||
+    arguments_[1] !== "--yes" ||
+    !/^opensocrates@(?:latest|next)$/u.test(arguments_[2]) ||
+    arguments_[3] !== "auto-update" ||
+    arguments_[4] !== "run"
+  ) {
+    fail(`refusing to remove a LaunchAgent without the OpenSocrates ownership identity: ${target}`);
+  }
+}
+
 async function disableLaunchAgent() {
   const paths = statePaths();
-  const agentPresent = await exists(paths.launchAgent);
+  const agentPresent = await entryExists(paths.launchAgent);
   if (agentPresent) {
-    const info = await lstat(paths.launchAgent);
-    if (!info.isFile() || info.isSymbolicLink()) {
-      fail(`refusing to remove an unsafe LaunchAgent path: ${paths.launchAgent}`);
-    }
+    await requireSafePathBelow(paths.launchAgentsDirectory, paths.launchAgent, "OpenSocrates LaunchAgent");
+    await requireOwnedLaunchAgent(paths.launchAgent);
   }
   if (process.env.OPENSOCRATES_SKIP_LAUNCHCTL !== "1") {
     stopLoadedLaunchAgent();
@@ -2562,7 +4303,7 @@ async function disableAutoUpdateState(desired) {
   };
 }
 
-async function runRemove(options) {
+async function runStandardRemove(options, { report = true, beforeBackupDelete = null } = {}) {
   const desired = await readDesiredState();
   const preflights = await preflightSelectedHosts(options, "remove", desired);
   const removedHosts = preflights.map((item) => item.host);
@@ -2577,14 +4318,23 @@ async function runRemove(options) {
       ? { ...desired.autoUpdate, hosts: remainingAutoUpdateHosts }
       : { enabled: false, hosts: [], nextCheckAt: null },
   };
-  const launchAgentPresent = await exists(statePaths().launchAgent);
+  const launchAgentPresent = await entryExists(statePaths().launchAgent);
   const schedulerNeedsChange =
     options.host === ALL_HOST ||
     remainingHosts.length === 0 ||
     launchAgentPresent !== keepAutoUpdate ||
     desired.autoUpdate.hosts.some((host) => removedHosts.includes(host));
   const transactions = preflights.map(removalTransaction);
+  // Validate every source tree before the first unregister/rename. The same
+  // check runs again after activation and immediately before deletion to
+  // close TOCTOU gaps without stranding pre-existing drift in a backup.
+  for (const transaction of transactions) {
+    if (transaction.rootExists) {
+      await verifyManagedTreeForPurge(transaction.host, transaction.paths.root);
+    }
+  }
   let schedulerTouched = false;
+  let desiredWritten = false;
   try {
     for (const transaction of transactions) await activateRemoval(transaction);
     if (schedulerNeedsChange) {
@@ -2596,43 +4346,75 @@ async function runRemove(options) {
       }
     }
     await writeDesiredState(nextDesired);
+    desiredWritten = true;
+    for (const transaction of transactions) await validateRemovalCommit(transaction);
+    for (const transaction of transactions) {
+      await commitRemoval(transaction, { beforeBackupDelete });
+    }
   } catch (error) {
-    for (const transaction of [...transactions].reverse()) await rollbackRemoval(transaction);
+    let rollbackComplete = true;
+    for (const transaction of [...transactions].reverse()) {
+      const restored = await rollbackRemoval(transaction);
+      rollbackComplete = restored && rollbackComplete;
+    }
+    const unrestoredHosts = new Set(
+      transactions.filter((transaction) => transaction.originalStateRestored !== true).map((item) => item.host),
+    );
+    const recoveredHosts = desired.installedHosts.filter((host) => !unrestoredHosts.has(host));
+    const recoveredAutoUpdateHosts = desired.autoUpdate.hosts.filter((host) => recoveredHosts.includes(host));
+    const keepRecoveredAutoUpdate = desired.autoUpdate.enabled && recoveredAutoUpdateHosts.length > 0;
+    let recoveredDesired = {
+      ...desired,
+      installedHosts: recoveredHosts,
+      activeVersion: recoveredHosts.length === 0 ? null : desired.activeVersion,
+      autoUpdate: keepRecoveredAutoUpdate
+        ? { ...desired.autoUpdate, hosts: recoveredAutoUpdateHosts }
+        : { enabled: false, hosts: [], nextCheckAt: null },
+    };
+    let schedulerRestored = true;
     if (schedulerTouched) {
-      const schedulerRestored = await recoveryStep("restore the automatic updater after removal failure", async () => {
-        if (desired.autoUpdate.enabled) {
-          await installLaunchAgent(desired.channel, desired.autoUpdate.hosts);
+      schedulerRestored = await recoveryStep("reconcile the automatic updater after removal failure", async () => {
+        if (recoveredDesired.autoUpdate.enabled) {
+          await installLaunchAgent(recoveredDesired.channel, recoveredDesired.autoUpdate.hosts);
         } else {
           await disableLaunchAgent();
         }
       });
-      if (!schedulerRestored && desired.autoUpdate.enabled) {
-        await recoveryStep("record the disabled updater after removal failure", async () => {
-          await writeDesiredState({
-            ...desired,
-            autoUpdate: {
-              enabled: false,
-              hosts: [],
-              nextCheckAt: null,
-            },
-          });
-        });
-      }
-    } else if (!nextDesired.autoUpdate.enabled && desired.autoUpdate.enabled) {
-      await recoveryStep("record the disabled updater after removal failure", async () => {
-        await writeDesiredState({
-          ...desired,
+      if (!schedulerRestored && recoveredDesired.autoUpdate.enabled) {
+        recoveredDesired = {
+          ...recoveredDesired,
           autoUpdate: {
             enabled: false,
             hosts: [],
             nextCheckAt: null,
           },
-        });
+        };
+      }
+      rollbackComplete = schedulerRestored && rollbackComplete;
+    }
+    if (desiredWritten || !rollbackComplete || !schedulerRestored) {
+      const stateRestored = await recoveryStep("record desired state after removal failure", async () => {
+        await writeDesiredState(recoveredDesired);
       });
+      rollbackComplete = stateRestored && rollbackComplete;
+    }
+    if (!rollbackComplete) {
+      console.error("error: removal cleanup is incomplete; no success was recorded.");
+      for (const transaction of transactions) {
+        if (!transaction.backupCreated || !(await entryExists(transaction.backup))) continue;
+        console.error(`error: preserved ${transaction.host} removal residue: ${transaction.backup}`);
+        console.error(
+          `error: safe cleanup retry: opensocrates remove --host ${transaction.host} --purge`,
+        );
+        console.error(
+          "error: if purge reports an integrity failure, inspect that exact UUID residue before manual cleanup: " +
+            `/bin/rm -rf -- ${shellQuote(transaction.backup)}`,
+        );
+      }
     }
     throw error;
   }
-  for (const transaction of transactions) await commitRemoval(transaction);
+  if (!report) return { removedHosts, desired: nextDesired };
   for (const host of removedHosts) {
     const label =
       host === "antigravity"
@@ -2649,6 +4431,454 @@ async function runRemove(options) {
     console.log(`OpenSocrates was removed from ${label}.`);
   }
   if (removedHosts.length === 0) console.log("OpenSocrates is not installed on any managed host.");
+  console.log("Removal scope: registrations and installer-managed roots only; this is not a complete uninstall.");
+  const residue = [];
+  for (const host of removedHosts) {
+    const paths = purgePathsFor(host);
+    for (const target of [paths.cacheRoot, paths.cacheMarketplaceRoot, ...paths.pluginData]) {
+      if (target !== null && (await entryExists(target))) residue.push(target);
+    }
+  }
+  for (const target of [statePaths().desiredState, statePaths().receipt]) {
+    if (await entryExists(target)) residue.push(target);
+  }
+  for (const target of [...new Set(residue)]) console.log(`Remaining OpenSocrates path: ${target}`);
+  if (removedHosts.includes("codex")) {
+    console.log("Codex OpenSocrates hook trust is preserved by this removal contract.");
+  }
+  console.log(`Next: close active hosts, then run opensocrates remove --host ${options.host} --purge.`);
+  return { removedHosts, desired: nextDesired };
+}
+
+async function purgeRegistration(host, paths) {
+  if (FILE_DROP_HOSTS.includes(host) || host === "opencode") {
+    return { status: "not-applicable", detail: "file-owned-host" };
+  }
+  try {
+    requireHostCli(host);
+  } catch (error) {
+    return {
+      status: "unverified",
+      detail: error instanceof Error ? error.message : String(error),
+    };
+  }
+  if (host === "claude") warnLegacyClaudeInstallation();
+  const entry = marketplaceEntry(host);
+  if (entry !== null && entryRoot(entry, host) !== paths.root) {
+    fail(`${host} OpenSocrates registration points to an unmanaged location`);
+  }
+  const state = pluginState(host);
+  const present = entry !== null || ["installed", "disabled"].includes(state.kind);
+  removeRegistration(host, entry, state);
+  const remainingEntry = marketplaceEntry(host);
+  const remainingState = pluginState(host);
+  if (remainingEntry !== null || ["installed", "disabled"].includes(remainingState.kind)) {
+    fail(`${host} did not confirm removal of the exact ${PLUGIN_ID} registration`);
+  }
+  return { status: present ? "removed" : "absent", detail: null };
+}
+
+async function capturePurgeComponent(hostResult, component, action) {
+  try {
+    const value = await action();
+    const items = Array.isArray(value) ? value : [value];
+    hostResult.components.push(...items);
+    return items;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    hostResult.components.push({ component, status: "failed", path: null, detail: message });
+    hostResult.errors.push(message);
+    return [];
+  }
+}
+
+function purgeComponentBlocksCompletion(component) {
+  return new Set(["pending", "failed"]).has(component.status);
+}
+
+function finalizePurgeHostResult(hostResult) {
+  const registrationComplete = new Set(["removed", "absent", "not-applicable"]).has(hostResult.registration);
+  hostResult.status =
+    registrationComplete &&
+    !hostResult.components.some(purgeComponentBlocksCompletion) &&
+    !purgeComponentBlocksCompletion(hostResult.extension)
+      ? "complete"
+      : "partial";
+  return hostResult.status === "complete";
+}
+
+async function resetPurgeTrustExtension(hostResult, options) {
+  if (hostResult.host !== "codex" || !options.resetTrust) return true;
+  try {
+    const reset = await resetCodexOpenSocratesHookTrust({ hooks: options.trustResetHooks ?? {} });
+    hostResult.extension = {
+      component: "host-security-trust",
+      status: reset.status,
+      removedCount: reset.removedEvents.length,
+      nextAction: null,
+    };
+    return true;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    hostResult.extension = {
+      component: "host-security-trust",
+      status: "failed",
+      removedCount: 0,
+      nextAction: "retry-purge-with-reset-trust-or-review-exact-sections-manually",
+      detail: message,
+    };
+    hostResult.errors.push(message);
+    return false;
+  }
+}
+
+function preservePurgeComponentsAfterTrustFailure(hostResult, paths) {
+  hostResult.registration = "preserved";
+  hostResult.registrationDetail = "not-attempted-after-trust-reset-failure";
+  const preserved = [
+    ["managed-root", paths.root],
+    ["transaction-residue", null],
+  ];
+  if (hostResult.host === "opencode") {
+    preserved.push(["opencode-bridge", paths.bridge], ["opencode-bridge-residue", null]);
+  }
+  if (paths.cacheRoot !== null) preserved.push(["plugin-cache", paths.cacheRoot]);
+  preserved.push(...paths.pluginData.map((path) => ["plugin-data", path]));
+  for (const [component, path] of preserved) {
+    hostResult.components.push({
+      component,
+      status: "preserved",
+      path,
+      detail: "not-attempted-after-trust-reset-failure",
+    });
+  }
+}
+
+async function purgeOneHost(hostResult, options) {
+  const paths = purgePathsFor(hostResult.host);
+  if (!(await resetPurgeTrustExtension(hostResult, options))) {
+    preservePurgeComponentsAfterTrustFailure(hostResult, paths);
+    finalizePurgeHostResult(hostResult);
+    return;
+  }
+  try {
+    const registration = await purgeRegistration(hostResult.host, paths);
+    hostResult.registration = registration.status;
+    hostResult.registrationDetail = registration.detail;
+    if (registration.status === "unverified") hostResult.errors.push(registration.detail);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    hostResult.registration = "failed";
+    hostResult.registrationDetail = message;
+    hostResult.errors.push(message);
+  }
+
+  await capturePurgeComponent(hostResult, "managed-root", () =>
+    removeOwnedManagedRoot(hostResult.host, paths),
+  );
+  if (hostResult.host === "opencode") {
+    await capturePurgeComponent(hostResult, "opencode-bridge", () => purgeOpenCodeBridge(paths));
+  }
+  await capturePurgeComponent(hostResult, "transaction-residue", () =>
+    cleanupTransientRootResidue(hostResult.host, paths),
+  );
+  if (hostResult.host === "opencode") {
+    await capturePurgeComponent(hostResult, "opencode-bridge-residue", () =>
+      purgeOpenCodeBridgeResidue(paths),
+    );
+  }
+  if (paths.cacheRoot !== null) {
+    await capturePurgeComponent(hostResult, "plugin-cache", () => purgeHostCache(hostResult.host, paths));
+  }
+  if (paths.pluginData.length > 0) {
+    await capturePurgeComponent(hostResult, "plugin-data", () => purgeClaudePluginData(paths));
+  }
+  finalizePurgeHostResult(hostResult);
+}
+
+function hostDeactivated(hostResult) {
+  const registrationComplete = new Set(["removed", "absent", "not-applicable"]).has(hostResult.registration);
+  const activationComponents = hostResult.components.filter((item) =>
+    new Set(["managed-root", "opencode-bridge"]).has(item.component),
+  );
+  return registrationComplete && !activationComponents.some(purgeComponentBlocksCompletion);
+}
+
+async function updatePurgeDesiredState(options, desired, result) {
+  const deactivated = result.hosts.filter(hostDeactivated).map((item) => item.host);
+  const installedHosts = desired.installedHosts.filter((host) => !deactivated.includes(host));
+  const autoUpdateHosts = desired.autoUpdate.hosts.filter((host) => !deactivated.includes(host));
+  const keepAutoUpdate = desired.autoUpdate.enabled && autoUpdateHosts.length > 0;
+  let nextDesired = {
+    ...desired,
+    installedHosts,
+    activeVersion: installedHosts.length === 0 ? null : desired.activeVersion,
+    autoUpdate: keepAutoUpdate
+      ? { ...desired.autoUpdate, hosts: autoUpdateHosts }
+      : { enabled: false, hosts: [], nextCheckAt: null },
+  };
+  const launchAgentPresent = await entryExists(statePaths().launchAgent);
+  const schedulerNeedsChange =
+    deactivated.length > 0 &&
+    (options.host === ALL_HOST ||
+      installedHosts.length === 0 ||
+      launchAgentPresent !== keepAutoUpdate ||
+      desired.autoUpdate.hosts.some((host) => deactivated.includes(host)));
+  if (schedulerNeedsChange) {
+    try {
+      if (keepAutoUpdate) await installLaunchAgent(desired.channel, autoUpdateHosts);
+      else await disableLaunchAgent();
+      result.finalization.components.push({
+        component: "launch-agent",
+        status: launchAgentPresent ? "removed-or-reconciled" : "absent",
+        path: statePaths().launchAgent,
+      });
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      result.finalization.components.push({
+        component: "launch-agent",
+        status: "failed",
+        path: statePaths().launchAgent,
+        detail: message,
+      });
+      result.finalization.errors.push(message);
+      nextDesired = desired;
+    }
+  } else {
+    result.finalization.components.push({
+      component: "launch-agent",
+      status: "preserved",
+      path: statePaths().launchAgent,
+    });
+  }
+  if (!schedulerNeedsChange && jsonDeepEqual(nextDesired, desired)) {
+    result.finalization.components.push({
+      component: "desired-state",
+      status: "preserved",
+      path: statePaths().desiredState,
+    });
+    return desired;
+  }
+  try {
+    nextDesired = await writeDesiredState(nextDesired);
+    result.finalization.components.push({
+      component: "desired-state",
+      status: "updated",
+      path: statePaths().desiredState,
+    });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    result.finalization.components.push({
+      component: "desired-state",
+      status: "failed",
+      path: statePaths().desiredState,
+      detail: message,
+    });
+    result.finalization.errors.push(message);
+  }
+  return nextDesired;
+}
+
+async function preparePurgeStateFinalization() {
+  const paths = statePaths();
+  if (!(await entryExists(paths.directory))) return { directory: paths.directory, tombstones: [] };
+  const directoryInfo = await lstat(paths.directory);
+  if (!directoryInfo.isDirectory() || directoryInfo.isSymbolicLink()) {
+    fail(`refusing to finalize an unsafe OpenSocrates state directory: ${paths.directory}`);
+  }
+  const uuid = "[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}";
+  const stateTemporary = new RegExp(
+    `^\\.(?:desired-state|auto-update-receipt)\\.json\\.${uuid}\\.tmp$`,
+    "u",
+  );
+  const purgeTombstone = new RegExp(
+    `^\\.purge-finalize-${uuid}-(?:desired-state\\.json|auto-update-receipt\\.json|` +
+      `\\.(?:desired-state|auto-update-receipt)\\.json\\.${uuid}\\.tmp)$`,
+    "u",
+  );
+  const candidates = [paths.desiredState, paths.receipt];
+  const tombstones = [];
+  for (const name of await readdir(paths.directory)) {
+    if (stateTemporary.test(name)) {
+      candidates.push(join(paths.directory, name));
+    } else if (purgeTombstone.test(name)) {
+      tombstones.push({ original: null, tombstone: join(paths.directory, name) });
+    }
+  }
+  const renamed = [];
+  try {
+    for (const item of tombstones) {
+      await requireSafePathBelow(paths.directory, item.tombstone, "OpenSocrates prior purge tombstone");
+      const info = await lstat(item.tombstone);
+      if (!info.isFile() || info.isSymbolicLink()) {
+        fail(`refusing to remove an unsafe prior OpenSocrates purge tombstone: ${item.tombstone}`);
+      }
+    }
+    for (const target of candidates) {
+      if (!(await entryExists(target))) continue;
+      await requireSafePathBelow(paths.directory, target, "OpenSocrates state file");
+      const info = await lstat(target);
+      if (!info.isFile() || info.isSymbolicLink()) {
+        fail(`refusing to remove an unsafe OpenSocrates state file: ${target}`);
+      }
+      const tombstone = join(paths.directory, `.purge-finalize-${randomUUID()}-${basename(target)}`);
+      await rename(target, tombstone);
+      const item = { original: target, tombstone };
+      tombstones.push(item);
+      renamed.push(item);
+    }
+    return { directory: paths.directory, tombstones };
+  } catch (error) {
+    for (const item of [...renamed].reverse()) {
+      await recoveryStep("restore installer state after purge finalization failed", async () => {
+        if (await entryExists(item.tombstone)) await rename(item.tombstone, item.original);
+      });
+    }
+    throw error;
+  }
+}
+
+async function completePurgeStateFinalization(plan, result, options) {
+  try {
+    for (const item of plan.tombstones) {
+      if (!(await entryExists(item.tombstone))) continue;
+      await requireSafePathBelow(plan.directory, item.tombstone, "OpenSocrates purge tombstone");
+      const info = await lstat(item.tombstone);
+      if (!info.isFile() || info.isSymbolicLink()) {
+        fail(`refusing to remove an unsafe OpenSocrates purge tombstone: ${item.tombstone}`);
+      }
+      await rm(item.tombstone);
+    }
+    if (await entryExists(plan.directory)) await rmdir(plan.directory);
+    result.finalization.components.push({
+      component: "state-directory",
+      status: "removed",
+      path: plan.directory,
+    });
+    result.finalization.status = "complete";
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    result.finalization.components.push({
+      component: "state-directory",
+      status: "failed",
+      path: plan.directory,
+      detail: message,
+    });
+    result.finalization.errors.push(message);
+    result.finalization.status = "partial";
+    result.status = "partial";
+    console.error(`error: OpenSocrates state cleanup remains at: ${plan.directory}`);
+    console.error(
+      `error: retry command: opensocrates remove --host ${options.host} --purge` +
+        (options.resetTrust ? " --reset-trust" : ""),
+    );
+  }
+}
+
+async function runPurgeLocked(options) {
+  const hosts = options.host === ALL_HOST ? SUPPORTED_HOSTS : [options.host];
+  const result = createPurgeResult(hosts, { resetTrust: options.resetTrust });
+  const desired = await readDesiredState();
+  for (const hostResult of result.hosts) await purgeOneHost(hostResult, options);
+  const nextDesired = await updatePurgeDesiredState(options, desired, result);
+  const hostsComplete = result.hosts.every((item) => item.status === "complete");
+  const finalizationComplete = result.finalization.errors.length === 0;
+  result.status = hostsComplete && finalizationComplete ? "complete" : "partial";
+  let stateFinalization = null;
+  if (
+    result.status === "complete" &&
+    nextDesired.installedHosts.length === 0 &&
+    !nextDesired.autoUpdate.enabled
+  ) {
+    try {
+      stateFinalization = await preparePurgeStateFinalization();
+      result.finalization.status = "ready";
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      result.finalization.components.push({
+        component: "state-finalization",
+        status: "failed",
+        path: statePaths().directory,
+        detail: message,
+      });
+      result.finalization.errors.push(message);
+      result.finalization.status = "partial";
+      result.status = "partial";
+    }
+  } else {
+    result.finalization.status = result.status === "complete" ? "preserved" : "deferred";
+  }
+  return { result, stateFinalization };
+}
+
+function reportPurgeResult(result) {
+  for (const host of result.hosts) {
+    console.log(`${host.host}: purge ${host.status}; registration ${host.registration}.`);
+    if (
+      new Set(["unverified", "failed"]).has(host.registration) &&
+      typeof host.registrationDetail === "string"
+    ) {
+      console.error(`${host.host}: registration ${host.registration} (${host.registrationDetail})`);
+    }
+    for (const component of host.components) {
+      if (new Set(["pending", "failed"]).has(component.status)) {
+        console.error(
+          `${host.host}: ${component.component} ${component.status}` +
+            (component.path ? ` at ${component.path}` : "") +
+            (component.detail ? ` (${component.detail})` : ""),
+        );
+      }
+    }
+    if (host.extension.status === "preserved") {
+      console.log(
+        `${host.host}: host security trust was preserved; rerun purge with --reset-trust to reset only ` +
+          "the exact OpenSocrates hook approvals.",
+      );
+    } else if (host.extension.status === "reset") {
+      console.log(
+        `${host.host}: host security trust reset completed for ${host.extension.removedCount} exact ` +
+          "OpenSocrates hook entries.",
+      );
+    } else if (host.extension.status === "absent") {
+      console.log(`${host.host}: no exact OpenSocrates host security trust entries were present.`);
+    } else if (host.extension.status === "failed") {
+      console.error(
+        `${host.host}: host security trust reset failed; no successful trust mutation is claimed.`,
+      );
+      console.error(
+        `${host.host}: rerun the same purge with --reset-trust after resolving Codex config validation, ` +
+          "or back up the config and manually review only the seven exact OpenSocrates hook sections.",
+      );
+    }
+  }
+  for (const component of result.finalization.components) {
+    if (new Set(["pending", "failed"]).has(component.status)) {
+      console.error(
+        `finalization: ${component.component} ${component.status}` +
+          (component.path ? ` at ${component.path}` : "") +
+          (component.detail ? ` (${component.detail})` : ""),
+      );
+    }
+  }
+  if (result.status === "complete") {
+    console.log("OpenSocrates purge completed for registrations and provably owned payloads.");
+    console.log("User task, project, chat, plan, and history data was preserved.");
+  } else {
+    console.error("OpenSocrates purge is incomplete; no complete-uninstall success is claimed.");
+    console.error("Resolve the reported item, close active hosts if needed, and rerun the same purge command.");
+  }
+}
+
+async function runPurge(options) {
+  const outcome = await withOperationLock(() => runPurgeLocked(options));
+  if (outcome.stateFinalization !== null) {
+    await completePurgeStateFinalization(outcome.stateFinalization, outcome.result, options);
+  }
+  reportPurgeResult(outcome.result);
+  if (outcome.result.status !== "complete") {
+    fail("purge remains pending or failed for one or more components");
+  }
+  return outcome.result;
 }
 
 async function enableAutoUpdate(options) {
@@ -2897,7 +5127,7 @@ async function verifyPackages(options) {
   }
 }
 
-export async function main(argv = process.argv.slice(2)) {
+export async function main(argv = process.argv.slice(2), internalDependencies = {}) {
   const options = parseCli(argv);
   if (options.action === "help") {
     showHelp();
@@ -2915,9 +5145,18 @@ export async function main(argv = process.argv.slice(2)) {
     await showAutoUpdateStatus();
     return 0;
   }
+  if (options.action === "remove" && options.purge) {
+    await runPurge({
+      ...options,
+      trustResetHooks: internalDependencies.trustResetHooks ?? {},
+    });
+    return 0;
+  }
   return withOperationLock(async () => {
     if (options.action === "remove") {
-      await runRemove(options);
+      await runStandardRemove(options, {
+        beforeBackupDelete: internalDependencies.beforeRemovalBackupDelete ?? null,
+      });
       return 0;
     }
     if (options.action === "auto-update") {