trans-genderian-orchestra 0.2.0 → 0.2.1

package/README.md

@@ -134,6 +134,7 @@ Put options in the second element of the plugin tuple: `["trans-genderian-orches
 | `checkVersion` | Whether to do that gentle npm drift check on startup. | `true` |
 | `sessionReuse` | `{ enabled, maxContextTokens }` — continues prior delegation sessions via task_id when the stored session is under the token budget. | `true`, 100000 |
 | `termination` | `{ enabled }` — stops a delegated session after it declares STATUS: complete with its exit gate satisfied and then makes a residual tool call. | `true` |
+| `selfUpdate` | `{ enabled }` — refreshes TGO's own plugin cache slot when a newer version is on npm; activates on next restart. | `true` |
 | `watchdog` | `{ enabled, wallClockMs, idleMs, checkMs, stuckLoopTools, stuckLoopMs }` — aborts a delegated session that’s hung or gone silent and asks Bernstein to re-dispatch. stuck-loop = <3 distinct tool signatures across the last 20 tools within 5m (read-only seats no longer false-trip). | `true`, 30m, 15m, 10s, stuckLoopTools 20, stuckLoopMs 5m |
 
 The JSON schema is at `plugin/schema/tgo.config.schema.json`.
@@ -181,6 +182,12 @@ Autonomy is a mode, not the default. “Keep going” is opt-in and bounded —
 
 For the human-readable long form: `docs/ARCHITECTURE.md` (shape and hooks), `docs/ROSTER.md` (the five seats), `docs/CONCISION.md` (the house style), `docs/SETUP.md` (install and per-repo setup), `docs/CONTRIBUTING.md` (dev workflow), and `CHANGELOG.md` (release history). The canonical contracts stay under `docs/spec/`.
 
+## Troubleshooting
+
+### Updating TGO
+
+Normally automatic via self-update (activates on restart) — when npm has a newer version, TGO refreshes its own plugin cache slot in the background and the update activates on next restart. If a slot is ever stuck, manual refresh is `rm -rf ~/.cache/opencode/packages/trans-genderian-orchestra*` then restart — `opencode plugin --force -g` is a no-op for same-spec entries (upstream behavior).
+
 ## Developing on TGO
 
 ```bash

package/dist/server.js

@@ -14351,6 +14351,9 @@ var sessionReuseConfig = exports_external.object({
 var terminationConfig = exports_external.object({
   enabled: exports_external.boolean().default(true)
 });
+var selfUpdateConfig = exports_external.object({
+  enabled: exports_external.boolean().default(true)
+});
 var tgoConfigSchema = exports_external.object({
   preset: exports_external.enum(PRESET_NAMES).default("balanced"),
   presets: exports_external.object({
@@ -14373,7 +14376,8 @@ var tgoConfigSchema = exports_external.object({
     stuckLoopMs: 5 * 60 * 1000
   })),
   sessionReuse: sessionReuseConfig.optional().default(() => ({ enabled: true, maxContextTokens: 1e5 })),
-  termination: terminationConfig.optional().default(() => ({ enabled: true }))
+  termination: terminationConfig.optional().default(() => ({ enabled: true })),
+  selfUpdate: selfUpdateConfig.optional().default(() => ({ enabled: true }))
 });
 function estimateTokens(text) {
   const normalized = text.replace(/\s+/g, " ").trim();
@@ -16801,9 +16805,344 @@ function parseCompletionSignal(text) {
 var and = (...cs) => (i) => cs.every((c) => c(i));
 var terminationDecision = and((i) => i.signal.complete, (i) => !i.exitGateRequired || i.signal.exitGate === true, (i) => i.toolCallsAfterCompletion >= 1);
 
-// src/plugin.ts
+// src/self-update.ts
+import * as fs8 from "node:fs/promises";
+import * as fsSync from "node:fs";
 import * as path9 from "node:path";
 import * as os2 from "node:os";
+var LOCK_STALE_MS = 120000;
+var LOCK_FILE = ".tgo-selfupdate.lock";
+function resolveCacheRoot(homeDir) {
+  const base = process.env.OPENCODE_TEST_HOME ?? process.env.XDG_CACHE_HOME ?? path9.join(homeDir ?? os2.homedir(), ".cache");
+  return path9.join(base, "opencode");
+}
+function slotDirs(cacheRoot, pkgName) {
+  const candidates = [
+    path9.join(cacheRoot, "packages", `${pkgName}@latest`),
+    path9.join(cacheRoot, "packages", pkgName)
+  ];
+  return candidates.filter((dir) => {
+    try {
+      return fsSync.existsSync(dir) && fsSync.statSync(dir).isDirectory();
+    } catch {
+      return false;
+    }
+  });
+}
+function parseSemver(v) {
+  if (typeof v !== "string")
+    return null;
+  let s = v.trim().replace(/^v/, "");
+  if (s.length === 0)
+    return null;
+  const plusIdx = s.indexOf("+");
+  if (plusIdx !== -1) {
+    const build = s.slice(plusIdx + 1);
+    if (build.length === 0)
+      return null;
+    const buildIds = build.split(".");
+    for (const id of buildIds) {
+      if (id.length === 0 || !/^[0-9A-Za-z-]+$/.test(id))
+        return null;
+    }
+    s = s.slice(0, plusIdx);
+  }
+  let coreStr;
+  let preStr = null;
+  const dashIdx = s.indexOf("-");
+  if (dashIdx !== -1) {
+    coreStr = s.slice(0, dashIdx);
+    preStr = s.slice(dashIdx + 1);
+    if (preStr.length === 0)
+      return null;
+  } else {
+    coreStr = s;
+  }
+  const coreParts = coreStr.split(".");
+  if (coreParts.length !== 3)
+    return null;
+  const nums = [];
+  for (const p of coreParts) {
+    if (!/^(0|[1-9]\d*)$/.test(p))
+      return null;
+    nums.push(parseInt(p, 10));
+  }
+  let prerelease = null;
+  if (preStr !== null) {
+    const ids = preStr.split(".");
+    for (const id of ids) {
+      if (id.length === 0 || !/^[0-9A-Za-z-]+$/.test(id))
+        return null;
+      if (/^[0-9]+$/.test(id) && !/^(0|[1-9]\d*)$/.test(id))
+        return null;
+    }
+    prerelease = ids;
+  }
+  return { major: nums[0], minor: nums[1], patch: nums[2], prerelease };
+}
+function semverGt(a, b) {
+  const pa = parseSemver(a);
+  const pb = parseSemver(b);
+  if (!pa || !pb)
+    return false;
+  if (pa.major !== pb.major)
+    return pa.major > pb.major;
+  if (pa.minor !== pb.minor)
+    return pa.minor > pb.minor;
+  if (pa.patch !== pb.patch)
+    return pa.patch > pb.patch;
+  const aPre = pa.prerelease;
+  const bPre = pb.prerelease;
+  if (aPre === null && bPre === null)
+    return false;
+  if (aPre === null && bPre !== null)
+    return true;
+  if (aPre !== null && bPre === null)
+    return false;
+  const aA = aPre;
+  const bA = bPre;
+  const len = Math.min(aA.length, bA.length);
+  for (let i = 0;i < len; i++) {
+    const aId = aA[i];
+    const bId = bA[i];
+    if (aId === bId)
+      continue;
+    const aIsNum = /^[0-9]+$/.test(aId);
+    const bIsNum = /^[0-9]+$/.test(bId);
+    if (aIsNum && bIsNum) {
+      return parseInt(aId, 10) > parseInt(bId, 10);
+    }
+    if (aIsNum && !bIsNum)
+      return false;
+    if (!aIsNum && bIsNum)
+      return true;
+    return aId > bId;
+  }
+  return aA.length > bA.length;
+}
+function shouldRefresh(runningVersion, latestVersion) {
+  return semverGt(latestVersion, runningVersion);
+}
+function buildInstallArgs(dir, pkgName) {
+  return ["npm", "install", "--prefix", dir, `${pkgName}@latest`, "--save-exact", "--ignore-scripts", "--no-audit", "--no-fund"];
+}
+async function recoverOrphans(dir) {
+  try {
+    const dirExists = await fs8.stat(dir).then(() => true).catch(() => false);
+    const backup = `${dir}.tgo-backup`;
+    const staging = `${dir}.tgo-staging`;
+    if (!dirExists) {
+      const backupExists = await fs8.stat(backup).then(() => true).catch(() => false);
+      if (backupExists) {
+        try {
+          await fs8.rename(backup, dir);
+        } catch {}
+      }
+      return;
+    }
+    await rmRf(staging);
+    await rmRf(backup);
+  } catch {}
+}
+async function rmRf(p) {
+  try {
+    await fs8.rm(p, { recursive: true, force: true });
+  } catch {}
+}
+async function copyDir(src, dest) {
+  const cp2 = fs8.cp;
+  if (typeof cp2 === "function") {
+    await cp2.call(fs8, src, dest, { recursive: true, force: true });
+    return;
+  }
+  await fs8.mkdir(dest, { recursive: true });
+  const entries = await fs8.readdir(src, { withFileTypes: true });
+  for (const e of entries) {
+    const s = path9.join(src, e.name);
+    const d = path9.join(dest, e.name);
+    if (e.isDirectory()) {
+      await copyDir(s, d);
+    } else if (e.isSymbolicLink()) {
+      const target = await fs8.readlink(s);
+      await fs8.symlink(target, d);
+    } else {
+      await fs8.copyFile(s, d);
+    }
+  }
+}
+async function selfUpdate(deps) {
+  try {
+    let latest;
+    try {
+      latest = await deps.fetchLatest();
+    } catch {
+      return;
+    }
+    if (!latest)
+      return;
+    if (typeof latest !== "string" || latest.trim().length === 0)
+      return;
+    if (!shouldRefresh(deps.runningVersion, latest))
+      return;
+    const cacheRoot = resolveCacheRoot(deps.homeDir);
+    const dirs = slotDirs(cacheRoot, deps.pkgName);
+    if (dirs.length === 0)
+      return;
+    const nowMs = deps.now ? deps.now().getTime() : Date.now();
+    for (const dir of dirs) {
+      try {
+        await recoverOrphans(dir);
+      } catch {}
+      const lockPath = path9.join(dir, LOCK_FILE);
+      const staging = `${dir}.tgo-staging`;
+      const backup = `${dir}.tgo-backup`;
+      let ownerToken = null;
+      let acquired = false;
+      try {
+        try {
+          await fs8.mkdir(dir, { recursive: true });
+        } catch {}
+        const token = `${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2)}`;
+        const tryAcquire = async () => {
+          let handle;
+          try {
+            handle = await fs8.open(lockPath, "wx");
+            try {
+              await handle.writeFile(token, "utf-8");
+            } catch {}
+            ownerToken = token;
+            acquired = true;
+            return true;
+          } catch (err) {
+            const code = err?.code;
+            if (code !== "EEXIST")
+              return false;
+            return false;
+          } finally {
+            if (handle) {
+              try {
+                await handle.close();
+              } catch {}
+            }
+          }
+        };
+        let ok = await tryAcquire();
+        if (!ok) {
+          try {
+            const stat3 = await fs8.stat(lockPath);
+            const age = nowMs - stat3.mtimeMs;
+            if (age > LOCK_STALE_MS) {
+              try {
+                await fs8.unlink(lockPath);
+              } catch {}
+              ok = await tryAcquire();
+              if (!ok)
+                continue;
+            } else {
+              continue;
+            }
+          } catch {
+            continue;
+          }
+        }
+        if (!acquired || !ownerToken)
+          continue;
+        let innerError = null;
+        let newVersionForLog = null;
+        try {
+          try {
+            await rmRf(staging);
+            await copyDir(dir, staging);
+          } catch (e) {
+            throw new Error(`self-update staging failed for ${dir}: ${String(e)}`);
+          }
+          const args = buildInstallArgs(staging, deps.pkgName);
+          let result;
+          try {
+            result = await deps.spawn(args);
+          } catch (e) {
+            throw new Error(`self-update spawn failed for ${dir}: ${String(e)}`);
+          }
+          if (result.exitCode !== 0) {
+            throw new Error(`self-update failed for ${dir}: exit ${result.exitCode} ${result.stderr || result.stdout}`.trim());
+          }
+          let newVersion = "";
+          try {
+            const pkgJsonPath = path9.join(staging, "node_modules", deps.pkgName, "package.json");
+            const raw = await fs8.readFile(pkgJsonPath, "utf-8");
+            const json2 = JSON.parse(raw);
+            newVersion = typeof json2.version === "string" ? json2.version : "";
+          } catch (e) {
+            throw new Error(`self-update verification failed for ${dir}: ${String(e)}`);
+          }
+          if (!newVersion) {
+            throw new Error(`self-update verification failed for ${dir}: missing version`);
+          }
+          if (!semverGt(newVersion, deps.runningVersion)) {
+            throw new Error(`self-update verification failed for ${dir}: installed ${newVersion} not > ${deps.runningVersion}`);
+          }
+          newVersionForLog = newVersion;
+          try {
+            await rmRf(backup);
+            await fs8.rename(dir, backup);
+            await fs8.rename(staging, dir);
+            await rmRf(backup);
+          } catch (e) {
+            try {
+              const backupExists = await fs8.stat(backup).then(() => true).catch(() => false);
+              const dirExists = await fs8.stat(dir).then(() => true).catch(() => false);
+              if (backupExists && !dirExists) {
+                try {
+                  await fs8.rename(backup, dir);
+                } catch {}
+              }
+              await rmRf(staging);
+            } catch {}
+            throw new Error(`self-update swap failed for ${dir}: ${String(e)}`);
+          }
+          try {
+            deps.log("info", `self-updated ${deps.pkgName} to ${newVersionForLog} — restart opencode to activate`);
+          } catch {}
+        } catch (e) {
+          innerError = e;
+          try {
+            const backupExists = await fs8.stat(backup).then(() => true).catch(() => false);
+            const dirExists = await fs8.stat(dir).then(() => true).catch(() => false);
+            if (backupExists && !dirExists) {
+              try {
+                await fs8.rename(backup, dir);
+              } catch {}
+            }
+            await rmRf(staging);
+          } catch {}
+          try {
+            const msg = String(e?.message ?? e);
+            if (msg.includes("self-update")) {
+              deps.log("warn", msg);
+            } else {
+              deps.log("warn", `self-update failed for ${dir}: ${String(e)}`);
+            }
+          } catch {}
+        }
+      } finally {
+        try {
+          if (ownerToken) {
+            const cur = await fs8.readFile(lockPath, "utf-8").catch(() => "");
+            if (cur === ownerToken) {
+              await fs8.unlink(lockPath).catch(() => {});
+            }
+          }
+        } catch {}
+      }
+    }
+  } catch {
+    return;
+  }
+}
+
+// src/plugin.ts
+import * as path10 from "node:path";
+import * as os3 from "node:os";
 var TgoPlugin = async ({ client, $, project, directory, worktree }, options) => {
   const config2 = await loadTgoConfig(options);
   const appLog = (level, message, extra) => {
@@ -16820,7 +17159,37 @@ var TgoPlugin = async ({ client, $, project, directory, worktree }, options) =>
       }
     }).catch(() => {});
   }
-  const seatDir = config2.agentDir ?? path9.join(os2.homedir(), ".config", "opencode", "agent");
+  if (config2.selfUpdate?.enabled !== false) {
+    (async () => {
+      try {
+        const runningVersion = await readLocalVersion() ?? "0.0.0";
+        await selfUpdate({
+          runningVersion,
+          pkgName: PLUGIN_NPM_NAME,
+          fetchLatest: () => fetchLatestVersion().then((v) => v ?? undefined),
+          spawn: async (args) => {
+            try {
+              const proc = Bun.spawn(args, {
+                stdout: "pipe",
+                stderr: "pipe",
+                env: BD_ENV
+              });
+              const [stdout, stderr, exitCode] = await Promise.all([
+                new Response(proc.stdout).text(),
+                new Response(proc.stderr).text(),
+                proc.exited
+              ]);
+              return { exitCode, stdout, stderr };
+            } catch (error51) {
+              return { exitCode: 1, stdout: "", stderr: String(error51) };
+            }
+          },
+          log: (level, msg) => appLog(level, msg)
+        });
+      } catch {}
+    })().catch(() => {});
+  }
+  const seatDir = config2.agentDir ?? path10.join(os3.homedir(), ".config", "opencode", "agent");
   try {
     const checked = await validateAgentDir(seatDir);
     if (checked > 0) {
@@ -16899,7 +17268,7 @@ var TgoPlugin = async ({ client, $, project, directory, worktree }, options) =>
       try {
         const args = command.split(/\s+/);
         const proc = cwd ? $`${args}`.cwd(cwd) : $`${args}`;
-        const completed = await proc.env({ ...process.env, BD_NON_INTERACTIVE: "1", HOME: os2.homedir() }).nothrow();
+        const completed = await proc.env({ ...process.env, BD_NON_INTERACTIVE: "1", HOME: os3.homedir() }).nothrow();
         return {
           exitCode: completed.exitCode,
           stdout: completed.stdout.toString(),
@@ -17032,7 +17401,7 @@ var TgoPlugin = async ({ client, $, project, directory, worktree }, options) =>
       const nextPermission = preapproveExternalDirectory(input.permission, worktreeRoot);
       if (nextPermission && Object.keys(nextPermission).length > 0) {
         input.permission = nextPermission;
-        const parent = worktreeRoot ? path9.dirname(worktreeRoot) : undefined;
+        const parent = worktreeRoot ? path10.dirname(worktreeRoot) : undefined;
         appLog("info", `pre-approved external_directory for worktree family ${parent}/*`, {
           worktreeRoot,
           projectWorktree: project?.worktree ?? null,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trans-genderian-orchestra",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "TGO — a thin multi-agent orchestration plugin for OpenCode",
   "license": "MIT",
   "repository": "https://github.com/octini/trans-genderian-orchestra",

package/schema/tgo.config.schema.json

@@ -145,6 +145,17 @@
       },
       "additionalProperties": false
     },
+    "selfUpdate": {
+      "description": "Self-update settings.",
+      "type": "object",
+      "properties": {
+        "enabled": {
+          "type": "boolean",
+          "default": true
+        }
+      },
+      "additionalProperties": false
+    },
     "presets": {
       "description": "Partial override of the built-in seat→model map. Missing presets fall back to built-ins. Model IDs are free-form strings.",
       "type": "object",

package/src/config.ts

@@ -75,6 +75,10 @@ const terminationConfig = z.object({
   enabled: z.boolean().default(true),
 });
 
+const selfUpdateConfig = z.object({
+  enabled: z.boolean().default(true),
+});
+
 export const tgoConfigSchema = z.object({
   preset: z.enum(PRESET_NAMES).default("balanced"),
   presets: z
@@ -100,6 +104,7 @@ export const tgoConfigSchema = z.object({
   })),
   sessionReuse: sessionReuseConfig.optional().default(() => ({ enabled: true, maxContextTokens: 100000 })),
   termination: terminationConfig.optional().default(() => ({ enabled: true })),
+  selfUpdate: selfUpdateConfig.optional().default(() => ({ enabled: true })),
 });
 
 export type TgoConfig = z.infer<typeof tgoConfigSchema>;

package/src/plugin.ts

@@ -15,8 +15,9 @@ import { validateDelegationBoundary, validateDelegationPacket, verifyClaimObserv
 import { captureDelegationSession, probeSessionReuseCapability, persistAbortHandback } from "./session-reuse";
 import { authorizeLifecycleSession, evaluateClosure, verifyClaimObserved } from "./lifecycle";
 import { loadBeadsTui, renderBeadsTui } from "./tui";
-import { checkVersionDrift } from "./version";
+import { checkVersionDrift, fetchLatestVersion, PLUGIN_NPM_NAME, readLocalVersion } from "./version";
 import { parseCompletionSignal, terminationDecision, type CompletionSignal } from "./termination";
+import { selfUpdate } from "./self-update";
 // No runtime function re-exports here: opencode's legacy plugin loader calls
 // EVERY exported function as a plugin factory (input, options), so an entry
 // re-export like evaluateClosure gets invoked as one and throws inside the
@@ -63,6 +64,37 @@ export const TgoPlugin: Plugin = async (
       .catch(() => {});
   }
 
+  if (config.selfUpdate?.enabled !== false) {
+    void (async () => {
+      try {
+        const runningVersion = (await readLocalVersion()) ?? "0.0.0";
+        await selfUpdate({
+          runningVersion,
+          pkgName: PLUGIN_NPM_NAME,
+          fetchLatest: () => fetchLatestVersion().then((v) => v ?? undefined),
+          spawn: async (args: string[]) => {
+            try {
+              const proc = Bun.spawn(args, {
+                stdout: "pipe",
+                stderr: "pipe",
+                env: BD_ENV as unknown as Record<string, string>,
+              });
+              const [stdout, stderr, exitCode] = await Promise.all([
+                new Response(proc.stdout).text(),
+                new Response(proc.stderr).text(),
+                proc.exited,
+              ]);
+              return { exitCode, stdout, stderr };
+            } catch (error) {
+              return { exitCode: 1, stdout: "", stderr: String(error) };
+            }
+          },
+          log: (level, msg) => appLog(level, msg),
+        });
+      } catch {}
+    })().catch(() => {});
+  }
+
   const seatDir =
     config.agentDir ?? path.join(os.homedir(), ".config", "opencode", "agent");
   // Load-time budget re-check. Warn, never throw: a throwing factory makes

package/src/self-update.ts

@@ -0,0 +1,359 @@
+import * as fs from "node:fs/promises";
+import * as fsSync from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+
+export const LOCK_STALE_MS = 120_000;
+export const LOCK_FILE = ".tgo-selfupdate.lock";
+
+export function resolveCacheRoot(homeDir?: string): string {
+  const base =
+    process.env.OPENCODE_TEST_HOME ??
+    process.env.XDG_CACHE_HOME ??
+    path.join(homeDir ?? os.homedir(), ".cache");
+  return path.join(base, "opencode");
+}
+
+export function slotDirs(cacheRoot: string, pkgName: string): string[] {
+  const candidates = [
+    path.join(cacheRoot, "packages", `${pkgName}@latest`),
+    path.join(cacheRoot, "packages", pkgName),
+  ];
+  return candidates.filter((dir) => {
+    try {
+      return fsSync.existsSync(dir) && fsSync.statSync(dir).isDirectory();
+    } catch {
+      return false;
+    }
+  });
+}
+
+function parseSemver(v: string): { major: number; minor: number; patch: number; prerelease: string[] | null } | null {
+  if (typeof v !== "string") return null;
+  let s = v.trim().replace(/^v/, "");
+  if (s.length === 0) return null;
+  // strip build metadata
+  const plusIdx = s.indexOf("+");
+  if (plusIdx !== -1) {
+    const build = s.slice(plusIdx + 1);
+    if (build.length === 0) return null;
+    const buildIds = build.split(".");
+    for (const id of buildIds) {
+      if (id.length === 0 || !/^[0-9A-Za-z-]+$/.test(id)) return null;
+    }
+    s = s.slice(0, plusIdx);
+  }
+  let coreStr: string;
+  let preStr: string | null = null;
+  const dashIdx = s.indexOf("-");
+  if (dashIdx !== -1) {
+    coreStr = s.slice(0, dashIdx);
+    preStr = s.slice(dashIdx + 1);
+    if (preStr.length === 0) return null;
+  } else {
+    coreStr = s;
+  }
+  const coreParts = coreStr.split(".");
+  if (coreParts.length !== 3) return null;
+  const nums: number[] = [];
+  for (const p of coreParts) {
+    if (!/^(0|[1-9]\d*)$/.test(p)) return null;
+    nums.push(parseInt(p, 10));
+  }
+  let prerelease: string[] | null = null;
+  if (preStr !== null) {
+    const ids = preStr.split(".");
+    for (const id of ids) {
+      if (id.length === 0 || !/^[0-9A-Za-z-]+$/.test(id)) return null;
+      if (/^[0-9]+$/.test(id) && !/^(0|[1-9]\d*)$/.test(id)) return null;
+    }
+    prerelease = ids;
+  }
+  return { major: nums[0]!, minor: nums[1]!, patch: nums[2]!, prerelease };
+}
+
+export function semverGt(a: string, b: string): boolean {
+  const pa = parseSemver(a);
+  const pb = parseSemver(b);
+  if (!pa || !pb) return false;
+  if (pa.major !== pb.major) return pa.major > pb.major;
+  if (pa.minor !== pb.minor) return pa.minor > pb.minor;
+  if (pa.patch !== pb.patch) return pa.patch > pb.patch;
+  const aPre = pa.prerelease;
+  const bPre = pb.prerelease;
+  if (aPre === null && bPre === null) return false;
+  if (aPre === null && bPre !== null) return true;
+  if (aPre !== null && bPre === null) return false;
+  // both have prerelease
+  const aA = aPre!;
+  const bA = bPre!;
+  const len = Math.min(aA.length, bA.length);
+  for (let i = 0; i < len; i++) {
+    const aId = aA[i]!;
+    const bId = bA[i]!;
+    if (aId === bId) continue;
+    const aIsNum = /^[0-9]+$/.test(aId);
+    const bIsNum = /^[0-9]+$/.test(bId);
+    if (aIsNum && bIsNum) {
+      return parseInt(aId, 10) > parseInt(bId, 10);
+    }
+    if (aIsNum && !bIsNum) return false;
+    if (!aIsNum && bIsNum) return true;
+    // both alphanumeric lexical (ASCII)
+    return aId > bId;
+  }
+  return aA.length > bA.length;
+}
+
+export function shouldRefresh(runningVersion: string, latestVersion: string): boolean {
+  return semverGt(latestVersion, runningVersion);
+}
+
+export function buildInstallArgs(dir: string, pkgName: string): string[] {
+  return ["npm", "install", "--prefix", dir, `${pkgName}@latest`, "--save-exact", "--ignore-scripts", "--no-audit", "--no-fund"];
+}
+
+// deprecated compat: keep for old callers/tests
+export function buildInstallCommand(dir: string, pkgName: string): string {
+  return buildInstallArgs(dir, pkgName).join(" ");
+}
+
+export async function recoverOrphans(dir: string): Promise<void> {
+  try {
+    const dirExists = await fs.stat(dir).then(() => true).catch(() => false);
+    const backup = `${dir}.tgo-backup`;
+    const staging = `${dir}.tgo-staging`;
+    if (!dirExists) {
+      const backupExists = await fs.stat(backup).then(() => true).catch(() => false);
+      if (backupExists) {
+        try {
+          await fs.rename(backup, dir);
+        } catch {}
+      }
+      return;
+    }
+    await rmRf(staging);
+    await rmRf(backup);
+  } catch {}
+}
+
+async function rmRf(p: string): Promise<void> {
+  try {
+    await fs.rm(p, { recursive: true, force: true });
+  } catch {}
+}
+
+async function copyDir(src: string, dest: string): Promise<void> {
+  // prefer fs.cp if available
+  const cp = (fs as unknown as { cp?: (s: string, d: string, opts: unknown) => Promise<void> }).cp;
+  if (typeof cp === "function") {
+    await cp.call(fs, src, dest, { recursive: true, force: true });
+    return;
+  }
+  await fs.mkdir(dest, { recursive: true });
+  const entries = await fs.readdir(src, { withFileTypes: true });
+  for (const e of entries) {
+    const s = path.join(src, e.name);
+    const d = path.join(dest, e.name);
+    if (e.isDirectory()) {
+      await copyDir(s, d);
+    } else if (e.isSymbolicLink()) {
+      const target = await fs.readlink(s);
+      await fs.symlink(target, d);
+    } else {
+      await fs.copyFile(s, d);
+    }
+  }
+}
+
+export async function selfUpdate(deps: {
+  runningVersion: string;
+  pkgName: string;
+  fetchLatest: () => Promise<string | undefined>;
+  spawn: (args: string[]) => Promise<{ exitCode: number; stdout: string; stderr: string }>;
+  log: (level: "info" | "warn", msg: string) => void;
+  homeDir?: string;
+  now?: () => Date;
+}): Promise<void> {
+  try {
+    let latest: string | undefined | null;
+    try {
+      latest = await deps.fetchLatest();
+    } catch {
+      return;
+    }
+    if (!latest) return;
+    if (typeof latest !== "string" || latest.trim().length === 0) return;
+    if (!shouldRefresh(deps.runningVersion, latest)) return;
+
+    const cacheRoot = resolveCacheRoot(deps.homeDir);
+    const dirs = slotDirs(cacheRoot, deps.pkgName);
+    if (dirs.length === 0) return;
+
+    const nowMs = deps.now ? deps.now().getTime() : Date.now();
+
+    for (const dir of dirs) {
+      try {
+        await recoverOrphans(dir);
+      } catch {}
+      const lockPath = path.join(dir, LOCK_FILE);
+      const staging = `${dir}.tgo-staging`;
+      const backup = `${dir}.tgo-backup`;
+      let ownerToken: string | null = null;
+      let acquired = false;
+
+      try {
+        try {
+          await fs.mkdir(dir, { recursive: true });
+        } catch {}
+        const token = `${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2)}`;
+
+        const tryAcquire = async (): Promise<boolean> => {
+          let handle: fs.FileHandle | undefined;
+          try {
+            handle = await fs.open(lockPath, "wx");
+            try {
+              await handle.writeFile(token, "utf-8");
+            } catch {}
+            ownerToken = token;
+            acquired = true;
+            return true;
+          } catch (err) {
+            const code = (err as NodeJS.ErrnoException)?.code;
+            if (code !== "EEXIST") return false;
+            return false;
+          } finally {
+            if (handle) {
+              try {
+                await handle.close();
+              } catch {}
+            }
+          }
+        };
+
+        let ok = await tryAcquire();
+        if (!ok) {
+          try {
+            const stat = await fs.stat(lockPath);
+            const age = nowMs - stat.mtimeMs;
+            if (age > LOCK_STALE_MS) {
+              try {
+                await fs.unlink(lockPath);
+              } catch {}
+              ok = await tryAcquire();
+              if (!ok) continue;
+            } else {
+              continue;
+            }
+          } catch {
+            continue;
+          }
+        }
+        if (!acquired || !ownerToken) continue;
+
+        let innerError: unknown = null;
+        let newVersionForLog: string | null = null;
+
+        try {
+          // (b) staging copy
+          try {
+            await rmRf(staging);
+            await copyDir(dir, staging);
+          } catch (e) {
+            throw new Error(`self-update staging failed for ${dir}: ${String(e)}`);
+          }
+
+          // (c) npm install with --prefix staging
+          const args = buildInstallArgs(staging, deps.pkgName);
+          let result: { exitCode: number; stdout: string; stderr: string };
+          try {
+            result = await deps.spawn(args);
+          } catch (e) {
+            throw new Error(`self-update spawn failed for ${dir}: ${String(e)}`);
+          }
+          if (result.exitCode !== 0) {
+            throw new Error(`self-update failed for ${dir}: exit ${result.exitCode} ${result.stderr || result.stdout}`.trim());
+          }
+
+          // (d) verify staging version gt running
+          let newVersion = "";
+          try {
+            const pkgJsonPath = path.join(staging, "node_modules", deps.pkgName, "package.json");
+            const raw = await fs.readFile(pkgJsonPath, "utf-8");
+            const json = JSON.parse(raw) as { version?: unknown };
+            newVersion = typeof json.version === "string" ? json.version : "";
+          } catch (e) {
+            throw new Error(`self-update verification failed for ${dir}: ${String(e)}`);
+          }
+          if (!newVersion) {
+            throw new Error(`self-update verification failed for ${dir}: missing version`);
+          }
+          if (!semverGt(newVersion, deps.runningVersion)) {
+            throw new Error(`self-update verification failed for ${dir}: installed ${newVersion} not > ${deps.runningVersion}`);
+          }
+          newVersionForLog = newVersion;
+
+          // (e) swap
+          try {
+            await rmRf(backup);
+            await fs.rename(dir, backup);
+            await fs.rename(staging, dir);
+            await rmRf(backup);
+          } catch (e) {
+            // swap failure: try to restore backup if dir missing
+            try {
+              const backupExists = await fs.stat(backup).then(() => true).catch(() => false);
+              const dirExists = await fs.stat(dir).then(() => true).catch(() => false);
+              if (backupExists && !dirExists) {
+                try {
+                  await fs.rename(backup, dir);
+                } catch {}
+              }
+              await rmRf(staging);
+            } catch {}
+            throw new Error(`self-update swap failed for ${dir}: ${String(e)}`);
+          }
+
+          // success log
+          try {
+            deps.log("info", `self-updated ${deps.pkgName} to ${newVersionForLog} — restart opencode to activate`);
+          } catch {}
+        } catch (e) {
+          innerError = e;
+          // (f) ANY failure → rm staging, restore backup if needed, log warn, original untouched
+          try {
+            const backupExists = await fs.stat(backup).then(() => true).catch(() => false);
+            const dirExists = await fs.stat(dir).then(() => true).catch(() => false);
+            if (backupExists && !dirExists) {
+              try {
+                await fs.rename(backup, dir);
+              } catch {}
+            }
+            await rmRf(staging);
+          } catch {}
+          try {
+            const msg = String((e as Error)?.message ?? e);
+            // ensure warn contains needed substrings; if message already contains warn-like text, log it directly
+            if (msg.includes("self-update")) {
+              deps.log("warn", msg);
+            } else {
+              deps.log("warn", `self-update failed for ${dir}: ${String(e)}`);
+            }
+          } catch {}
+        }
+        // lock release handled in finally below
+      } finally {
+        try {
+          if (ownerToken) {
+            const cur = await fs.readFile(lockPath, "utf-8").catch(() => "");
+            if (cur === ownerToken) {
+              await fs.unlink(lockPath).catch(() => {});
+            }
+          }
+        } catch {}
+      }
+    }
+  } catch {
+    return;
+  }
+}