carthagent 1.0.7 → 1.1.0-preview.13

package/lib/opencode/runtime.mjs

@@ -1,13 +1,47 @@
-import { chmod, mkdir, open, readFile, rename, rm, stat } from 'node:fs/promises';
-import { randomUUID } from 'node:crypto';
-import { homedir } from 'node:os';
+import { chmod, lstat, mkdir, open, opendir, readFile, realpath, rename, rm, stat, unlink } from 'node:fs/promises';
+import { constants, readFileSync } from 'node:fs';
+import { createHash, randomUUID } from 'node:crypto';
+import { createRequire } from 'node:module';
+import { arch, homedir, platform } from 'node:os';
 import { fileURLToPath } from 'node:url';
 import path from 'node:path';
 import { spawn } from 'node:child_process';
+import { acquireOwnedRuntime } from './runtime-artifact.mjs';
+import { createRuntimeGithubFetch } from './runtime-github-transport.mjs';
 
 export const OPENCODE_VERSION = '2.0.32';
+export const CTG_RUNTIME_VERSION = '0.0.0-ctg.2.0.32';
+export const CTG_RUNTIME_SOURCE = '843a6c514e606b436a7fe713422ace0a93ad3d61';
+export const CTG_RUNTIME_LOCK_SHA256 = '9d78379cd264584a495440a217b9d2ecab524c9a56f7f8b4b5bed3926daa330d';
+export const CTG_RUNTIME_PATCH_SHA256 = 'ec4bb182308ed8b311513aad5c9c7d57dcd0db103f0882f3dc3517d535b4c975';
+// Update only this development pin after reviewing a new checked-in patch and
+// script/ctg/prepare-development-runtime.sh. The published release pin above,
+// its build recipe, and the release manifest stay immutable until a separately
+// verified runtime release is promoted.
+export const CTG_DEVELOPMENT_RUNTIME_PATCH_SHA256 = 'ec4bb182308ed8b311513aad5c9c7d57dcd0db103f0882f3dc3517d535b4c975';
 const DEFAULT_ROOT = path.join(homedir(), '.carthagent', 'opencode');
+const require = createRequire(import.meta.url);
 const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
+const RUNTIME_RELEASE_MANIFEST = path.join(PACKAGE_ROOT, 'lib', 'opencode', 'runtime-release.json');
+// Tracks the verified cache selected by the packaged release path without
+// turning it into the separate, explicitly trusted staging selector.
+const RESOLVED_OWNED_RUNTIME = Symbol('resolvedOwnedRuntime');
+
+export function resolvePathCommand(command, env = process.env, hostPlatform = platform()) {
+  const entries = (env.PATH ?? env.Path ?? '').split(path.delimiter).filter(Boolean);
+  const extensions = hostPlatform === 'win32' && !path.extname(command)
+    ? (env.PATHEXT ?? '.COM;.EXE;.BAT;.CMD').split(';')
+    : [''];
+  for (const entry of entries) {
+    for (const extension of extensions) {
+      const candidate = path.resolve(entry, `${command}${extension}`);
+      try {
+        const details = require('node:fs').statSync(candidate);
+        if (details.isFile() && (hostPlatform === 'win32' || (details.mode & 0o111) !== 0)) return candidate;
+      } catch {}
+    }
+  }
+}
 
 function abs(value) { return path.resolve(value); }
 
@@ -34,31 +68,202 @@ export function runtimePaths(options = {}) {
 
 /** Find a CTG/OpenCode executable without downloading or replacing user binaries. */
 export async function resolveOpenCode(options = {}) {
+  const owned = options.ownedRuntime ?? process.env.CTG_OWNED_OPENCODE_RUNTIME;
   const explicit = options.binary ?? process.env.CTG_OPENCODE_BIN;
-  const packaged = path.join(PACKAGE_ROOT, 'node_modules', '@opencode', 'cli', 'bin', 'opencode.exe');
+  if (!explicit && owned) return resolveOwnedOpenCode(owned, options);
+  if (!explicit) {
+    const release = await readRuntimeReleaseManifest(options.runtimeReleaseManifestPath ?? RUNTIME_RELEASE_MANIFEST);
+    if (release) {
+      const key = `${platform() === 'win32' ? 'windows' : platform()}-${arch()}`;
+      const asset = release.assets[key];
+      if (!asset) throw new Error(`This CTG release does not provide its owned Carthagent runtime for ${key}; no upstream or system fallback was attempted.`);
+      const root = await (options.acquireOwnedRuntime ?? acquireOwnedRuntime)({
+        releaseVersion: release.releaseVersion,
+        platform: platform() === 'win32' ? 'windows' : platform(),
+        arch: arch(),
+        assetName: asset.name,
+        expectedArchiveSha256: asset.archiveSha256,
+        expectedExecutableSha256: asset.executableSha256,
+        expectedSourceRevision: release.sourceRevision,
+        expectedPatchSha256: release.patchSha256,
+        expectedLockSha256: release.lockSha256,
+        expectedCompatibilityVersion: release.compatibilityVersion,
+        expectedRuntimeVersion: release.runtimeVersion,
+        expectedChannel: `ctg.${release.compatibilityVersion}`,
+        baseUrl: options.runtimeReleaseBaseUrl ?? `https://github.com/B-icy/Carthagent/releases/download/v${release.releaseVersion}`,
+        cacheRoot: options.runtimeCacheRoot,
+        fetchImpl: process.env.CTG_RUNTIME_GITHUB_TOKEN
+          ? createRuntimeGithubFetch({ token: process.env.CTG_RUNTIME_GITHUB_TOKEN, fetchImpl: options.fetchImpl ?? globalThis.fetch })
+          : options.fetchImpl,
+        signal: options.signal,
+      });
+      // Automatic acquisition never opts into development provenance, even
+      // when a caller supplies an acquisition implementation or cached root.
+      const binary = await resolvePinnedOwnedOpenCode(root, options, false, asset.executableSha256);
+      // Preserve the selection for runtimeIdentity(), but do not put it in
+      // ownedRuntime: that is an explicit developer/staging trust selector.
+      // Repeated resolution must pass through acquisition again so its pinned
+      // executable digest is rechecked even if the cache and SHA256SUMS changed.
+      Object.defineProperty(options, RESOLVED_OWNED_RUNTIME, {
+        configurable: true,
+        value: root,
+      });
+      return binary;
+    }
+  }
+  let packaged;
+  if (!explicit) {
+    try {
+      const packageJson = require.resolve('@opencode/cli/package.json');
+      const metadata = JSON.parse(await readFile(packageJson, 'utf8'));
+      const executable = typeof metadata.bin === 'string'
+        ? metadata.bin
+        : metadata.bin?.opencode;
+      if (typeof executable !== 'string') throw new Error('package has no opencode binary entry');
+      packaged = path.resolve(path.dirname(packageJson), executable);
+    } catch (error) {
+      throw new Error(`Packaged Carthagent runtime ${OPENCODE_VERSION} dependency could not be resolved from CTG: ${error.message}`);
+    }
+  }
   const candidates = explicit ? [explicit] : [packaged];
   for (const candidate of candidates) {
     if (candidate.includes(path.sep) || candidate.includes('/')) {
       try {
-        const result = await runCapture(candidate, ['--version'], { timeout: 5000, spawnImpl: options.spawnImpl });
+        const result = options.spawnImpl
+          ? await runCapture(candidate, ['--version'], { timeout: 5000, spawnImpl: options.spawnImpl })
+          : await runCapture(candidate, ['--version'], { timeout: 5000 });
         const version = result.stdout.trim().match(/(?:opencode\s+)?v?(\d+\.\d+\.\d+)/i)?.[1];
-        if (version !== OPENCODE_VERSION) throw new Error(`OpenCode ${OPENCODE_VERSION} is required; found ${version ?? 'unknown'} at ${candidate}`);
+        if (version !== OPENCODE_VERSION) throw new Error(`Carthagent runtime ${OPENCODE_VERSION} is required; found ${version ?? 'unknown'} at ${candidate}`);
         return abs(candidate);
       } catch (error) {
         if (explicit || /is required/.test(error.message)) throw error;
       }
-    } else {
+      } else {
       try {
-        const result = await runCapture(candidate, ['--version'], { timeout: 5000, spawnImpl: options.spawnImpl });
+        const result = await runCapture(candidate, ['--version'], { timeout: 5000, spawnImpl: options.spawnImpl, env: options.env });
         const version = result.stdout.trim().match(/(?:opencode\s+)?v?(\d+\.\d+\.\d+)/i)?.[1];
-        if (version !== OPENCODE_VERSION) throw new Error(`OpenCode ${OPENCODE_VERSION} is required; found ${version ?? 'unknown'} on PATH`);
-        return candidate;
+        if (version !== OPENCODE_VERSION) throw new Error(`Carthagent runtime ${OPENCODE_VERSION} is required; found ${version ?? 'unknown'} on PATH`);
+        const resolved = resolvePathCommand(candidate, options.env ?? process.env);
+        if (!resolved) throw new Error(`${candidate} was not found on PATH`);
+        return await realpath(resolved);
       } catch (error) {
         if (explicit || /is required/.test(error.message)) throw error;
       }
     }
   }
-  throw new Error(`Packaged OpenCode ${OPENCODE_VERSION} was not found at ${packaged}. Reinstall CTG or set CTG_OPENCODE_BIN explicitly; CTG will not use or replace another OpenCode installation.`);
+  throw new Error(`Packaged Carthagent runtime ${OPENCODE_VERSION} was not found at ${packaged}. Reinstall CTG or set CTG_OPENCODE_BIN explicitly; CTG will not use or replace another Carthagent runtime installation.`);
+}
+
+/** Read and strictly validate the package-pinned release trust root. */
+export async function readRuntimeReleaseManifest(file = RUNTIME_RELEASE_MANIFEST) {
+  let manifest;
+  try { manifest = JSON.parse(await readFile(file, 'utf8')); }
+  catch (error) {
+    if (error.code === 'ENOENT') return undefined;
+    throw new Error(`Invalid CTG Carthagent runtime release manifest at ${file}: ${error.message}`);
+  }
+  const invalid = () => { throw new Error(`Invalid or incompatible CTG Carthagent runtime release manifest at ${file}`); };
+  let packageMetadata;
+  try { packageMetadata = JSON.parse(await readFile(path.join(PACKAGE_ROOT, 'package.json'), 'utf8')); }
+  catch (error) { throw new Error(`Could not verify CTG package version for runtime release manifest: ${error.message}`); }
+  if (!manifest || manifest.version !== 1
+    || !isReleaseVersion(manifest.releaseVersion)
+    || manifest.releaseVersion !== packageMetadata.version
+    || manifest.compatibilityVersion !== OPENCODE_VERSION
+    || manifest.runtimeVersion !== CTG_RUNTIME_VERSION
+    || manifest.sourceRevision !== CTG_RUNTIME_SOURCE
+    || manifest.patchSha256 !== CTG_RUNTIME_PATCH_SHA256
+    || manifest.lockSha256 !== CTG_RUNTIME_LOCK_SHA256
+    || !manifest.assets || typeof manifest.assets !== 'object' || Array.isArray(manifest.assets)) invalid();
+  const allowed = new Set(['linux-x64', 'linux-arm64', 'darwin-x64', 'darwin-arm64', 'windows-x64']);
+  for (const [key, asset] of Object.entries(manifest.assets)) {
+    if (!allowed.has(key) || !asset || typeof asset !== 'object'
+      || asset.name !== `opencode-${key}.tar.gz`
+      || !isSha256(asset.archiveSha256) || !isSha256(asset.executableSha256)) invalid();
+  }
+  for (const key of allowed) if (!manifest.assets[key]) invalid();
+  if (Object.keys(manifest.assets).length !== allowed.size) invalid();
+  return manifest;
+}
+
+function isReleaseVersion(value) {
+  return typeof value === 'string' && /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/.test(value);
+}
+function isSha256(value) { return typeof value === 'string' && /^[a-f0-9]{64}$/.test(value); }
+
+/** Explicit developer/staging selector: accept release or checked-in development provenance. */
+export async function resolveOwnedOpenCode(directory, options = {}) {
+  return resolvePinnedOwnedOpenCode(directory, options, true);
+}
+
+// The trust choice is internal, not an option or adjacent-manifest override.
+async function resolvePinnedOwnedOpenCode(directory, options, allowDevelopment, expectedExecutableSha256) {
+  const root = abs(directory);
+  const manifestPath = path.join(root, 'ctg-runtime.json');
+  let manifest;
+  try { manifest = JSON.parse(await readFile(manifestPath, 'utf8')); }
+  catch (error) { throw new Error(`Invalid CTG-owned Carthagent runtime manifest at ${manifestPath}: ${error.message}`); }
+  if (!manifest || manifest.owner !== 'Carthagent'
+    || manifest.sourceRepository !== 'https://github.com/anomalyco/opencode'
+    || manifest.sourceRevision !== CTG_RUNTIME_SOURCE
+    || manifest.lockSha256 !== CTG_RUNTIME_LOCK_SHA256
+    || (manifest.patchSha256 !== CTG_RUNTIME_PATCH_SHA256
+      && !(allowDevelopment && manifest.patchSha256 === CTG_DEVELOPMENT_RUNTIME_PATCH_SHA256))
+    || manifest.compatibilityVersion !== OPENCODE_VERSION
+    || manifest.runtimeVersion !== CTG_RUNTIME_VERSION
+    || manifest.channel !== 'ctg.2.0.32'
+    || manifest.webUI !== false) {
+    throw new Error(`CTG-owned Carthagent runtime manifest is not compatible with the pinned CTG ${OPENCODE_VERSION} runtime at ${manifestPath}`);
+  }
+  const platformName = platform() === 'win32' ? 'windows' : platform();
+  const supportedPlatform = `${platformName}-${arch()}`;
+  if (manifest.platform !== supportedPlatform) {
+    throw new Error(`CTG-owned Carthagent runtime platform ${manifest.platform} does not match this host ${supportedPlatform}`);
+  }
+  const artifactPlatform = manifest.platform;
+  const executable = path.join(root, `cli-${artifactPlatform}`, 'bin', platform() === 'win32' ? 'opencode.exe' : 'opencode');
+  const checksumFile = path.join(root, 'SHA256SUMS');
+  const relativeExecutable = path.relative(root, executable).split(path.sep).join('/');
+  let sums;
+  try { sums = await readFile(checksumFile, 'utf8'); }
+  catch (error) { throw new Error(`CTG-owned Carthagent runtime checksums are missing at ${checksumFile}: ${error.message}`); }
+  const expected = sums.split(/\r?\n/).map(line => line.trim().split(/\s+/)).find(([hash, name]) => /^[a-f0-9]{64}$/i.test(hash || '') && name?.replace(/^\*?/, '') === relativeExecutable)?.[0];
+  if (!expected) throw new Error(`CTG-owned Carthagent runtime checksum does not list ${relativeExecutable}`);
+  let bytes;
+  try { bytes = await readFile(executable); }
+  catch (error) { throw new Error(`CTG-owned Carthagent runtime executable is missing at ${executable}: ${error.message}`); }
+  const actual = createHash('sha256').update(bytes).digest('hex');
+  if (actual !== expected.toLowerCase()) throw new Error(`CTG-owned Carthagent runtime executable SHA-256 mismatch at ${executable}`);
+  if (expectedExecutableSha256 !== undefined && actual !== expectedExecutableSha256) {
+    throw new Error(`CTG-owned Carthagent runtime pinned executable SHA-256 mismatch at ${executable}`);
+  }
+  const result = await runCapture(executable, ['--version'], { timeout: 5000, spawnImpl: options.spawnImpl });
+  if (result.stdout.trim() !== `opencode v${CTG_RUNTIME_VERSION}`) {
+    throw new Error(`CTG-owned Carthagent runtime identity mismatch at ${executable}: ${result.stdout.trim() || 'unknown version'}`);
+  }
+  return executable;
+}
+
+/** Describe the executable identity that a profile's persistent server must match. */
+export async function runtimeIdentity(binary, options = {}) {
+  const executable = await realpath(binary.includes(path.sep) || binary.includes('/') ? binary : resolvePathCommand(binary, options.env ?? process.env) ?? binary);
+  const digest = createHash('sha256').update(await readFile(executable)).digest('hex');
+  const ownedDirectory = options.ownedRuntime ?? process.env.CTG_OWNED_OPENCODE_RUNTIME ?? options[RESOLVED_OWNED_RUNTIME];
+  if (!ownedDirectory || options.binary || process.env.CTG_OPENCODE_BIN) {
+    return Object.freeze({ kind: 'upstream-compatible', binaryPath: executable, binarySha256: digest, version: OPENCODE_VERSION });
+  }
+  const manifest = JSON.parse(await readFile(path.join(abs(ownedDirectory), 'ctg-runtime.json'), 'utf8'));
+  const artifactPlatform = manifest.platform;
+  const ownedPath = await realpath(path.join(abs(ownedDirectory), `cli-${artifactPlatform}`, 'bin', platform() === 'win32' ? 'opencode.exe' : 'opencode'));
+  if (ownedPath !== executable) {
+    throw new Error(`CTG-owned runtime selector resolved ${executable}, but the selected artifact manifest binds ${ownedPath}`);
+  }
+  return Object.freeze({
+    kind: 'ctg-owned', binaryPath: executable, binarySha256: digest,
+    version: manifest.runtimeVersion, sourceRevision: manifest.sourceRevision,
+    lockSha256: manifest.lockSha256, patchSha256: manifest.patchSha256,
+    platform: manifest.platform, capabilities: { shellOrigin: true },
+  });
 }
 
 /** Construct the environment for CTG-owned OpenCode children. */
@@ -68,7 +273,10 @@ export function runtimeEnvironment(options = {}) {
   // overrides. Workspace child environments are restored through the native
   // session.environment API, not through this host process environment.
   const inherited = { ...process.env, ...(options.env ?? {}) };
-  const env = Object.fromEntries(Object.entries(inherited).filter(([key]) => !key.startsWith('OPENCODE_')));
+  for (const key of Object.keys(inherited)) {
+    if (key.toUpperCase() === 'CTG_RUNTIME_GITHUB_TOKEN') delete inherited[key];
+  }
+  const env = Object.fromEntries(Object.entries(inherited).filter(([key]) => !key.startsWith('OPENCODE_') && key !== 'CTG_NATIVE_GLYPHS' && key !== 'CTG_TUI_GLYPHS'));
   Object.assign(env, {
     XDG_CONFIG_HOME: paths.config,
     XDG_DATA_HOME: paths.data,
@@ -82,10 +290,9 @@ export function runtimeEnvironment(options = {}) {
     OPENCODE_DB: path.join(paths.data, 'opencode.db'),
     OPENCODE_CONFIG: paths.configFile,
     OPENCODE_CONFIG_DIR: paths.configDir,
-    OPENCODE_CONFIG_PROJECT_DISABLE: 'true',
+    ...(options.isolate ? { OPENCODE_CONFIG_PROJECT_DISABLE: 'true' } : {}),
     OPENCODE_DISABLE_MODELS_FETCH: 'true',
-    OPENCODE_DISABLE_CLAUDE_CODE: 'true',
-    OPENCODE_DISABLE_CLAUDE_CODE_SKILLS: 'true',
+    ...(options.isolate ? { OPENCODE_DISABLE_CLAUDE_CODE: 'true', OPENCODE_DISABLE_CLAUDE_CODE_SKILLS: 'true' } : {}),
     OPENCODE_DISABLE_AUTOUPDATE: 'true',
     CTG_OPENCODE_HOME: paths.root,
   });
@@ -105,18 +312,74 @@ export async function provisionRuntime(options = {}) {
       current = JSON.parse(await readFile(paths.configFile, 'utf8'));
       if (!current || typeof current !== 'object' || Array.isArray(current)) throw new Error('expected a JSON object');
     } catch (error) {
-      if (error.code !== 'ENOENT') throw new Error(`Cannot preserve CTG OpenCode profile at ${paths.configFile}: ${error.message}`);
+      if (error.code !== 'ENOENT') throw new Error(`Cannot preserve CTG Carthagent runtime profile at ${paths.configFile}: ${error.message}`);
     }
     const config = { ...current, ...(options.profile ?? {}), $schema: current.$schema ?? 'https://opencode.ai/config.json' };
     if (options.pluginPath) {
       const plugin = abs(options.pluginPath);
-      config.plugins = [...new Set([...(Array.isArray(config.plugins) ? config.plugins : []), plugin])];
+      config.plugins = replaceManagedPlugin(config.plugins, plugin);
     }
     await atomicWrite(paths.configFile, `${JSON.stringify(config, null, 2)}\n`, 0o600);
   });
   return paths;
 }
 
+/** Old checkout/install references share one plugin ID, even when paths differ.
+ * Recognize the managed layout without requiring obsolete paths to still exist.
+ * Leave unrelated plugins (including their options and ordering) untouched. */
+function replaceManagedPlugin(plugins, plugin) {
+  const entries = Array.isArray(plugins) ? plugins : [];
+  const managed = entry => {
+    let reference = typeof entry === 'string' ? entry : entry?.package;
+    if (typeof reference !== 'string') return false;
+    if (reference.startsWith('file:')) {
+      try { reference = fileURLToPath(reference); } catch { return false; }
+    }
+    if (abs(reference) === plugin) return true;
+    return /(?:^|\/)plugins\/carthagent(?:\/(?:src\/)?index\.ts)?$/.test(reference.replaceAll('\\', '/').replace(/\/+$/, ''));
+  };
+  const previous = entries.filter(managed);
+  // Prefer the selected installation's options, otherwise retain the latest
+  // managed entry's options when moving between installations.
+  const selected = previous.find(entry => typeof entry === 'object' && entry?.package === plugin)
+    ?? previous.findLast(entry => entry && typeof entry === 'object')
+    ?? previous.at(-1);
+  const replacement = selected && typeof selected === 'object' ? { ...selected, package: plugin } : plugin;
+  const result = [];
+  let replaced = false;
+  for (const entry of entries) {
+    if (!managed(entry)) result.push(entry);
+    else if (!replaced) { result.push(replacement); replaced = true; }
+  }
+  if (!replaced) result.push(replacement);
+  return result;
+}
+
+/** Remove only this file's atomicWrite staging entries without reading payloads.
+ * The caller must hold the same exclusive lock as every writer to this file;
+ * otherwise a staging entry could belong to a live write.
+ */
+export async function cleanupAtomicWriteStaging(file) {
+  const directoryPath = path.dirname(file), prefix = `${path.basename(file)}.`;
+  const suffix = /^[1-9][0-9]*\.[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}\.tmp$/i;
+  // Windows cannot open directories as file handles; lstat still rejects a
+  // final-component symlink there. POSIX also persists the directory unlink.
+  const directory = process.platform === 'win32' ? undefined
+    : await open(directoryPath, constants.O_RDONLY | (constants.O_DIRECTORY ?? 0) | (constants.O_NOFOLLOW ?? 0));
+  try {
+    if (!(directory ? await directory.stat() : await lstat(directoryPath)).isDirectory()) throw new Error('Invalid atomicWrite staging directory');
+    // Stream entries rather than loading an unbounded directory listing.
+    let removed = false;
+    for await (const entry of await opendir(directoryPath)) {
+      if (!entry.name.startsWith(prefix) || !suffix.test(entry.name.slice(prefix.length))
+        || (!entry.isFile() && !entry.isSymbolicLink())) continue;
+      // unlink does not follow symlinks and never recursively deletes paths.
+      await unlink(path.join(directoryPath, entry.name)); removed = true;
+    }
+    if (removed) await directory?.sync();
+  } finally { await directory?.close(); }
+}
+
 export async function atomicWrite(file, contents, mode = 0o600) {
   await mkdir(path.dirname(file), { recursive: true, mode: 0o700 });
   const temporary = `${file}.${process.pid}.${randomUUID()}.tmp`;
@@ -210,15 +473,27 @@ function lockTimeoutError(file, owner) {
 }
 
 export function processAlive(pid) {
-  try { process.kill(pid, 0); return true; }
+  try { process.kill(pid, 0); }
   catch (error) { return error.code === 'EPERM'; }
+  if (process.platform === 'linux') {
+    try {
+      // kill(pid, 0) also succeeds for exited children awaiting reaping by PID 1.
+      const status = readFileSync(`/proc/${pid}/stat`, 'utf8');
+      return !['Z', 'X', 'x'].includes(status.slice(status.lastIndexOf(')') + 2).split(' ')[0]);
+    } catch (error) { if (error.code === 'ENOENT') return false; }
+  }
+  return true;
 }
 
 /** Run a child process with bounded startup and captured diagnostic output. */
 export function runCapture(command, args, options = {}) {
   return new Promise((resolve, reject) => {
     const spawnImpl = options.spawnImpl ?? spawn;
-    const child = spawnImpl(command, args, { cwd: options.cwd, env: options.env ?? process.env, stdio: ['ignore', 'pipe', 'pipe'] });
+    const env = { ...(options.env ?? process.env) };
+    for (const key of Object.keys(env)) {
+      if (key.toUpperCase() === 'CTG_RUNTIME_GITHUB_TOKEN') delete env[key];
+    }
+    const child = spawnImpl(command, args, { cwd: options.cwd, env, stdio: ['ignore', 'pipe', 'pipe'] });
     let stdout = '';
     let stderr = '';
     const cap = options.maxOutput ?? 256 * 1024;
@@ -236,7 +511,11 @@ export function runCapture(command, args, options = {}) {
 
 /** Preserve workspace authentication/environment: do not apply CTG host XDG overrides. */
 export function workspaceEnvironment(workspace, env = process.env) {
-  return { ...env, CTG_WORKSPACE: abs(workspace) };
+  const child = { ...env, CTG_WORKSPACE: abs(workspace) };
+  for (const key of Object.keys(child)) {
+    if (key.toUpperCase() === 'CTG_RUNTIME_GITHUB_TOKEN') delete child[key];
+  }
+  return child;
 }
 
 export async function readRuntimeCredentials(options = {}) {

package/lib/opencode/service.mjs

@@ -1,7 +1,9 @@
 import { readFile, rm } from 'node:fs/promises';
 import { spawn } from 'node:child_process';
 import { randomBytes } from 'node:crypto';
-import { OPENCODE_VERSION, processAlive, provisionRuntime, resolveOpenCode, runtimeEnvironment, runtimePaths, withFileLock, atomicWrite, workspaceEnvironment } from './runtime.mjs';
+import { processAlive, provisionRuntime, resolveOpenCode, runtimeEnvironment, runtimeIdentity, runtimePaths, withFileLock, atomicWrite, workspaceEnvironment } from './runtime.mjs';
+import { withoutRuntimeGithubToken } from '../environment.mjs';
+import { packageVersion } from '../update.mjs';
 
 function authHeaders(info) {
   if (!info.password) return {};
@@ -10,7 +12,7 @@ function authHeaders(info) {
 
 async function registration(file) {
   try { return JSON.parse(await readFile(file, 'utf8')); }
-  catch (error) { if (error.code === 'ENOENT') return undefined; throw new Error(`Cannot read isolated OpenCode service registration: ${error.message}`); }
+  catch (error) { if (error.code === 'ENOENT') return undefined; throw new Error(`Cannot read isolated Carthagent runtime service registration: ${error.message}`); }
 }
 
 async function inspect(info, timeout = 1000) {
@@ -19,7 +21,9 @@ async function inspect(info, timeout = 1000) {
     if (!response.ok) return undefined;
     const payload = await response.json();
     const body = payload.data ?? payload;
-    if (body.version !== OPENCODE_VERSION || (info.pid && body.pid !== info.pid)) return undefined;
+    if (body.version !== (info.runtimeIdentity?.version ?? info.version) || (info.pid && body.pid !== info.pid)) return undefined;
+    if (info.runtimeIdentity?.capabilities?.shellOrigin === true
+      && body.capabilities?.shellOrigin !== info.runtimeIdentity.capabilities.shellOrigin) return undefined;
     return { version: body.version, pid: body.pid, server: body, url: info.url };
   } catch { return undefined; }
 }
@@ -28,22 +32,46 @@ async function inspect(info, timeout = 1000) {
 export async function ensureService(options = {}) {
   const paths = await provisionRuntime(options);
   const binary = await resolveOpenCode(options);
+  const identity = await runtimeIdentity(binary, options);
   const env = runtimeEnvironment(options);
   return withFileLock(paths.lifecycleLock, async () => {
+    // Serialize profile provisioning with lifecycle startup so concurrent
+    // launchers cannot race while installing the same theme files.
+    const { provisionDefaultNativeTheme } = await import('../../plugins/carthagent/src/ui/theme-provision.mjs');
+    await provisionDefaultNativeTheme(paths.configDir);
     const info = await registration(paths.serviceFile);
     if (info) {
+      const sameIdentity = JSON.stringify(info.runtimeIdentity) === JSON.stringify(identity);
       const healthy = await inspect(info, options.healthTimeout ?? 1500);
-      if (healthy) return Object.freeze({ ...healthy, info, headers: authHeaders(info), paths, binary });
-      if (processAlive(info.pid)) {
-        throw new Error(`CTG OpenCode service process ${info.pid} is alive but unhealthy at ${info.url}; registration was retained to avoid orphaning or duplicating it.`);
+      const sameLauncher = info.launcherVersion === packageVersion();
+      const ownedUpgrade = healthy && info.runtimeIdentity?.kind === 'ctg-owned' && identity.kind === 'ctg-owned';
+      if (healthy && sameIdentity && (sameLauncher || !ownedUpgrade)) return Object.freeze({ ...healthy, info, headers: authHeaders(info), paths, binary, runtimeIdentity: identity });
+      if (ownedUpgrade) {
+        // The lifecycle lock stays held through shutdown and replacement.
+        await stopRegisteredService(paths, info, options);
+      } else if (processAlive(info.pid)) {
+        if (!sameIdentity) {
+          throw serviceIdentityMismatch(info, identity, paths);
+        }
+        throw new Error(`CTG Carthagent runtime service process ${info.pid} is alive but unhealthy at ${info.url}; registration was retained to avoid orphaning or duplicating it.`);
       }
       const current = await registration(paths.serviceFile);
       if (current?.id === info.id && current?.pid === info.pid) await rm(paths.serviceFile, { force: true });
     }
-    return startService({ paths, binary, env, options });
+    return startService({ paths, binary, env, options, identity });
   }, { timeout: options.lockTimeout ?? 20000 });
 }
 
+function serviceIdentityMismatch(info, expected, paths) {
+  return new Error(
+    `CTG Carthagent runtime service profile is already running runtime ${info.runtimeIdentity?.version ?? 'with unknown identity'} `
+    + `(${info.runtimeIdentity?.kind ?? 'legacy'}). This invocation selected ${expected.version} (${expected.kind}). `
+    + `The active service was left running; no process was stopped or replaced. `
+    + `After finishing active sessions, run ctg native service stop with CTG_OPENCODE_HOME=${JSON.stringify(paths.root)}, `
+    + `then relaunch. Sessions and credentials are preserved. Alternatively, choose a separate CTG_OPENCODE_HOME profile.`,
+  );
+}
+
 /** Stop only the process registered by this CTG profile; never signal a shared service. */
 export async function stopService(options = {}) {
   const paths = runtimePaths(options);
@@ -57,25 +85,31 @@ export async function stopService(options = {}) {
         if (current?.id === info.id && current?.pid === info.pid) await rm(paths.serviceFile, { force: true });
         return false;
       }
-      throw new Error(`Refusing to stop CTG OpenCode PID ${info.pid}: the registered process is alive but its service identity cannot be verified. Registration was retained.`);
-    }
-    const current = await registration(paths.serviceFile);
-    if (current?.id !== info.id || current?.pid !== info.pid || current?.url !== info.url) return false;
-    try { process.kill(info.pid, 'SIGTERM'); } catch (error) { if (error.code !== 'ESRCH') throw error; }
-    const deadline = Date.now() + (options.stopTimeout ?? 5000);
-    while (Date.now() < deadline) {
-      if (!processAlive(info.pid)) {
-        const latest = await registration(paths.serviceFile);
-        if (latest?.id === info.id && latest?.pid === info.pid) await rm(paths.serviceFile, { force: true });
-        return true;
-      }
-      await new Promise((resolve) => setTimeout(resolve, 50));
+      throw new Error(`Refusing to stop CTG Carthagent runtime PID ${info.pid}: the registered process is alive but its service identity cannot be verified. Registration was retained.`);
     }
-    throw new Error(`CTG OpenCode service process ${info.pid} did not stop within ${options.stopTimeout ?? 5000}ms`);
+    return stopRegisteredService(paths, info, options);
   }, { timeout: options.lockTimeout ?? 20000 });
 }
 
-async function startService({ paths, binary, env: baseEnv, options }) {
+async function stopRegisteredService(paths, info, options) {
+  const current = await registration(paths.serviceFile);
+  if (current?.id !== info.id || current?.pid !== info.pid || current?.url !== info.url) {
+    throw new Error('CTG runtime service registration changed before shutdown; no process was stopped.');
+  }
+  try { process.kill(info.pid, 'SIGTERM'); } catch (error) { if (error.code !== 'ESRCH') throw error; }
+  const deadline = Date.now() + (options.stopTimeout ?? 5000);
+  while (Date.now() < deadline) {
+    if (!processAlive(info.pid)) {
+      const latest = await registration(paths.serviceFile);
+      if (latest?.id === info.id && latest?.pid === info.pid) await rm(paths.serviceFile, { force: true });
+      return true;
+    }
+    await new Promise((resolve) => setTimeout(resolve, 50));
+  }
+  throw new Error(`CTG Carthagent runtime service process ${info.pid} did not stop within ${options.stopTimeout ?? 5000}ms`);
+}
+
+async function startService({ paths, binary, env: baseEnv, options, identity }) {
   const deadline = Date.now() + (options.startupTimeout ?? 20000);
   const password = randomBytes(32).toString('base64url');
   const env = { ...baseEnv, OPENCODE_SERVER_PASSWORD: password };
@@ -99,10 +133,10 @@ async function startService({ paths, binary, env: baseEnv, options }) {
     child.stderr.on('data', collect);
     child.once('error', (error) => { startupFailure = error; if (!settled) { settled = true; clearTimeout(startupTimer); reject(error); } });
     child.once('exit', (code, signal) => {
-      if (!settled) { settled = true; clearTimeout(startupTimer); reject(new Error(`OpenCode exited ${code ?? signal} before listening: ${output.replaceAll(password, '[redacted]')}`)); }
+      if (!settled) { settled = true; clearTimeout(startupTimer); reject(new Error(`Carthagent runtime exited ${code ?? signal} before listening: ${output.replaceAll(password, '[redacted]')}`)); }
     });
     startupTimer = setTimeout(() => {
-      if (!settled) { settled = true; reject(new Error(`OpenCode startup timed out after ${options.startupTimeout ?? 20000}ms`)); }
+      if (!settled) { settled = true; reject(new Error(`Carthagent runtime startup timed out after ${options.startupTimeout ?? 20000}ms`)); }
     }, Math.max(1, deadline - Date.now()));
     child.unref();
   });
@@ -112,17 +146,18 @@ async function startService({ paths, binary, env: baseEnv, options }) {
         id: `ctg-${child.pid}-${randomBytes(8).toString('hex')}`,
         pid: child.pid,
         state: 'starting',
-        version: OPENCODE_VERSION,
+        version: identity.version,
+        runtimeIdentity: identity,
       })}\n`);
     }
     const url = await started;
     child.stdout.unref?.();
     child.stderr.unref?.();
-    const info = { id: `ctg-${child.pid}-${randomBytes(8).toString('hex')}`, pid: child.pid, url, password, version: OPENCODE_VERSION };
+    const info = { id: `ctg-${child.pid}-${randomBytes(8).toString('hex')}`, pid: child.pid, url, password, version: identity.version, runtimeIdentity: identity, launcherVersion: packageVersion() };
     await atomicWrite(paths.serviceFile, `${JSON.stringify(info)}\n`);
     const healthy = await inspect(info, Math.max(250, deadline - Date.now()));
-    if (!healthy) throw new Error('OpenCode listener started but authenticated service identity did not validate');
-    return Object.freeze({ ...healthy, info, headers: authHeaders(info), paths, binary });
+    if (!healthy) throw new Error('Carthagent runtime listener started but authenticated service identity did not validate');
+    return Object.freeze({ ...healthy, info, headers: authHeaders(info), paths, binary, runtimeIdentity: identity });
   } catch (error) {
     let stopped = !child?.pid || !processAlive(child.pid);
     if (child?.pid && processAlive(child.pid)) {
@@ -137,9 +172,9 @@ async function startService({ paths, binary, env: baseEnv, options }) {
     const registered = await registration(paths.serviceFile).catch(() => undefined);
     if (stopped && registered?.pid === child?.pid) await rm(paths.serviceFile, { force: true });
     if (!stopped) {
-      throw new Error(`CTG OpenCode startup failed and process ${child.pid} could not be stopped; ownership registration was retained at ${paths.serviceFile}.`, { cause: error });
+      throw new Error(`CTG Carthagent runtime startup failed and process ${child.pid} could not be stopped; ownership registration was retained at ${paths.serviceFile}.`, { cause: error });
     }
-    throw new Error(`Unable to start CTG OpenCode service: ${startupFailure?.message ?? error.message}${output ? `\n${output.replaceAll(password, '[redacted]')}` : ''}`, { cause: error });
+    throw new Error(`Unable to start CTG Carthagent runtime service: ${startupFailure?.message ?? error.message}${output ? `\n${output.replaceAll(password, '[redacted]')}` : ''}`, { cause: error });
   }
 }
 
@@ -165,7 +200,7 @@ export async function serviceRequest(service, method, endpoint, options = {}) {
   let data;
   try { data = text ? JSON.parse(text) : undefined; } catch { data = text; }
   if (!response.ok) {
-    const error = new Error(`OpenCode API ${method} ${url.pathname} failed (${response.status}): ${typeof data === 'string' ? data : JSON.stringify(data)}`);
+    const error = new Error(`Carthagent runtime API ${method} ${url.pathname} failed (${response.status}): ${typeof data === 'string' ? data : JSON.stringify(data)}`);
     error.status = response.status;
     error.body = data;
     throw error;
@@ -226,7 +261,7 @@ export async function setSessionEnvironment(service, sessionID, env, options = {
 
 function normalizeDirectory(location) {
   const directory = typeof location === 'string' ? location : location?.directory;
-  if (typeof directory !== 'string' || !directory) throw new TypeError('OpenCode location must include a directory');
+  if (typeof directory !== 'string' || !directory) throw new TypeError('Carthagent runtime location must include a directory');
   return directory;
 }
 
@@ -234,13 +269,20 @@ export function launchTui(service, workspace, options = {}) {
   const args = ['--server', service.url, workspace];
   if (options.sessionID) args.push('--session', options.sessionID);
   if (options.continue) args.push('--continue');
+  const env = { ...runtimeEnvironment({ root: service.paths.root, env: options.env }) };
+  if (typeof options.theme === 'string' && options.theme.trim()) env.OPENCODE_CLI_CONFIG_CONTENT = JSON.stringify({ theme: { name: options.theme.trim(), mode: 'system' } });
+  const glyphs = options.glyphs ?? options.env?.CTG_TUI_GLYPHS;
+  if (glyphs === 'ascii' || glyphs === 'unicode') env.CTG_TUI_GLYPHS = glyphs;
+  for (const key of Object.keys(env)) {
+    if (key.toUpperCase() === 'CTG_RUNTIME_GITHUB_TOKEN') delete env[key];
+  }
   const child = (options.spawnImpl ?? spawn)(service.binary, args, {
     cwd: workspace,
-    env: {
-      ...runtimeEnvironment({ root: service.paths.root, env: options.env }),
+    env: withoutRuntimeGithubToken({
+      ...env,
       OPENCODE_PASSWORD: service.info?.password ?? service.password,
       CTG_WORKSPACE: workspaceEnvironment(workspace, options.env ?? process.env).CTG_WORKSPACE,
-    },
+    }),
     stdio: 'inherit',
   });
   return child;

package/lib/opencode/session-options.mjs

@@ -2,8 +2,8 @@ import { resolve } from 'node:path';
 import { validateBudgetOptions } from '../budget.mjs';
 
 export const SESSION_OPTIONS_KEY = 'carthagent.options';
-const booleans = ['delivery', 'guide', 'strict', 'isolate', 'protectExisting'];
-const integers = ['maxTools', 'maxSeconds', 'maxRepairs', 'codegraphMaxFiles', 'rewriteCap', 'toolOutputCap'];
+const booleans = ['delivery', 'guide', 'strict', 'isolate', 'protectExisting', 'jev'];
+const integers = ['maxTools', 'maxSeconds', 'maxRepairs', 'codegraphMaxFiles', 'rewriteCap', 'toolOutputCap', 'turnDelayMs'];
 const paths = ['validators', 'context'];
 
 /** Only delivery runtime settings belong here; credentials and UI choices do not. */
@@ -23,6 +23,10 @@ export function normalizeSessionOptions(input = {}, cwd = process.cwd()) {
     }
     result[key] = Number(input[key]);
   }
+  if (input.jevProvider !== undefined) {
+    if (!['ship', 'openrouter', 'typesafe'].includes(input.jevProvider)) throw new TypeError('jevProvider must be ship, openrouter or typesafe');
+    result.jevProvider = input.jevProvider;
+  }
   if (input.bashCap !== undefined) {
     const cap = Number(input.bashCap);
     if (!Number.isFinite(cap) || cap <= 0 || !/^\d+(?:\.\d+)?$/.test(String(input.bashCap))) throw new TypeError('bashCap must be a positive number');