carthagent 0.0.0-stage → 1.0.7

package/lib/engine.mjs

@@ -0,0 +1,137 @@
+/**
+ * Locating the agent CLI + building its argument list — shared by the console
+ * (bin/ctg.mjs, lib/tui/app.mjs) and the evaluation runner (evaluate.mjs).
+ * carthagent uses a baked-in agent engine in vendor/agent and an isolated state directory
+ * (~/.carthagent/agent) to ensure it runs completely fresh without piggybacking on any
+ * host engine installation.
+ */
+import { existsSync, readdirSync, statSync, openSync, fstatSync, readSync, closeSync } from 'node:fs';
+import { join, dirname, resolve, basename } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import os from 'node:os';
+import { validateBudgetOptions } from './budget.mjs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ROOT = resolve(__dirname, '..');
+
+// Ensure an isolated state directory (~/.carthagent/agent) by default:
+const DEFAULT_AGENT_DIR = process.env.CARTHAGENT_AGENT_DIR || process.env.CARTHAGENT_CODING_AGENT_DIR || join(os.homedir(), '.carthagent', 'agent');
+if (!process.env.CARTHAGENT_CODING_AGENT_DIR && !process.env.CARTHAGENT_AGENT_DIR) {
+  process.env.CARTHAGENT_CODING_AGENT_DIR = DEFAULT_AGENT_DIR;
+}
+if (!process.env.PI_CODING_AGENT_DIR) {
+  process.env.PI_CODING_AGENT_DIR = process.env.CARTHAGENT_CODING_AGENT_DIR || DEFAULT_AGENT_DIR;
+}
+
+export function locateEngine(explicit) {
+  const candidates = [explicit, process.env.CARTHAGENT_CLI, process.env.PI_CLI].filter(Boolean);
+  for (const c of candidates) {
+    if (existsSync(c)) return { cmd: process.execPath, args: [c] };
+  }
+
+  // Self-contained baked-in agent engine inside the package.
+  const baked = join(ROOT, 'vendor', 'agent', 'cli.js');
+  if (existsSync(baked)) return { cmd: process.execPath, args: [baked] };
+
+  throw new Error('Cannot find the baked-in agent engine in vendor/agent/cli.js — pass --agent-cli /path/to/cli.js');
+}
+
+/** Build engine CLI args for both the TUI (rpc) and headless (-p) paths. */
+export function buildEngineArgs(opts) {
+  validateBudgetOptions(opts);
+  const args = [];
+  if (opts.json) args.push('--mode', 'json');
+  if (opts.provider) args.push('--provider', opts.provider);
+  if (opts.model) args.push('--model', opts.model);
+  if (opts.thinking) args.push('--thinking', opts.thinking);
+  // Session selection: --session <path|id> or --continue for the most recent.
+  // (--resume is intentionally not forwarded — agent picker is interactive.)
+  if (opts.session) args.push('--session', opts.session);
+  else if (opts.continue) args.push('--continue');
+  if (opts.isolate) args.push('--no-extensions', '--no-skills', '--no-prompt-templates');
+  // Product providers load independently of the delivery extension so they are
+  // available in the TUI, RPC child, headless runs, and --no-delivery mode.
+  args.push('-e', join(ROOT, 'extensions', 'experiential.ts'));
+  args.push('-e', join(ROOT, 'extensions', 'subscriptions.ts'));
+  args.push('-e', join(ROOT, 'extensions', 'codegraph.ts'));
+  if (opts.codegraphMaxFiles !== undefined) {
+    if (!/^\d+$/.test(String(opts.codegraphMaxFiles)) || !Number.isSafeInteger(Number(opts.codegraphMaxFiles)) || Number(opts.codegraphMaxFiles) < 1) throw Error('codegraph-max-files must be a positive safe integer');
+    args.push('--codegraph-max-files', String(opts.codegraphMaxFiles));
+  }
+  if (opts.delivery !== false) {
+    const workflow = opts.workflow ?? 'standard';
+    if (!['standard', 'strict'].includes(workflow)) throw Error('workflow must be standard or strict');
+    args.push('-e', join(ROOT, 'extensions', 'delivery.ts'),
+      '--skill', join(ROOT, 'skills'),
+      '--prompt-template', join(ROOT, 'prompts'));
+    args.push('--delivery-workflow', workflow);
+    if (opts.strict !== false) args.push('--delivery-strict');
+    if (opts.validators) args.push('--delivery-validators', resolve(opts.cwd || process.cwd(), opts.validators));
+    if (opts.context) args.push('--delivery-context', resolve(opts.cwd || process.cwd(), opts.context));
+    for (const [key, flag] of [['maxTools', 'tools'], ['maxSeconds', 'seconds'], ['maxRepairs', 'repairs']]) {
+      if (opts[key] !== undefined) args.push(`--delivery-max-${flag}`, String(opts[key]));
+    }
+    if (opts.bashCap) args.push('--delivery-bash-cap', String(opts.bashCap));
+    // Review is orchestrated by the console, not an engine extension flag.
+    // Forwarding --delivery-review makes the bundled engine reject startup.
+  }
+  return args;
+}
+
+// ------------------------------------------------------------- session files
+
+/** carthagent's per-cwd session dir: <agentDir>/sessions/--a-b-c--/. Defaults to ~/.carthagent/agent. */
+export function sessionDirFor(cwd = process.cwd(), agentDir = process.env.CARTHAGENT_AGENT_DIR || process.env.CARTHAGENT_CODING_AGENT_DIR || process.env.PI_CODING_AGENT_DIR || join(os.homedir(), '.carthagent', 'agent')) {
+  const safe = `--${resolve(cwd).replace(/^[/\\]/, '').replace(/[/\\:]/g, '-')}--`;
+  return join(agentDir, 'sessions', safe);
+}
+
+function textOfContent(content) {
+  if (!Array.isArray(content)) return typeof content === 'string' ? content : '';
+  return content.filter(c => c?.type === 'text').map(c => c.text).join('\n');
+}
+
+/** Read bounded metadata from one session file: header, latest name, first user message. */
+function readSessionMeta(path, mtime) {
+  const meta = { path, id: basename(path, '.jsonl').split('_').pop() || '', name: null, created: null, modified: mtime, messageCount: 0, firstMessage: '' };
+  let fd;
+  try {
+    fd = openSync(path, 'r');
+    const size = Math.min(4 * 1024 * 1024, fstatSync(fd).size);
+    const buf = Buffer.alloc(size);
+    readSync(fd, buf, 0, size, 0);
+    for (const line of buf.toString('utf8').split('\n')) {
+      if (!line) continue;
+      let e; try { e = JSON.parse(line); } catch { continue; }
+      if (e.type === 'session') { meta.id = e.id || meta.id; meta.created = e.timestamp || null; }
+      else if (e.type === 'session_info' && typeof e.name === 'string' && e.name.trim()) meta.name = e.name.trim();
+      else if (e.type === 'message') {
+        meta.messageCount++;
+        if (!meta.firstMessage && e.message?.role === 'user') {
+          const t = textOfContent(e.message.content).replace(/\s+/g, ' ').trim();
+          if (t) meta.firstMessage = t.slice(0, 200);
+        }
+      }
+    }
+  } catch { /* corrupt/partial file — return what we have */ }
+  finally { try { if (fd !== undefined) closeSync(fd); } catch { } }
+  return meta;
+}
+
+/** Sessions stored for a cwd, newest first. `dir` overrides discovery (tests). */
+export function listSessions(cwd = process.cwd(), { limit = 80, dir = sessionDirFor(cwd) } = {}) {
+  let files;
+  try { files = readdirSync(dir).filter(f => f.endsWith('.jsonl')); } catch { return []; }
+  const rows = [];
+  for (const f of files) {
+    const path = join(dir, f);
+    try { rows.push({ path, mtime: statSync(path).mtimeMs }); } catch { }
+  }
+  rows.sort((a, b) => b.mtime - a.mtime);
+  return rows.slice(0, limit).map(r => readSessionMeta(r.path, r.mtime));
+}
+
+/** Newest session file for a cwd, or null. */
+export function mostRecentSession(cwd = process.cwd(), dir) {
+  return listSessions(cwd, { limit: 1, dir })[0]?.path || null;
+}

package/lib/guidance.mjs

@@ -0,0 +1,71 @@
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { unframe } from './tui/framing.mjs';
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+export const DEFAULT_PROFILE_DIR = join(root, 'guidance', 'profiles');
+
+export function loadGuidanceProfiles(dir = DEFAULT_PROFILE_DIR) {
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir)
+    .filter(file => file.endsWith('.json'))
+    .sort()
+    .map(file => validateProfile(JSON.parse(readFileSync(join(dir, file), 'utf8')), file))
+    .sort((a, b) => b.priority - a.priority || a.id.localeCompare(b.id));
+}
+
+export function routeGuidance(request, { cwd = process.cwd(), profiles = loadGuidanceProfiles() } = {}) {
+  // Harness instructions are not user requirements. Route only the task.
+  const text = normalize(unframe(request) ?? request);
+  const dependencies = projectDependencies(cwd);
+  return profiles.filter(profile => {
+    const keywordMatch = (profile.match.keywords || []).some(keyword => contains(text, keyword));
+    const allMatch = !(profile.match.allKeywords || []).length || profile.match.allKeywords.every(keyword => contains(text, keyword));
+    const excluded = (profile.match.excludeKeywords || []).some(keyword => contains(text, keyword));
+    const dependencyMatch = (profile.match.dependencies || []).some(dependency => dependencies.has(dependency.toLowerCase()));
+    return !excluded && allMatch && (keywordMatch || (profile.activateOnDependency && dependencyMatch));
+  });
+}
+
+export function formatGuidance(profiles) {
+  if (!profiles.length) return '';
+  const lines = [
+    'Additional delivery guidance applies to this request. Apply it during delivery_plan, implementation, and review. Add only checks relevant to the requested change, but do not omit affected boundaries or failure paths.'
+  ];
+  for (const profile of profiles) {
+    lines.push(`\n[${profile.id}] ${profile.title}`);
+    for (const item of profile.planning) lines.push(`Plan: ${item}`);
+    for (const item of profile.checks) lines.push(`Check: ${item}`);
+    for (const item of profile.review) lines.push(`Review: ${item}`);
+  }
+  return lines.join('\n');
+}
+
+function projectDependencies(cwd) {
+  try {
+    const pkg = JSON.parse(readFileSync(join(cwd, 'package.json'), 'utf8'));
+    return new Set(Object.keys({ ...pkg.dependencies, ...pkg.devDependencies, ...pkg.peerDependencies }).map(name => name.toLowerCase()));
+  } catch {
+    return new Set();
+  }
+}
+
+function validateProfile(profile, file) {
+  const arrays = ['planning', 'checks', 'review'];
+  if (!profile || typeof profile !== 'object' || !/^[a-z][a-z0-9-]{1,39}$/.test(profile.id || '') || typeof profile.title !== 'string') throw Error(`Invalid guidance profile: ${file}`);
+  if (!profile.match || !Array.isArray(profile.match.keywords) || !profile.match.keywords.length) throw Error(`Guidance profile ${profile.id} needs match.keywords`);
+  for (const key of arrays) if (!Array.isArray(profile[key]) || !profile[key].every(item => typeof item === 'string' && item.trim())) throw Error(`Guidance profile ${profile.id} needs ${key} strings`);
+  return { priority: 0, activateOnDependency: false, ...profile };
+}
+
+function normalize(value) {
+  return String(value || '').toLowerCase().replace(/\s+/g, ' ').trim();
+}
+
+function contains(text, keyword) {
+  const value = normalize(keyword);
+  if (!value) return false;
+  if (/^[a-z0-9]+$/.test(value)) return new RegExp(`(?:^|[^a-z0-9])${value}(?:$|[^a-z0-9])`).test(text);
+  return text.includes(value);
+}

package/lib/jev-advisor.mjs

@@ -0,0 +1,47 @@
+import { ADVISOR_QUESTIONS } from './plan-advisor.mjs';
+
+// HTTP adapter for documented Noul answers. Key/network/time/pricing are injected.
+// No env lookup, implicit opt-in, retries, SDK install or approval authority.
+export function createJevAdvisor({ apiKey, fetchImpl = fetch, model = 'jev-1.13.0', timeoutMs = 3000, inputPricePerMillion = null } = {}) {
+  if (typeof apiKey !== 'string' || !apiKey.trim()) throw Error('Explicit Jev key required');
+  if (!Number.isInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 30000) throw Error('Advisor timeout must be 1–30000ms');
+  if (inputPricePerMillion !== null && (!Number.isFinite(inputPricePerMillion) || inputPricePerMillion < 0)) throw Error('Explicit nonnegative input pricing required');
+  return {
+    async classify(plan) {
+      const body = JSON.stringify({ model, state: { goal: plan.goal, acceptance: plan.acceptance, checks: plan.checks, outputs: plan.outputs, assumptions: plan.assumptions, design: plan.design, workflow: plan.workflow }, questions: ADVISOR_QUESTIONS });
+      if (Buffer.byteLength(body) > 64000) throw Error('Advisor request exceeds conservative 64KB local limit');
+      const controller = new AbortController();
+      let timer;
+      const timeout = new Promise((_, reject) => { timer = setTimeout(() => { controller.abort(); reject(Error('Advisor timeout')); }, timeoutMs); });
+      try {
+        return await Promise.race([timeout, (async () => {
+          const response = await fetchImpl('https://api.typesafe.ai/v1/systemone', { method: 'POST', headers: { authorization: `Bearer ${apiKey}`, 'content-type': 'application/json' }, body, signal: controller.signal, redirect: 'error' });
+          if (!response.ok) throw Error('Advisor HTTP failure');
+          const reader = response.body?.getReader();
+          if (!reader) throw Error('Advisor response body unavailable');
+          const chunks = []; let size = 0;
+          try {
+            for (;;) {
+              const { value, done } = await reader.read();
+              if (done) break;
+              size += value.byteLength;
+              if (size > 65536) { await reader.cancel(); throw Error('Advisor response too large'); }
+              chunks.push(Buffer.from(value));
+            }
+          } finally { reader.releaseLock(); }
+          const payload = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+          if (typeof payload.model !== 'string' || !payload.model.trim()) throw Error('Missing advisor model identity');
+          const probabilities = {};
+          for (const key of Object.keys(ADVISOR_QUESTIONS)) {
+            const answer = payload.answers?.[key];
+            if (answer?.type !== 'noul' || !Number.isFinite(answer.noul) || answer.noul < 0 || answer.noul > 1) throw Error('Invalid Noul answer');
+            probabilities[key] = answer.noul;
+          }
+          const tokens = payload.usage?.input_tokens;
+          const usage = Number.isInteger(tokens) && tokens >= 0 ? { inputTokens: tokens, outputTokens: payload.usage.output_tokens ?? null } : null;
+          return { model: payload.model, probabilities, usage, costUsd: usage && inputPricePerMillion !== null ? tokens * inputPricePerMillion / 1e6 : null };
+        })()]);
+      } finally { clearTimeout(timer); controller.abort(); }
+    },
+  };
+}

package/lib/opencode/archive.mjs

@@ -0,0 +1,122 @@
+import { constants, closeSync, fstatSync, lstatSync, openSync, readFileSync, readdirSync, realpathSync, statSync } from 'node:fs';
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+
+/** @param {string} directory @returns {string[]} */
+function walk(directory) {
+  let entries;
+  try { entries = readdirSync(directory, { withFileTypes: true }); } catch (error) { if (error.code === 'ENOENT') return []; throw error; }
+  const files = [];
+  for (const entry of entries) {
+    const path = join(directory, entry.name);
+    let stat;
+    try { stat = lstatSync(path); } catch (error) { if (error.code === 'ENOENT' || error.code === 'ELOOP') continue; throw error; }
+    // Do not follow either directory or file symlinks while enumerating an archive.
+    if (stat.isSymbolicLink()) continue;
+    if (stat.isDirectory()) files.push(...walk(path));
+    else if (stat.isFile() && entry.name.endsWith('.jsonl')) files.push(path);
+  }
+  return files;
+}
+
+function isWithin(root, path) {
+  const pathFromRoot = relative(root, path);
+  return pathFromRoot === '' || (pathFromRoot !== '..' && !pathFromRoot.startsWith(`..${sep}`) && !isAbsolute(pathFromRoot));
+}
+
+function canonicalRoots(roots = []) {
+  return roots.flatMap(root => {
+    try { return [realpathSync(resolve(root))]; }
+    catch (error) { if (error.code === 'ENOENT' || error.code === 'ENOTDIR') return []; throw error; }
+  });
+}
+
+/** Open the real target only after checking both its canonical parent and final target.
+ * O_NOFOLLOW prevents a final-component symlink swap between validation and open. */
+function readContained(path, allowedRoots) {
+  const lexical = resolve(path);
+  let realParent;
+  try { realParent = realpathSync(dirname(lexical)); } catch (error) { if (error.code === 'ENOENT' || error.code === 'ENOTDIR') throw error; throw Error('Legacy transcript parent is not accessible', { cause: error }); }
+  let realTarget;
+  try { realTarget = realpathSync(lexical); } catch (error) {
+    if ((error.code === 'ENOENT' || error.code === 'ENOTDIR') && allowedRoots.some(root => isWithin(root, realParent))) throw error;
+    throw Error('Legacy transcript path is outside configured archive roots or is not accessible', { cause: error });
+  }
+  if (!allowedRoots.some(root => isWithin(root, realParent) && isWithin(root, realTarget))) throw Error('Legacy transcript path is outside configured archive roots');
+  const targetStat = statSync(realTarget);
+  if (!realTarget.endsWith('.jsonl') || !targetStat.isFile()) throw Error('Legacy transcript must be a JSONL file');
+  let fd;
+  try {
+    fd = openSync(realTarget, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+    const openedStat = fstatSync(fd);
+    if (openedStat.dev !== targetStat.dev || openedStat.ino !== targetStat.ino) throw Error('Legacy transcript target changed while opening');
+    return readFileSync(fd, 'utf8');
+  } finally { if (fd !== undefined) closeSync(fd); }
+}
+
+/** @param {string} text @returns {{ rows: any[], malformed: Array<{ line: number }> }} */
+function parse(text) {
+  const rows = [];
+  const malformed = [];
+  text.split(/\r?\n/).forEach((line, index) => {
+    if (!line.trim()) return;
+    try { rows.push(JSON.parse(line)); } catch { malformed.push({ line: index + 1 }); }
+  });
+  return { rows, malformed };
+}
+
+/** @param {string} path @param {string[]} roots */
+function sessionInfo(path, roots) {
+  const canonical = realpathSync(path);
+  const { rows, malformed } = parse(readContained(canonical, roots));
+  const header = rows.find(row => row?.type === 'session') || rows[0] || {};
+  const messages = rows.filter(row => row?.type === 'message');
+  const text = messages.map(row => JSON.stringify(row.message ?? row)).join('\n');
+  return { id: header.id || basename(path, '.jsonl'), path: canonical, root: roots.find(root => isWithin(root, canonical)) || null, createdAt: header.timestamp || null, messageCount: messages.length, malformedLines: malformed, searchText: text };
+}
+
+/** Enumerate legacy Pi transcripts only; this module never imports or mutates them. */
+/** @param {{ roots: string[] }} options */
+export function listLegacyArchive({ roots }) {
+  if (!Array.isArray(roots)) throw Error('roots must be an array');
+  const allowed = canonicalRoots(roots);
+  const files = [...new Set(allowed.flatMap(root => walk(root)))].sort();
+  return files.flatMap(path => {
+    try { const info = sessionInfo(path, allowed); delete info.searchText; return [info]; }
+    catch (error) { if (error.code === 'ENOENT' || error.code === 'ELOOP') return []; throw error; }
+  });
+}
+
+/** @param {{ roots: string[], query: string }} options */
+export function searchLegacyArchive({ roots, query }) {
+  if (!Array.isArray(roots)) throw Error('roots must be an array');
+  if (typeof query !== 'string' || !query.trim()) throw Error('Search query is required');
+  const allowed = canonicalRoots(roots);
+  const needle = query.toLocaleLowerCase();
+  return [...new Set(allowed.flatMap(root => walk(root)))].sort().flatMap(path => {
+    try {
+      const session = sessionInfo(path, allowed);
+      const index = session.searchText.toLocaleLowerCase().indexOf(needle);
+      if (index < 0) return [];
+      return [{ ...session, excerpt: session.searchText.slice(Math.max(0, index - 120), index + needle.length + 180) }];
+    } catch (error) { if (error.code === 'ENOENT' || error.code === 'ELOOP') return []; throw error; }
+  });
+}
+
+/** @param {{ path: string, roots?: string[] }} options */
+export function readLegacyTranscript({ path, roots }) {
+  if (!roots) throw Error('Configured archive roots are required to read a legacy transcript');
+  const allowed = canonicalRoots(roots);
+  const target = resolve(path);
+  const content = readContained(target, allowed);
+  const canonical = realpathSync(target);
+  const { rows, malformed } = parse(content);
+  return { path: canonical, records: rows, malformedLines: malformed };
+}
+
+/** @param {{ path: string, format?: 'json' | 'jsonl', roots?: string[] }} options */
+export function exportLegacyTranscript({ path, format = 'json', roots }) {
+  const transcript = readLegacyTranscript({ path, roots });
+  if (format === 'json') return `${JSON.stringify(transcript.records, null, 2)}\n`;
+  if (format !== 'jsonl') throw Error('Export format must be json or jsonl');
+  return readContained(transcript.path, canonicalRoots(roots));
+}

package/lib/opencode/compatibility.mjs

@@ -0,0 +1,19 @@
+import { OPENCODE_VERSION, resolveOpenCode } from './runtime.mjs';
+
+/** Assert that the installed executable implements the native runtime contract. */
+export async function assertCompatibility(options = {}) {
+  const binary = await resolveOpenCode(options);
+  return Object.freeze({ binary, version: OPENCODE_VERSION, native: true });
+}
+
+/** Keep only portable CTG slash-command metadata for the native TUI launcher. */
+export function normalizeSlashCommand(name, definition) {
+  if (!/^[a-z][a-z0-9_-]*$/i.test(name)) throw new TypeError(`Invalid slash command name: ${name}`);
+  if (typeof definition === 'string') return { description: name, template: definition };
+  if (!definition || typeof definition.template !== 'string') throw new TypeError(`Slash command ${name} requires a template`);
+  return { description: definition.description ?? name, template: definition.template, ...(definition.agent ? { agent: definition.agent } : {}) };
+}
+
+export function nativeCommandConfig(commands = {}) {
+  return Object.fromEntries(Object.entries(commands).map(([name, definition]) => [name, normalizeSlashCommand(name, definition)]));
+}

package/lib/opencode/credentials.mjs

@@ -0,0 +1,205 @@
+/** CTG-owned credential helpers. OpenCode's integration store remains the
+ * authoritative store; this module only coordinates refresh and supports a
+ * one-way migration read from Carthagent's legacy auth.json. */
+import { open, readFile, rename, rm } from 'node:fs/promises';
+import { createHash, randomUUID } from 'node:crypto';
+import { join, resolve } from 'node:path';
+import os from 'node:os';
+import { shipAgentDir } from '../ship-auth.mjs';
+import { CARTHAGENT_SHIP_PROVIDER_ID } from '../providers/names.mjs';
+import { withFileLock } from './file-lock.mjs';
+
+export const CTG_CREDENTIAL_NAMESPACE = 'ctg.credentials/';
+const refreshFlights = new Map();
+
+const identity = value => String(value || '').trim();
+const processAlive = pid => {
+  try { process.kill(pid, 0); return true; }
+  catch (error) { return error.code === 'EPERM'; }
+};
+
+/** Single-flight by credential ID and refresh-token fingerprint. The callback
+ * persists the returned rotated token through the authoritative OpenCode
+ * integration refresh path; callers sharing the old credential await it. */
+export function refreshSingleFlight(key, refresh) {
+  const flightKey = identity(key);
+  if (!flightKey) return Promise.reject(new TypeError('A credential refresh key is required.'));
+  if (typeof refresh !== 'function') return Promise.reject(new TypeError('A refresh callback is required.'));
+  const active = refreshFlights.get(flightKey);
+  if (active) return active;
+  const flight = Promise.resolve().then(refresh);
+  refreshFlights.set(flightKey, flight);
+  return flight.finally(() => {
+    if (refreshFlights.get(flightKey) === flight) refreshFlights.delete(flightKey);
+  });
+}
+
+/** Select OpenCode's native profile credential file; never store a credential here. */
+export function nativeCredentialFile(env = process.env, platform = process.platform, home = os.homedir()) {
+  if (env.CTG_OPENCODE_CREDENTIAL_FILE) return resolve(env.CTG_OPENCODE_CREDENTIAL_FILE);
+  const dataHome = env.XDG_DATA_HOME || (platform === 'darwin'
+    ? join(home, 'Library', 'Application Support')
+    : platform === 'win32'
+      ? env.APPDATA || join(home, 'AppData', 'Roaming')
+      : join(home, '.local', 'share'));
+  return join(dataHome, 'opencode', 'auth.json');
+}
+
+/** Serialize refresh across host processes, rereading OpenCode's vault under the lock.
+ * @param {{credential: any, credentialFile: string, reread: () => Promise<any>, refresh: (credential: any) => Promise<any>, timeout?: number}} options
+ */
+export async function refreshNativeCredential({
+  credential,
+  credentialFile,
+  reread,
+  refresh,
+  timeout = 15_000,
+  processAliveImpl = processAlive,
+} = {}) {
+  if (!credential?.refresh || typeof reread !== 'function' || typeof refresh !== 'function') {
+    throw new TypeError('A refresh credential, vault reread, and refresh callback are required.');
+  }
+  const profile = resolve(credentialFile);
+  // Token material is never written to the lease path or logs.
+  const digest = createHash('sha256').update(`${credential.methodID || ''}\0${credential.refresh}`).digest('hex').slice(0, 32);
+  const lock = `${profile}.ctg-refresh-${digest}.lock`;
+  const pending = `${lock}.pending`;
+  const credentialDigest = value => createHash('sha256')
+    .update(`${value?.methodID || credential.methodID || ''}\0${value?.refresh || ''}`).digest('hex').slice(0, 32);
+  return withFileLock(lock, async () => {
+    const acceptPersistedRotation = async () => {
+      const latest = await reread();
+      if (latest?.type !== 'oauth' || !latest.refresh || credentialDigest(latest) === digest) return undefined;
+      const persistedReceipt = await readFile(pending, 'utf8').catch(() => '');
+      if (persistedReceipt === receipt?.raw) await rm(pending, { force: true });
+      return latest;
+    };
+    const current = await reread();
+    // OpenCode persists refresh callback results only after this callback
+    // resolves. Leave a token-free handoff receipt so another host that wins
+    // the disk lock during that gap waits for the native vault write instead
+    // of presenting the single-use refresh token a second time.
+    let receipt;
+    try {
+      receipt = JSON.parse(await readFile(pending, 'utf8'));
+      receipt.raw = JSON.stringify({ pid: receipt.pid, owner: receipt.owner, from: receipt.from, to: receipt.to, stage: receipt.stage, createdAt: receipt.createdAt });
+    }
+    catch (error) { if (error.code !== 'ENOENT') throw new Error('Invalid pending native credential refresh receipt; inspect the CTG refresh receipt before retrying.'); }
+    if (current?.type === 'oauth' && current.refresh && current.refresh !== credential.refresh) {
+      if (receipt?.from === digest && receipt.to === credentialDigest(current)) {
+        const persistedReceipt = await readFile(pending, 'utf8').catch(() => '');
+        if (persistedReceipt === receipt.raw) await rm(pending, { force: true });
+      }
+      return current;
+    }
+    if (receipt) {
+      if (receipt.from !== digest) throw new Error('A different native credential refresh is pending; retry after the active host saves its credential.');
+      if (receipt.stage === 'failed') throw new Error('A previous Ship refresh ended with an uncertain result. No second rotation was attempted; reauthenticate to recover safely.');
+      if (receipt.stage !== 'complete' && !processAliveImpl(receipt.pid)) {
+        throw new Error('A previous native credential refresh ended before its vault write could be confirmed. Inspect the CTG refresh receipt and reauthenticate if necessary; no second rotation was attempted.');
+      }
+      const until = Date.now() + timeout;
+      while (Date.now() < until) {
+        const latest = await acceptPersistedRotation();
+        if (latest) return latest;
+        if (!processAliveImpl(receipt.pid)) {
+          // The callback owner can persist the native vault and exit after the
+          // preceding read but before this liveness check. Make one final
+          // authoritative read before treating the outcome as uncertain.
+          const persisted = await acceptPersistedRotation();
+          if (persisted) return persisted;
+          throw new Error('The native refresh owner exited before OpenCode saved its credential. No second rotation was attempted; inspect the CTG refresh receipt.');
+        }
+        await new Promise(resolve => setTimeout(resolve, 40));
+      }
+      throw new Error('Timed out waiting for OpenCode to persist its refreshed credential; no second refresh was attempted.');
+    }
+
+    const owner = randomUUID();
+    const initialReceipt = JSON.stringify({ pid: process.pid, owner, from: digest, stage: 'refreshing', createdAt: Date.now() });
+    const pendingHandle = await open(pending, 'wx', 0o600);
+    try { await pendingHandle.writeFile(initialReceipt); await pendingHandle.sync(); }
+    finally { await pendingHandle.close(); }
+    const saveReceipt = async value => {
+      const temporary = `${pending}.${owner}.${value.stage}.tmp`;
+      const handle = await open(temporary, 'wx', 0o600);
+      try { await handle.writeFile(JSON.stringify(value)); await handle.sync(); }
+      finally { await handle.close(); }
+      if (await readFile(pending, 'utf8').catch(() => '') !== initialReceipt) {
+        await rm(temporary, { force: true });
+        throw new Error('Native credential refresh ownership changed unexpectedly; inspect the CTG refresh receipt.');
+      }
+      await rename(temporary, pending);
+    };
+    let rotated;
+    try {
+      rotated = await refresh(current?.type === 'oauth' ? current : credential);
+      if (rotated?.type !== 'oauth' || !rotated.refresh || !rotated.access) throw new Error('Ship token refresh returned an invalid OAuth credential.');
+    } catch (error) {
+      await saveReceipt({ pid: process.pid, owner, from: digest, stage: 'failed', createdAt: Date.now() });
+      throw error;
+    }
+    await saveReceipt({
+      pid: process.pid,
+      owner,
+      from: digest,
+      to: credentialDigest(rotated),
+      stage: 'complete',
+      createdAt: Date.now(),
+    });
+    return rotated;
+  }, { timeout });
+}
+
+/** Namespaced plugin-store keys avoid colliding with host/plugin settings. */
+export function credentialStorageKey(integrationID) {
+  const id = identity(integrationID);
+  if (!/^[a-z0-9][a-z0-9._-]{0,127}$/i.test(id)) throw new TypeError('Invalid CTG integration id.');
+  return `${CTG_CREDENTIAL_NAMESPACE}${id}`;
+}
+
+/**
+ * Read a legacy Pi-compatible auth entry for explicit migration only. Never
+ * writes the old file; successful login/refresh must be saved by OpenCode.
+ */
+export async function readLegacyCarthagentCredential({
+  agentDir = shipAgentDir(),
+  providerID = CARTHAGENT_SHIP_PROVIDER_ID,
+  readFileImpl = readFile,
+} = {}) {
+  try {
+    const parsed = JSON.parse(await readFileImpl(join(agentDir, 'auth.json'), 'utf8'));
+    const credential = parsed?.[providerID];
+    if (credential?.type === 'oauth'
+      && typeof credential.access === 'string' && credential.access
+      && typeof credential.refresh === 'string' && credential.refresh
+      && Number.isFinite(Number(credential.expires))) {
+      return { type: 'oauth', access: credential.access, refresh: credential.refresh, expires: Number(credential.expires) };
+    }
+    // BYOK used the same provider namespace in Pi and remains a valid direct
+    // OpenCode API key; do not reinterpret it as managed Ship OAuth.
+    if (credential?.type === 'api_key' && typeof credential.key === 'string' && credential.key.trim()) {
+      return { type: 'api_key', key: credential.key.trim() };
+    }
+  } catch { /* no legacy store or unreadable/malformed data */ }
+  return undefined;
+}
+
+/** Mark only an explicit migration value as eligible for OpenCode OAuth
+ * persistence. The actual write is returned from IntegrationOAuthAuthorization
+ * and is therefore performed by OpenCode's credential store. */
+export async function legacyOAuthForOpenCode(options = {}) {
+  const credential = await readLegacyCarthagentCredential(options);
+  if (credential?.type !== 'oauth') return undefined;
+  return {
+    type: 'oauth',
+    methodID: 'carthagent-device',
+    access: credential.access,
+    refresh: credential.refresh,
+    expires: Math.trunc(credential.expires),
+  };
+}
+
+export function legacyCredentialMigrationGuidance() {
+  return 'Existing Carthagent Ship OAuth can be migrated from the legacy auth.json credential into OpenCode integration storage; other provider credentials remain BYOK and may be reconnected through OpenCode if their format is unsupported.';
+}