carthagent 0.0.0-stage → 1.0.7

package/lib/opencode/headless.mjs

@@ -0,0 +1,200 @@
+import { cancelSession, createSession, getSession, promptSession, serviceRequest, sessionMessages, setSessionEnvironment } from './service.mjs';
+
+const POLL_INTERVAL = 50;
+const MAX_TURN_MESSAGES = 200;
+
+/** Create and run a native session, returning its terminal execution outcome. */
+export async function runHeadless(service, workspace, prompt, options = {}) {
+  // Avoid installing a forwarding listener (or allocating timeout state) for
+  // calls that are already cancelled. This also keeps repeated calls on a
+  // shared AbortSignal listener-free.
+  if (options.signal?.aborted) return preAdmissionResult(options.sessionID, 'aborted', options.signal.reason);
+  const controller = new AbortController();
+  const forwardAbort = () => controller.abort(options.signal?.reason);
+  options.signal?.addEventListener('abort', forwardAbort, { once: true });
+  const timeout = options.timeout ?? 120_000;
+  const deadline = Date.now() + timeout;
+  const timeoutSignal = AbortSignal.timeout(timeout);
+  const signal = AbortSignal.any([controller.signal, timeoutSignal]);
+  let created;
+  let id = options.sessionID;
+  let session;
+  let accepted;
+  let promptStarted = false;
+  try {
+    if (!id) {
+      created = await createSession(service, workspace, { body: options.session ?? {}, signal });
+      id = created?.id ?? created?.sessionID;
+    }
+    if (!id) throw new Error('OpenCode did not return a valid session identifier');
+    session = created ?? { id };
+    await setSessionEnvironment(service, id, options.env ?? process.env, { location: workspace, signal });
+    promptStarted = true;
+    accepted = await promptSession(service, id, prompt, {
+      location: workspace,
+      signal,
+      body: { ...(options.prompt ?? {}), ...(options.parts ? { parts: options.parts } : {}), text: prompt },
+    });
+    await serviceRequest(service, 'POST', `/api/experimental/session/${encodeURIComponent(id)}/wait`, { signal, location: workspace });
+    session = await waitForOutcome(service, id, workspace, { deadline, signal, accepted });
+    const fetched = await sessionMessages(service, id, { signal, location: workspace });
+    const messages = currentTurnMessages(chronologicalMessages(fetched), accepted, options.maxMessages);
+    const result = extractAssistant(messages, accepted);
+    const idle = terminalIdle(messages);
+    const outcome = session.outcome ?? idle?.outcome ?? 'failed';
+    const terminal = Boolean(session.outcome || idle);
+    return {
+      session,
+      accepted,
+      messages,
+      result,
+      outcome,
+      terminal,
+      reason: session.ctg?.reason,
+      budgetReason: terminal ? undefined : session.ctg?.reason ?? 'terminal outcome was not observed before timeout',
+      error: outcome === 'failed' ? result?.error ?? session.error ?? idle?.error : undefined,
+    };
+  } catch (error) {
+    if (options.signal?.aborted || timeoutSignal.aborted) {
+      if (!accepted) {
+        if (id && promptStarted) await cancelSession(service, id, { location: workspace, timeout: 5000 }).catch(() => {});
+        return preAdmissionResult(id, options.signal?.aborted ? 'aborted' : 'timed-out', error, options.signal?.reason);
+      }
+      await cancelSession(service, id, { location: workspace, timeout: 5000 }).catch(() => {});
+      const saved = await observeOutcome(service, id, workspace, AbortSignal.timeout(5000)).catch(() => session);
+      if (saved?.outcome) session = saved;
+      const reason = options.signal?.aborted ? 'aborted' : 'timed-out';
+      return incompleteResult(service, id, workspace, accepted, session, reason, error, options.signal?.reason);
+    }
+    throw error;
+  } finally {
+    options.signal?.removeEventListener('abort', forwardAbort);
+  }
+}
+
+function preAdmissionResult(sessionID, reason, cause, abortReason) {
+  const outcome = reason === 'aborted' ? 'interrupted' : 'timed-out';
+  return {
+    ...(sessionID ? { session: { id: sessionID } } : {}),
+    messages: [],
+    result: undefined,
+    outcome,
+    terminal: false,
+    reason,
+    budgetReason: outcome === 'timed-out' ? reason : undefined,
+    cause: cause?.message,
+    abortReason: abortReason?.message,
+  };
+}
+
+async function waitForOutcome(service, sessionID, workspace, { deadline, signal, accepted }) {
+  let lastError;
+  while (Date.now() < deadline) {
+    signal.throwIfAborted();
+    try {
+      const session = await getSession(service, sessionID, { location: workspace, signal });
+      if (session?.outcome) return session;
+      lastError = undefined;
+    } catch (error) {
+      if (error.status !== 503) throw error;
+      lastError = error;
+    }
+    if (Date.now() >= deadline) break;
+    await delay(Math.min(POLL_INTERVAL, deadline - Date.now()), signal);
+  }
+  const observed = await observeOutcome(service, sessionID, workspace, AbortSignal.timeout(5000)).catch(() => undefined);
+  const messages = await sessionMessages(service, sessionID, { location: workspace, signal: AbortSignal.timeout(5000) }).catch(() => []);
+  const turnMessages = currentTurnMessages(chronologicalMessages(messages), accepted);
+  const idle = terminalIdle(turnMessages);
+  const reason = lastError ? 'session projection remained unavailable (503)' : 'session outcome was not observed';
+  return {
+    ...(observed ?? { id: sessionID }),
+    outcome: observed?.outcome ?? idle?.outcome ?? 'failed',
+    error: observed?.error ?? idle?.error ?? lastError,
+    ctg: { terminal: Boolean(observed?.outcome || idle), reason, acceptedMessageID: accepted?.id },
+  };
+}
+
+async function observeOutcome(service, sessionID, workspace, signal) {
+  return getSession(service, sessionID, { location: workspace, signal });
+}
+
+async function incompleteResult(service, sessionID, workspace, accepted, session, reason, cause, abortReason) {
+  const fetched = await sessionMessages(service, sessionID, { location: workspace, signal: AbortSignal.timeout(5000) }).catch(() => []);
+  const messages = currentTurnMessages(chronologicalMessages(fetched), accepted);
+  const idle = terminalIdle(messages);
+  const outcome = session.outcome ?? idle?.outcome ?? (reason === 'aborted' ? 'interrupted' : undefined);
+  const result = extractAssistant(messages, accepted);
+  const reasonText = session.ctg?.reason ?? reason;
+  const finalOutcome = outcome ?? (reason === 'timed-out' ? 'timed-out' : 'interrupted');
+  return {
+    session: { ...session, ...(outcome ? { outcome } : {}), error: session.error ?? idle?.error },
+    accepted,
+    messages,
+    result,
+    outcome: finalOutcome,
+    error: finalOutcome === 'failed' ? result?.error ?? session.error ?? idle?.error : undefined,
+    terminal: Boolean(session.outcome || idle),
+    reason: reasonText,
+    budgetReason: finalOutcome === 'timed-out' || finalOutcome === 'failed' ? reasonText : undefined,
+    cause: cause?.message,
+    abortReason: abortReason?.message,
+  };
+}
+
+function delay(milliseconds, signal) {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(done, milliseconds);
+    function done() { signal.removeEventListener('abort', aborted); resolve(); }
+    function aborted() { clearTimeout(timer); signal.removeEventListener('abort', aborted); reject(signal.reason); }
+    signal.addEventListener('abort', aborted, { once: true });
+    if (signal.aborted) aborted();
+  });
+}
+
+function chronologicalMessages(messages) {
+  const list = Array.isArray(messages) ? messages : messages?.data ?? messages?.messages ?? [];
+  return [...list].reverse().sort((left, right) => messageTime(left) - messageTime(right));
+}
+
+function messageTime(item) {
+  const value = item.time?.created ?? item.timestamp ?? item.info?.time?.created ?? item.info?.timestamp ?? 0;
+  const number = typeof value === 'number' ? value : Date.parse(value);
+  return Number.isFinite(number) ? number : 0;
+}
+
+function terminalIdle(messages) {
+  return [...messages].reverse().find((item) => item.type === 'idle' && ['succeeded', 'failed', 'interrupted'].includes(item.outcome));
+}
+
+function currentTurnMessages(messages, accepted, limit = MAX_TURN_MESSAGES) {
+  const acceptedIndex = accepted?.id ? messages.findIndex((item) => item.id === accepted.id) : -1;
+  const lastUserIndex = acceptedIndex >= 0
+    ? acceptedIndex
+    : messages.reduce((latest, item, index) => item.type === 'user' ? index : latest, -1);
+  const turn = lastUserIndex >= 0 ? messages.slice(lastUserIndex) : messages;
+  return turn.slice(-Math.max(1, Math.min(MAX_TURN_MESSAGES, Number.isInteger(limit) ? limit : MAX_TURN_MESSAGES)));
+}
+
+function extractAssistant(messages, accepted) {
+  const assistantMessages = messages.filter((item) => item.type === 'assistant' || item.info?.role === 'assistant' || item.role === 'assistant');
+  const latestAssistant = assistantMessages.at(-1);
+  const acceptedTime = accepted?.time?.created;
+  const acceptedIndex = accepted?.id ? messages.findIndex((item) => item.id === accepted.id) : -1;
+  const assistantAfterAccepted = acceptedIndex >= 0
+    ? assistantMessages.filter((item) => messages.indexOf(item) > acceptedIndex).at(-1)
+    : undefined;
+  const message = acceptedIndex >= 0
+    ? assistantAfterAccepted
+    : (Number.isFinite(acceptedTime) ? assistantMessages.filter((item) => messageTime(item) >= acceptedTime).at(-1) : undefined) ?? latestAssistant;
+  if (!message) return undefined;
+  const parts = message.parts ?? message.content ?? [];
+  return {
+    status: message.finish ?? message.info?.finish ?? message.info?.status ?? message.status,
+    text: Array.isArray(parts) ? parts.filter((part) => part.type === 'text' || part.type === 'text-delta' || typeof part.text === 'string').map((part) => part.text ?? '').join('') : String(parts),
+    error: message.error ?? message.info?.error,
+    message,
+  };
+}
+
+export { cancelSession, createSession, getSession, promptSession, sessionMessages, setSessionEnvironment };

package/lib/opencode/review.mjs

@@ -0,0 +1,213 @@
+import { createHash } from 'node:crypto';
+import { execFileSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { resolve } from 'node:path';
+import { beginReview, parseFindings } from '../review-state.mjs';
+
+function reviewVerdict(output) {
+  const line = output.trim().split(/\r?\n/).at(-1);
+  const match = /^VERDICT: (APPROVE|CHANGES-REQUESTED)$/.exec(line || '');
+  if (!match) throw Error('Reviewer output must end with an exact structured VERDICT line');
+  return match[1];
+}
+
+function localSource(root, git) {
+  const diff = git('diff', 'HEAD', '--binary', { trim: false });
+  const untracked = execFileSync('git', ['ls-files', '--others', '--exclude-standard', '-z'], { cwd: root, encoding: 'utf8' }).split('\0').filter(path => path && path !== '.harness' && !path.startsWith('.harness/')).sort();
+  return `${diff}\0UNTRACKED\0${untracked.map(path => `${path}\0${readFileSync(join(root, path)).toString('base64')}`).join('\0')}`;
+}
+
+/** Return the same source-bound identity used by local reviews without launching a reviewer. */
+export function localReviewSnapshot(cwd) {
+  const root = resolve(cwd);
+  const head = execFileSync('git', ['rev-parse', 'HEAD'], { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+  const git = (...args) => {
+    const options = args.at(-1)?.trim === false ? args.pop() : undefined;
+    const output = execFileSync('git', args, { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+    return options ? output : output.trim();
+  };
+  return { head, snapshot: createReviewSnapshot({ source: localSource(root, git), head }) };
+}
+
+function assistantText(messages, session) {
+  if (session?.outcome && session.outcome !== 'succeeded') throw Error(`Reviewer execution did not succeed (${session.outcome})`);
+  const terminal = messages.at(-1);
+  if (terminal?.type !== 'idle' || terminal.outcome !== 'succeeded') throw Error(`Reviewer execution did not reach a successful terminal state (${terminal?.type === 'idle' ? terminal.outcome : 'missing'})`);
+  const assistant = [...messages.slice(0, -1)].reverse().find(message => message.type === 'assistant');
+  if (!assistant || assistant.finish !== 'stop' || !Array.isArray(assistant.content)) throw Error('Reviewer did not return a completed assistant response');
+  return assistant.content.filter(part => part.type === 'text').map(part => part.text).join('\n');
+}
+
+const READ_ONLY_PERMISSIONS = [
+  { action: '*', resource: '*', effect: 'deny' },
+  { action: 'shell', resource: '*', effect: 'deny' },
+  { action: 'edit', resource: '*', effect: 'deny' },
+  { action: 'write', resource: '*', effect: 'deny' },
+  { action: 'external_directory', resource: '*', effect: 'deny' },
+  { action: 'execute', resource: '*', effect: 'deny' },
+  { action: 'subagent', resource: '*', effect: 'deny' },
+  { action: 'skill', resource: '*', effect: 'deny' },
+  { action: 'read', resource: '*', effect: 'allow' },
+  { action: 'glob', resource: '*', effect: 'allow' },
+  { action: 'grep', resource: '*', effect: 'allow' },
+];
+
+function reviewerSignal(signal, timeoutMs) {
+  if (!Number.isInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 300_000) throw Error('Review timeout must be an integer from 1 to 300000 ms');
+  const timeout = AbortSignal.timeout(timeoutMs);
+  return signal ? AbortSignal.any([signal, timeout]) : timeout;
+}
+
+async function interruptReviewer(ctx, sessionID) {
+  let timer;
+  try {
+    return await Promise.race([
+      ctx.session.interrupt({ sessionID, resume: false }, { signal: AbortSignal.timeout(2_000) }).then(result => result.interrupted === true),
+      new Promise(resolveInterrupt => { timer = setTimeout(() => resolveInterrupt(false), 2_000); }),
+    ]);
+  } finally { if (timer) clearTimeout(timer); }
+}
+
+async function selectReviewerAgent(ctx, agent, signal) {
+  const list = await ctx.agent.list({}, { signal });
+  const agents = Array.isArray(list) ? list : list?.data;
+  if (!Array.isArray(agents) || !agents.some(item => item.id === agent)) throw Error(`Reviewer agent ${agent} is not registered at this OpenCode location`);
+  return agent;
+}
+
+async function runReviewer({ ctx, root, title, prompt, agent, model, signal, timeoutMs }) {
+  const requestSignal = reviewerSignal(signal, timeoutMs);
+  let reviewer;
+  try {
+    await selectReviewerAgent(ctx, agent, requestSignal);
+    reviewer = await ctx.session.create({ title, agent, model, location: { directory: root }, permissions: READ_ONLY_PERMISSIONS }, { signal: requestSignal });
+    // Mark structured reviewer instructions as raw so the session-controls hook
+    // does not append the user's delivery workflow to this read-only review.
+    await ctx.session.prompt({ sessionID: reviewer.id, text: prompt, metadata: { 'ctg.raw': true } }, { signal: requestSignal });
+    await ctx.session.wait({ sessionID: reviewer.id }, { signal: requestSignal });
+    const [messages, session] = await Promise.all([
+      ctx.session.context({ sessionID: reviewer.id }, { signal: requestSignal }),
+      ctx.session.get({ sessionID: reviewer.id }, { signal: requestSignal }),
+    ]);
+    return { reviewer, output: assistantText(messages, session) };
+  } catch (error) {
+    let interrupted = false;
+    if (reviewer && (requestSignal.aborted || signal?.aborted)) {
+      try { interrupted = await interruptReviewer(ctx, reviewer.id); }
+      catch { /* Preserve the cancellation/timeout failure. */ }
+    }
+    if (requestSignal.aborted) {
+      const reason = signal?.aborted ? 'cancelled' : 'timed out';
+      const stopped = interrupted ? 'reviewer interruption confirmed' : 'reviewer may still be running; interruption was not confirmed';
+      throw Error(`Review ${reason}; ${stopped} (session ${reviewer?.id ?? 'creation pending'})`, { cause: error });
+    }
+    throw error;
+  }
+}
+
+export function createReviewSnapshot({ source, head }) {
+  return createHash('sha256').update(`${source}\0${head}`).digest('hex');
+}
+
+/** Local delivery review. This does not approve or merge a remote PR. */
+/** @param {{ ctx: OpenCodeContext, cwd: string, identity?: string, model?: { providerID: string, id: string, variant?: string }, agent?: string, signal?: AbortSignal, timeoutMs?: number }} options */
+export async function startReview({ ctx, cwd, identity = 'local-delivery', model = /** @type {{ providerID: string, id: string, variant?: string }} */ ({ providerID: 'lattice', id: 'gpt-6-luna', variant: 'high' }), agent = 'build', signal, timeoutMs = 300_000 }) {
+  const root = resolve(cwd);
+  const git = (...args) => {
+    const options = args.at(-1)?.trim === false ? args.pop() : undefined;
+    const output = execFileSync('git', args, { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+    return options ? output : output.trim();
+  };
+  const head = git('rev-parse', 'HEAD');
+  const source = localSource(root, git);
+  const snapshot = createReviewSnapshot({ source, head });
+  const admission = beginReview(root, identity, snapshot, head);
+  let reviewer;
+  try {
+    const prompt = `Review this exact local delivery source at ${root}. This is a read-only local delivery review, not a PR review. Do not modify files, commit, push, or merge.\nHEAD: ${head}\nSnapshot SHA-256: ${snapshot}\n\nExact source diff and untracked source files (base64 records where applicable):\n${source}\n\nReport findings and end with REVIEW_JSON: {"version":1,"snapshot":"${snapshot}","head":"${head}","findings":[]} followed by VERDICT: APPROVE or VERDICT: CHANGES-REQUESTED.`;
+    const result = await runReviewer({ ctx, root, title: `CTG review: ${identity}`, prompt, agent, model, signal, timeoutMs });
+    reviewer = result.reviewer;
+    const output = result.output;
+    const verdict = reviewVerdict(output);
+    const findings = parseFindings(output, snapshot, head, verdict);
+    const currentHead = await git('rev-parse', 'HEAD');
+    const currentSource = localSource(root, git);
+    if (currentHead !== head || createReviewSnapshot({ source: currentSource, head: currentHead }) !== snapshot) throw Error('Local review source or HEAD moved while review was running');
+    const status = verdict === 'APPROVE' ? 'approved' : 'changes-requested';
+    admission.finish(status, { reviewerSessionID: reviewer.id, findings: findings.findings, remote: false });
+    return { type: 'local-delivery', identity, head, snapshot, reviewerSessionID: reviewer.id, verdict, findings };
+  } catch (error) {
+    admission.finish('inconclusive', { message: String(error.message || error) });
+    throw error;
+  } finally { admission.release(); }
+}
+
+function commandOutput(command, args, cwd, { trim = true } = {}) {
+  const result = execFileSync(command, args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+  const output = Buffer.isBuffer(result) ? result.toString('utf8') : String(result);
+  return trim ? output.trim() : output;
+}
+
+function authoritativePR({ cwd, repository, prNumber }) {
+  if (!Number.isInteger(prNumber) || prNumber < 1) throw Error('A positive GitHub pull request number is required');
+  if (!/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(repository || '')) throw Error('A GitHub repository in owner/name form is required');
+  const git = (...args) => commandOutput('git', args, cwd);
+  const response = commandOutput('gh', ['api', `repos/${repository}/pulls/${prNumber}`], cwd);
+  let pullRequest;
+  try { pullRequest = JSON.parse(response); } catch (error) { throw Error('GitHub CLI returned malformed pull request metadata', { cause: error }); }
+  const headRepository = pullRequest?.head?.repo?.full_name;
+  const headUrl = pullRequest?.head?.repo?.clone_url;
+  const baseRepository = pullRequest?.base?.repo?.full_name;
+  const baseUrl = pullRequest?.base?.repo?.clone_url;
+  const remoteHead = pullRequest?.head?.sha;
+  const baseHead = pullRequest?.base?.sha;
+  const headRefName = pullRequest?.head?.ref;
+  const baseRefName = pullRequest?.base?.ref;
+  if (pullRequest?.state !== 'open' || !headRepository || !headUrl || !baseRepository || !baseUrl || typeof headRefName !== 'string' || typeof baseRefName !== 'string' || !/^[a-f0-9]{40}$/i.test(remoteHead || '') || !/^[a-f0-9]{40}$/i.test(baseHead || '')) throw Error('GitHub PR is not open or did not provide authoritative head/base commits');
+  const localHead = git('rev-parse', 'HEAD');
+  const headRef = `refs/ctg-review/pr-${prNumber}/head`;
+  const baseRef = `refs/ctg-review/pr-${prNumber}/base`;
+  if (git('check-ref-format', '--branch', headRefName) !== headRefName || git('check-ref-format', '--branch', baseRefName) !== baseRefName) throw Error('GitHub PR returned an invalid branch ref');
+  commandOutput('git', ['fetch', '--no-tags', '--no-write-fetch-head', headUrl, `+refs/heads/${headRefName}:${headRef}`], cwd);
+  commandOutput('git', ['fetch', '--no-tags', '--no-write-fetch-head', baseUrl, `+refs/heads/${baseRefName}:${baseRef}`], cwd);
+  if (git('rev-parse', headRef) !== remoteHead || git('rev-parse', baseRef) !== baseHead) throw Error('Fetched GitHub branch refs do not match the authoritative pull request commit IDs');
+  if (localHead !== remoteHead) throw Error('Local HEAD does not match the authoritative GitHub PR head');
+  const mergeBase = git('merge-base', baseHead, remoteHead);
+  const source = commandOutput('git', ['diff', '--binary', mergeBase, remoteHead, '--'], cwd, { trim: false });
+  if (git('rev-parse', `${remoteHead}^{commit}`) !== remoteHead || git('rev-parse', `${baseHead}^{commit}`) !== baseHead) throw Error('Fetched Git objects do not match the authoritative GitHub PR commits');
+  return { repository: repository.toLowerCase(), prNumber, localHead, remoteHead, baseHead, headRepository: headRepository.toLowerCase(), source };
+}
+
+/** PR approval is derived from GitHub PR metadata and exact fetched Git objects, never caller-supplied refs/source. */
+/** @typedef {import('@opencode/plugin/promise/plugin').Context} OpenCodeContext */
+/** @param {{ ctx: OpenCodeContext, cwd: string, repository: string, prNumber: number, model?: { providerID: string, id: string, variant?: string }, agent?: string, signal?: AbortSignal, timeoutMs?: number }} options */
+export async function startPullRequestReview({ ctx, cwd, repository, prNumber, model = /** @type {{ providerID: string, id: string, variant?: string }} */ ({ providerID: 'lattice', id: 'gpt-6-luna', variant: 'high' }), agent = 'build', signal, timeoutMs = 300_000 }) {
+  const root = resolve(cwd);
+  const initial = authoritativePR({ cwd: root, repository, prNumber });
+  const identity = `${initial.repository}#${initial.prNumber}`;
+  const head = initial.remoteHead;
+  const snapshot = createReviewSnapshot({ source: initial.source, head });
+  const admission = beginReview(root, `pr:${identity}`, snapshot, head);
+  try {
+    const prompt = `Review this exact GitHub pull request source snapshot. This is remote PR review, not local delivery review. Do not modify files, commit, push, or merge.\nRepository: ${identity}\nVerified PR head: ${head}\nSnapshot SHA-256: ${snapshot}\n\n${initial.source}\n\nReturn REVIEW_JSON: {"version":1,"snapshot":"${snapshot}","head":"${head}","findings":[]} followed by VERDICT: APPROVE or VERDICT: CHANGES-REQUESTED.`;
+    const result = await runReviewer({ ctx, root, title: `CTG PR review: ${identity}`, prompt, agent, model, signal, timeoutMs });
+    const reviewer = result.reviewer;
+    const output = result.output;
+    const verdict = reviewVerdict(output);
+    const findings = parseFindings(output, snapshot, head, verdict);
+    const current = authoritativePR({ cwd: root, repository, prNumber });
+    if (current.repository !== initial.repository || current.headRepository !== initial.headRepository || current.localHead !== initial.localHead || current.remoteHead !== initial.remoteHead || current.baseHead !== initial.baseHead || createReviewSnapshot({ source: current.source, head: current.remoteHead }) !== snapshot) throw Error('Authoritative GitHub PR refs or source moved while review was running');
+    admission.finish(verdict === 'APPROVE' ? 'approved' : 'changes-requested', { reviewerSessionID: reviewer.id, findings: findings.findings, remote: true });
+    return { type: 'pull-request', identity, head, snapshot, reviewerSessionID: reviewer.id, verdict, findings };
+  } catch (error) {
+    admission.finish('inconclusive', { message: String(error.message || error), remote: true });
+    throw error;
+  } finally { admission.release(); }
+}
+
+/** PR review guard: caller supplies the verified source refs from local and remote checks. */
+export function verifyPullRequestHeads({ localHead, remoteHead, pullRequestHead }) {
+  if (!localHead || !remoteHead || !pullRequestHead || localHead !== remoteHead || remoteHead !== pullRequestHead) throw Error('PR review head mismatch; refresh and review the exact current PR source');
+  return { verifiedHead: pullRequestHead };
+}

package/lib/opencode/runtime.mjs

@@ -0,0 +1,246 @@
+import { chmod, mkdir, open, readFile, rename, rm, stat } from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+import { homedir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+
+export const OPENCODE_VERSION = '2.0.32';
+const DEFAULT_ROOT = path.join(homedir(), '.carthagent', 'opencode');
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
+
+function abs(value) { return path.resolve(value); }
+
+/** Return the isolated CTG OpenCode filesystem layout. */
+export function runtimePaths(options = {}) {
+  const root = abs(options.root ?? process.env.CTG_OPENCODE_HOME ?? DEFAULT_ROOT);
+  return Object.freeze({
+    root,
+    home: path.join(root, 'home'),
+    appData: path.join(root, 'home', 'AppData', 'Roaming'),
+    localAppData: path.join(root, 'home', 'AppData', 'Local'),
+    config: path.join(root, 'config'),
+    configDir: path.join(root, 'config', 'opencode'),
+    data: path.join(root, 'data'),
+    state: path.join(root, 'state'),
+    cache: path.join(root, 'cache'),
+    serviceFile: path.join(root, 'state', 'opencode', 'service.json'),
+    credentials: path.join(root, 'data', 'opencode', 'auth.json'),
+    configFile: path.join(root, 'config', 'opencode', 'opencode.json'),
+    lifecycleLock: path.join(root, 'state', 'opencode', 'lifecycle.lock'),
+    profileLock: path.join(root, 'state', 'opencode', 'profile.lock'),
+  });
+}
+
+/** Find a CTG/OpenCode executable without downloading or replacing user binaries. */
+export async function resolveOpenCode(options = {}) {
+  const explicit = options.binary ?? process.env.CTG_OPENCODE_BIN;
+  const packaged = path.join(PACKAGE_ROOT, 'node_modules', '@opencode', 'cli', 'bin', 'opencode.exe');
+  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 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}`);
+        return abs(candidate);
+      } catch (error) {
+        if (explicit || /is required/.test(error.message)) throw error;
+      }
+    } else {
+      try {
+        const result = await runCapture(candidate, ['--version'], { timeout: 5000, spawnImpl: options.spawnImpl });
+        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;
+      } 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.`);
+}
+
+/** Construct the environment for CTG-owned OpenCode children. */
+export function runtimeEnvironment(options = {}) {
+  const paths = runtimePaths(options);
+  // OpenCode has many profile/config switches; do not inherit ambient host
+  // 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_')));
+  Object.assign(env, {
+    XDG_CONFIG_HOME: paths.config,
+    XDG_DATA_HOME: paths.data,
+    XDG_STATE_HOME: paths.state,
+    XDG_CACHE_HOME: paths.cache,
+    HOME: paths.home,
+    APPDATA: paths.appData,
+    LOCALAPPDATA: paths.localAppData,
+    OPENCODE_TEST_HOME: paths.home,
+    USERPROFILE: paths.home,
+    OPENCODE_DB: path.join(paths.data, 'opencode.db'),
+    OPENCODE_CONFIG: paths.configFile,
+    OPENCODE_CONFIG_DIR: paths.configDir,
+    OPENCODE_CONFIG_PROJECT_DISABLE: 'true',
+    OPENCODE_DISABLE_MODELS_FETCH: 'true',
+    OPENCODE_DISABLE_CLAUDE_CODE: 'true',
+    OPENCODE_DISABLE_CLAUDE_CODE_SKILLS: 'true',
+    OPENCODE_DISABLE_AUTOUPDATE: 'true',
+    CTG_OPENCODE_HOME: paths.root,
+  });
+  return env;
+}
+
+/** Ensure private persistent directories and CTG profile/plugin config exist. */
+export async function provisionRuntime(options = {}) {
+  const paths = runtimePaths(options);
+  for (const directory of [paths.root, paths.home, paths.appData, paths.localAppData, paths.config, paths.configDir, paths.data, paths.state, path.dirname(paths.serviceFile), paths.cache]) {
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    await chmod(directory, 0o700).catch(() => {});
+  }
+  await withFileLock(paths.profileLock, async () => {
+    let current = {};
+    try {
+      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}`);
+    }
+    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])];
+    }
+    await atomicWrite(paths.configFile, `${JSON.stringify(config, null, 2)}\n`, 0o600);
+  });
+  return paths;
+}
+
+export async function atomicWrite(file, contents, mode = 0o600) {
+  await mkdir(path.dirname(file), { recursive: true, mode: 0o700 });
+  const temporary = `${file}.${process.pid}.${randomUUID()}.tmp`;
+  const handle = await open(temporary, 'wx', mode);
+  try {
+    await handle.writeFile(contents);
+    await handle.sync();
+    await handle.close();
+    await rename(temporary, file);
+    await chmod(file, mode).catch(() => {});
+  } catch (error) {
+    await handle.close().catch(() => {});
+    await rm(temporary, { force: true }).catch(() => {});
+    throw error;
+  }
+}
+
+/** Cross-process exclusive lock with bounded wait and dead-owner recovery. */
+export async function withFileLock(file, action, options = {}) {
+  const timeout = options.timeout ?? 15000;
+  const deadline = Date.now() + timeout;
+  await mkdir(path.dirname(file), { recursive: true, mode: 0o700 });
+  let handle;
+  const token = randomUUID();
+  while (!handle) {
+    if (Date.now() >= deadline) throw lockTimeoutError(file);
+    try {
+      handle = await open(file, 'wx', 0o600);
+      await handle.writeFile(JSON.stringify({ pid: process.pid, token, startedAt: Date.now() }));
+      await handle.sync();
+    } catch (error) {
+      if (error.code !== 'EEXIST') {
+        await handle?.close().catch(() => {});
+        handle = undefined;
+        await rm(file, { force: true }).catch(() => {});
+        throw error;
+      }
+      let owner;
+      let observed;
+      try { observed = await readFile(file, 'utf8'); owner = JSON.parse(observed); } catch {}
+      const abandoned = owner?.pid ? !processAlive(owner.pid) : await stat(file)
+        .then((details) => Date.now() - details.mtimeMs >= (options.staleLockAge ?? 5000))
+        .catch(() => false);
+      if (abandoned) {
+        await options.afterStaleLockCheck?.({ file, owner });
+        // Recovery itself is serialized. Never rename/unlink the contested
+        // pathname after inspecting it: another contender may have replaced
+        // that pathname with a fresh lock in the meantime.
+        let recovery;
+        try { recovery = await open(`${file}.recovery`, 'wx', 0o600); }
+        catch (lockError) {
+          if (lockError.code !== 'EEXIST') throw lockError;
+          await new Promise((resolve) => setTimeout(resolve, Math.min(options.pollInterval ?? 40, Math.max(1, deadline - Date.now()))));
+          continue;
+        }
+        const recoveryToken = JSON.stringify({ pid: process.pid, token: randomUUID() });
+        try {
+          await recovery.writeFile(recoveryToken);
+          await recovery.sync();
+          const latest = await readFile(file, 'utf8').catch(() => '');
+          let latestOwner;
+          try { latestOwner = JSON.parse(latest); } catch {}
+          if (latest === observed) {
+            const stillAbandoned = latestOwner?.pid
+              ? !processAlive(latestOwner.pid)
+              : await stat(file).then((details) => Date.now() - details.mtimeMs >= (options.staleLockAge ?? 5000)).catch(() => false);
+            if (stillAbandoned) await rm(file, { force: true });
+          }
+        } finally {
+          const currentRecovery = await readFile(`${file}.recovery`, 'utf8').catch(() => '');
+          try { if (currentRecovery === recoveryToken) await rm(`${file}.recovery`, { force: true }); } catch {}
+          await recovery.close();
+        }
+        continue;
+      }
+      if (Date.now() >= deadline) throw lockTimeoutError(file, owner);
+      await new Promise((resolve) => setTimeout(resolve, Math.min(options.pollInterval ?? 40, Math.max(1, deadline - Date.now()))));
+    }
+  }
+  try { return await action(); }
+  finally {
+    const owner = await readFile(file, 'utf8').catch(() => '');
+    try { if (JSON.parse(owner).token === token) await rm(file, { force: true }); } catch {}
+    await handle.close();
+  }
+}
+
+function lockTimeoutError(file, owner) {
+  const recovery = `${file}.recovery`;
+  return new Error(`Timed out waiting for CTG runtime lock ${file}${owner?.pid ? ` held by process ${owner.pid}` : ''}. If no CTG process is recovering it, inspect and remove the stale lock/recovery files (${file} and ${recovery}) before retrying.`);
+}
+
+export function processAlive(pid) {
+  try { process.kill(pid, 0); return true; }
+  catch (error) { return error.code === 'EPERM'; }
+}
+
+/** 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'] });
+    let stdout = '';
+    let stderr = '';
+    const cap = options.maxOutput ?? 256 * 1024;
+    child.stdout.setEncoding('utf8').on('data', (chunk) => { stdout = (stdout + chunk).slice(-cap); });
+    child.stderr.setEncoding('utf8').on('data', (chunk) => { stderr = (stderr + chunk).slice(-cap); });
+    const timer = setTimeout(() => { child.kill('SIGTERM'); reject(new Error(`${command} timed out after ${options.timeout ?? 30000}ms`)); }, options.timeout ?? 30000);
+    child.once('error', (error) => { clearTimeout(timer); reject(error); });
+    child.once('close', (code, signal) => {
+      clearTimeout(timer);
+      if (code === 0) resolve({ stdout, stderr, code });
+      else reject(new Error(`${command} exited ${code ?? signal}: ${(stderr || stdout).trim().slice(-4000)}`));
+    });
+  });
+}
+
+/** Preserve workspace authentication/environment: do not apply CTG host XDG overrides. */
+export function workspaceEnvironment(workspace, env = process.env) {
+  return { ...env, CTG_WORKSPACE: abs(workspace) };
+}
+
+export async function readRuntimeCredentials(options = {}) {
+  const file = runtimePaths(options).credentials;
+  try { return JSON.parse(await readFile(file, 'utf8')); }
+  catch (error) { if (error.code === 'ENOENT') return {}; throw error; }
+}