carthagent 1.0.7 → 1.1.0-preview.12

package/lib/opencode/review.mjs

@@ -4,27 +4,44 @@ import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { resolve } from 'node:path';
 import { beginReview, parseFindings } from '../review-state.mjs';
+import { withoutRuntimeGithubToken } from '../environment.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');
+  if (!match) throw Object.assign(Error('Reviewer output must end with an exact structured VERDICT line'), { exitCode: 2 });
   return match[1];
 }
 
+function reviewContractError(error) {
+  if (Number.isInteger(error?.exitCode)) return error;
+  if (/^Missing structured REVIEW_JSON|^Invalid REVIEW_JSON|^Invalid or stale structured review identity|^Malformed structured finding|^Verdict contradicts structured findings/.test(String(error?.message || ''))) {
+    error.exitCode = 2;
+  }
+  return error;
+}
+
+function beginReviewChecked(...args) {
+  try { return beginReview(...args); }
+  catch (error) {
+    if (/review round limit|already approved|invalid persisted review state|review already running|interrupted review/i.test(String(error?.message || ''))) error.exitCode = 2;
+    throw error;
+  }
+}
+
 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();
+  const untracked = execFileSync('git', ['ls-files', '--others', '--exclude-standard', '-z'], { cwd: root, encoding: 'utf8', env: withoutRuntimeGithubToken() }).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 head = execFileSync('git', ['rev-parse', 'HEAD'], { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], env: withoutRuntimeGithubToken() }).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'] });
+    const output = execFileSync('git', args, { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], env: withoutRuntimeGithubToken() });
     return options ? output : output.trim();
   };
   return { head, snapshot: createReviewSnapshot({ source: localSource(root, git), head }) };
@@ -72,7 +89,7 @@ async function interruptReviewer(ctx, sessionID) {
 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`);
+  if (!Array.isArray(agents) || !agents.some(item => item.id === agent)) throw Error(`Reviewer agent ${agent} is not registered at this Carthagent runtime location`);
   return agent;
 }
 
@@ -116,13 +133,13 @@ export async function startReview({ ctx, cwd, identity = 'local-delivery', model
   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'] });
+    const output = execFileSync('git', args, { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], env: withoutRuntimeGithubToken() });
     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);
+  const admission = beginReviewChecked(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.`;
@@ -130,10 +147,12 @@ export async function startReview({ ctx, cwd, identity = 'local-delivery', model
     reviewer = result.reviewer;
     const output = result.output;
     const verdict = reviewVerdict(output);
-    const findings = parseFindings(output, snapshot, head, verdict);
+    let findings;
+    try { findings = parseFindings(output, snapshot, head, verdict); }
+    catch (error) { throw reviewContractError(error); }
     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');
+    if (currentHead !== head || createReviewSnapshot({ source: currentSource, head: currentHead }) !== snapshot) throw Object.assign(Error('Local review source or HEAD moved while review was running'), { exitCode: 2 });
     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 };
@@ -144,7 +163,7 @@ export async function startReview({ ctx, cwd, identity = 'local-delivery', model
 }
 
 function commandOutput(command, args, cwd, { trim = true } = {}) {
-  const result = execFileSync(command, args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+  const result = execFileSync(command, args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], env: withoutRuntimeGithubToken() });
   const output = Buffer.isBuffer(result) ? result.toString('utf8') : String(result);
   return trim ? output.trim() : output;
 }
@@ -171,11 +190,11 @@ function authoritativePR({ cwd, repository, prNumber }) {
   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');
+  if (git('rev-parse', headRef) !== remoteHead || git('rev-parse', baseRef) !== baseHead) throw Object.assign(Error('Fetched GitHub branch refs do not match the authoritative pull request commit IDs'), { exitCode: 2 });
+  if (localHead !== remoteHead) throw Object.assign(Error('Local HEAD does not match the authoritative GitHub PR head'), { exitCode: 2 });
   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');
+  if (git('rev-parse', `${remoteHead}^{commit}`) !== remoteHead || git('rev-parse', `${baseHead}^{commit}`) !== baseHead) throw Object.assign(Error('Fetched Git objects do not match the authoritative GitHub PR commits'), { exitCode: 2 });
   return { repository: repository.toLowerCase(), prNumber, localHead, remoteHead, baseHead, headRepository: headRepository.toLowerCase(), source };
 }
 
@@ -188,16 +207,18 @@ export async function startPullRequestReview({ ctx, cwd, repository, prNumber, m
   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);
+  const admission = beginReviewChecked(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);
+    let findings;
+    try { findings = parseFindings(output, snapshot, head, verdict); }
+    catch (error) { throw reviewContractError(error); }
     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');
+    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 Object.assign(Error('Authoritative GitHub PR refs or source moved while review was running'), { exitCode: 2 });
     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) {

package/lib/opencode/runtime-artifact.mjs

@@ -0,0 +1,335 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { createReadStream, createWriteStream } from 'node:fs';
+import { chmod, lstat, mkdir, open, readFile, rename, rm } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import path from 'node:path';
+import { Transform } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { createGunzip } from 'node:zlib';
+import { withFileLock } from './runtime.mjs';
+
+const MANIFEST_NAME = 'ctg-runtime.json';
+const MAX_ARCHIVE_BYTES = 512 * 1024 * 1024;
+const MAX_EXPANDED_BYTES = 1024 * 1024 * 1024;
+const MAX_ENTRIES = 20_000;
+const DEFAULT_ROOT = path.join(homedir(), '.carthagent', 'opencode', 'runtimes');
+
+const TARGETS = Object.freeze({
+  'linux-x64': { platform: 'linux', arch: 'x64', executable: 'bin/opencode' },
+  'linux-arm64': { platform: 'linux', arch: 'arm64', executable: 'bin/opencode' },
+  'darwin-x64': { platform: 'darwin', arch: 'x64', executable: 'bin/opencode' },
+  'darwin-arm64': { platform: 'darwin', arch: 'arm64', executable: 'bin/opencode' },
+  'windows-x64': { platform: 'windows', arch: 'x64', executable: 'bin/opencode.exe' },
+  'windows-arm64': { platform: 'windows', arch: 'arm64', executable: 'bin/opencode.exe' },
+});
+
+/**
+ * Acquire one immutable CTG release artifact. All expected digests and runtime
+ * identity fields must come from the caller's packaged, pinned runtime-release
+ * manifest; this function never consults a latest-version pointer or treats a
+ * downloaded checksum/manifest as a trust anchor.
+ * Returns the installed artifact root containing ctg-runtime.json,
+ * SHA256SUMS, and cli-<platform>-<arch>/bin/opencode.
+ */
+export async function acquireOwnedRuntime(options = {}) {
+  const releaseVersion = validateVersion(options.releaseVersion);
+  const target = resolveTarget(options.platform, options.arch);
+  const assetName = options.assetName ?? `opencode-${target.key}.tar.gz`;
+  if (assetName !== `opencode-${target.key}.tar.gz`) throw new TypeError(`assetName must be opencode-${target.key}.tar.gz`);
+  const archiveSha256 = validateSha256(options.expectedArchiveSha256, 'expectedArchiveSha256');
+  const expected = {
+    platform: `${target.platform}-${target.arch}`,
+    sourceRevision: validateRevision(options.expectedSourceRevision),
+    patchSha256: validateSha256(options.expectedPatchSha256, 'expectedPatchSha256'),
+    lockSha256: validateSha256(options.expectedLockSha256, 'expectedLockSha256'),
+    compatibilityVersion: validateText(options.expectedCompatibilityVersion, 'expectedCompatibilityVersion'),
+    runtimeVersion: validateText(options.expectedRuntimeVersion, 'expectedRuntimeVersion'),
+    channel: validateText(options.expectedChannel, 'expectedChannel'),
+    executableSha256: validateSha256(options.expectedExecutableSha256, 'expectedExecutableSha256'),
+  };
+  const baseUrl = validateBaseUrl(options.baseUrl);
+  const root = path.resolve(options.cacheRoot ?? DEFAULT_ROOT);
+  const releaseDir = path.join(root, releaseVersion, target.key);
+  const lockPath = path.join(root, '.locks', `${releaseVersion}-${target.key}.lock`);
+  await mkdir(root, { recursive: true, mode: 0o700 });
+
+  return withFileLock(lockPath, async () => {
+    // Cached checksums cannot be trusted: they live inside the writable cache.
+    // Always compare executable bytes to the independently pinned digest.
+    const existing = await validateInstalled(releaseDir, expected, target).catch(() => null);
+    if (existing) return existing;
+
+    const stageDir = path.join(root, '.staging', `${releaseVersion}-${target.key}-${randomUUID()}`);
+    await mkdir(stageDir, { recursive: true, mode: 0o700 });
+    try {
+      const archive = path.join(stageDir, assetName);
+      await downloadArchive(new URL(encodeURIComponent(assetName), `${baseUrl}/`), archive, options.fetchImpl ?? fetch, options.signal);
+      const actualArchiveHash = await hashFile(archive);
+      if (actualArchiveHash !== archiveSha256) {
+        throw new Error(`CTG Carthagent runtime ${releaseVersion} ${target.key} archive SHA-256 mismatch (expected ${archiveSha256}, got ${actualArchiveHash}).`);
+      }
+      const contentDir = path.join(stageDir, 'unpacked');
+      await mkdir(contentDir, { mode: 0o700 });
+      await unpackTarGz(archive, contentDir, target);
+      await validateInstalled(contentDir, expected, target);
+      await mkdir(path.dirname(releaseDir), { recursive: true, mode: 0o700 });
+      const previousDir = `${releaseDir}.replaced-${randomUUID()}`;
+      let movedPrevious = false;
+      try {
+        await rename(releaseDir, previousDir);
+        movedPrevious = true;
+      } catch (error) {
+        if (error.code !== 'ENOENT') throw error;
+      }
+      try {
+        await rename(contentDir, releaseDir);
+      } catch (error) {
+        if (movedPrevious) await rename(previousDir, releaseDir).catch(() => {});
+        throw error;
+      }
+      if (movedPrevious) await rm(previousDir, { recursive: true, force: true });
+      await chmod(releaseDir, 0o700).catch(() => {});
+      return releaseDir;
+    } catch (error) {
+      throw new Error(`Could not acquire CTG-owned Carthagent runtime ${releaseVersion} for ${target.key}: ${error.message}. Check network access or remove the incomplete cache and retry; no system Carthagent runtime fallback was attempted.`, { cause: error });
+    } finally {
+      await rm(stageDir, { recursive: true, force: true }).catch(() => {});
+    }
+  }, { timeout: options.lockTimeout ?? 60_000 });
+}
+
+function validateVersion(value) {
+  if (typeof value !== 'string' || !/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/.test(value)) {
+    throw new TypeError('releaseVersion must be an exact semantic version (without a v prefix).');
+  }
+  return value;
+}
+function validateRevision(value) {
+  if (typeof value !== 'string' || !/^[a-f0-9]{40,64}$/i.test(value)) {
+    throw new TypeError('expectedSourceRevision must be a pinned 40- to 64-character hexadecimal revision.');
+  }
+  return value.toLowerCase();
+}
+function validateText(value, name) {
+  if (typeof value !== 'string' || !value.trim() || value.includes('\0')) throw new TypeError(`${name} must be a non-empty pinned string.`);
+  return value;
+}
+function validateSha256(value, name) {
+  if (typeof value !== 'string' || !/^[a-f0-9]{64}$/i.test(value)) throw new TypeError(`${name} must be a pinned 64-character SHA-256 hex digest.`);
+  return value.toLowerCase();
+}
+function resolveTarget(platform = process.platform, arch = process.arch) {
+  const key = `${platform}-${arch}`;
+  const normalized = ({ 'win32-x64': 'windows-x64', 'win32-arm64': 'windows-arm64' })[key] ?? key;
+  const target = TARGETS[normalized];
+  if (!target) throw new Error(`Unsupported CTG Carthagent runtime release target ${key}.`);
+  return { ...target, key: normalized };
+}
+function validateBaseUrl(value) {
+  let url;
+  try { url = new URL(value); } catch { throw new TypeError('baseUrl must be an HTTPS release asset base URL.'); }
+  if (url.protocol !== 'https:' && !['localhost', '127.0.0.1', '[::1]'].includes(url.hostname)) {
+    throw new TypeError('baseUrl must use HTTPS (HTTP is allowed only for loopback fixture servers).');
+  }
+  if (url.username || url.password || url.search || url.hash) throw new TypeError('baseUrl must not contain credentials, a query, or a fragment.');
+  return url.toString().replace(/\/+$/, '');
+}
+
+async function downloadArchive(url, destination, fetchImpl, signal) {
+  const timeout = AbortSignal.timeout(120_000);
+  const requestSignal = signal ? AbortSignal.any([signal, timeout]) : timeout;
+  let response;
+  for (let redirects = 0; redirects <= 5; redirects++) {
+    response = await fetchImpl(url, { redirect: 'manual', signal: requestSignal });
+    if (![301, 302, 303, 307, 308].includes(response.status)) break;
+    const location = response.headers.get('location');
+    await response.body?.cancel().catch(() => {});
+    if (!location || redirects === 5) throw new Error('release asset returned a missing or excessive redirect chain');
+    const next = new URL(location, url);
+    if (next.protocol !== 'https:' && !['localhost', '127.0.0.1', '[::1]'].includes(next.hostname)) {
+      throw new Error('release asset redirect attempted an insecure non-loopback URL');
+    }
+    if (next.username || next.password) throw new Error('release asset redirect included URL credentials');
+    url = next;
+  }
+  if (!response.ok || !response.body) throw new Error(`release asset request failed with HTTP ${response.status}`);
+  const length = Number(response.headers.get('content-length'));
+  if (Number.isFinite(length) && length > MAX_ARCHIVE_BYTES) throw new Error(`release archive exceeds the ${MAX_ARCHIVE_BYTES}-byte download limit`);
+  let bytes = 0;
+  const limiter = new Transform({ transform(chunk, _encoding, callback) {
+    bytes += chunk.length;
+    callback(bytes > MAX_ARCHIVE_BYTES ? new Error(`release archive exceeds the ${MAX_ARCHIVE_BYTES}-byte download limit`) : null, chunk);
+  } });
+  await pipeline(response.body, limiter, createWriteStream(destination, { flags: 'wx', mode: 0o600 }));
+}
+
+async function hashFile(file) {
+  const hash = createHash('sha256');
+  const stream = createReadStream(file);
+  for await (const chunk of stream) hash.update(chunk);
+  return hash.digest('hex');
+}
+
+async function validateInstalled(directory, expected, target) {
+  const manifestPath = path.join(directory, MANIFEST_NAME);
+  const manifest = JSON.parse(await readFile(manifestPath, 'utf8'));
+  const required = {
+    owner: 'Carthagent',
+    sourceRepository: 'https://github.com/anomalyco/opencode',
+    sourceRevision: expected.sourceRevision,
+    lockSha256: expected.lockSha256,
+    patchSha256: expected.patchSha256,
+    compatibilityVersion: expected.compatibilityVersion,
+    runtimeVersion: expected.runtimeVersion,
+    channel: expected.channel,
+    platform: expected.platform,
+    webUI: false,
+  };
+  for (const [key, value] of Object.entries(required)) {
+    if (manifest[key] !== value) throw new Error(`inner runtime manifest ${key} mismatch`);
+  }
+  const executablePath = `cli-${target.key}/${target.executable}`;
+  const safePath = safeArchivePath(executablePath);
+  const executable = path.join(directory, ...safePath.split('/'));
+  const details = await lstat(executable);
+  if (!details.isFile() || details.isSymbolicLink()) throw new Error('manifest executable is not a regular file');
+  const sums = await readFile(path.join(directory, 'SHA256SUMS'), 'utf8');
+  const checksum = sums.split(/\r?\n/).map((line) => line.trim().split(/\s+/))
+    .find(([hash, name]) => /^[a-f0-9]{64}$/i.test(hash ?? '') && name?.replace(/^\*?/, '') === executablePath)?.[0];
+  if (!checksum) throw new Error(`SHA256SUMS does not list ${executablePath}`);
+  const executableHash = validateSha256(checksum, 'SHA256SUMS executable entry');
+  if (executableHash !== expected.executableSha256) throw new Error('SHA256SUMS executable hash does not match pinned release metadata');
+  if (await hashFile(executable) !== expected.executableSha256) throw new Error('inner runtime executable SHA-256 mismatch');
+  // Windows filesystems do not expose POSIX executable bits. The Unix target's
+  // USTAR header is checked during extraction on every host; use cached stat
+  // mode only when the host filesystem can represent it.
+  if (process.platform !== 'win32' && target.platform !== 'windows' && !(details.mode & 0o111)) {
+    throw new Error('inner runtime executable is not marked executable');
+  }
+  return directory;
+}
+
+// Deliberately small ustar reader: it accepts only regular files/directories,
+// never invokes a system tar program, and rejects links and unsafe names.
+async function unpackTarGz(archive, destination, target) {
+  let expandedBytes = 0;
+  let entries = 0;
+  let buffered = Buffer.alloc(0);
+  let pending = null;
+  let ended = false;
+  let decompressedBytes = 0;
+  const gunzip = createGunzip();
+  const input = createReadStream(archive).pipe(gunzip);
+  const consume = async (chunk) => {
+    decompressedBytes += chunk.length;
+    if (decompressedBytes > MAX_EXPANDED_BYTES) throw new Error('decompressed archive exceeds the size limit');
+    if (ended) {
+      if (chunk.some((byte) => byte !== 0)) throw new Error('tar archive has non-zero data after its end marker');
+      return;
+    }
+    buffered = Buffer.concat([buffered, chunk]);
+    while (true) {
+      if (pending) {
+        const take = Math.min(pending.remaining, buffered.length);
+        if (take) {
+          await pending.handle.write(buffered.subarray(0, take));
+          buffered = buffered.subarray(take);
+          pending.remaining -= take;
+        }
+        if (pending.remaining) return;
+        await pending.handle.sync(); await pending.handle.close(); pending = null;
+        const padding = (512 - (pendingSize % 512)) % 512;
+        if (buffered.length < padding) {
+          pendingPadding = padding - buffered.length;
+          buffered = Buffer.alloc(0);
+          return;
+        }
+        buffered = buffered.subarray(padding);
+        continue;
+      }
+      if (pendingPadding) {
+        const take = Math.min(pendingPadding, buffered.length);
+        buffered = buffered.subarray(take); pendingPadding -= take;
+        if (pendingPadding) return;
+        continue;
+      }
+      if (buffered.length < 512) return;
+      const header = buffered.subarray(0, 512); buffered = buffered.subarray(512);
+      if (header.every((byte) => byte === 0)) {
+        ended = true;
+        if (buffered.some((byte) => byte !== 0)) throw new Error('tar archive has non-zero data after its end marker');
+        return;
+      }
+      validateTarChecksum(header);
+      entries++;
+      if (entries > MAX_ENTRIES) throw new Error('archive contains too many entries');
+      const name = tarString(header, 0, 100);
+      const prefix = tarString(header, 345, 155);
+      const rawRelative = prefix ? `${prefix}/${name}` : name;
+      const type = header[156];
+      const size = parseTarOctal(header.subarray(124, 136));
+      const mode = parseTarOctal(header.subarray(100, 108)) & 0o777;
+      expandedBytes += size;
+      if (expandedBytes > MAX_EXPANDED_BYTES) throw new Error('expanded archive exceeds the size limit');
+      // GNU tar commonly archives `.` as a top-level directory entry.
+      if ((rawRelative === '.' || rawRelative === './') && (type === 53 || type === 0) && size === 0) continue;
+      const relative = safeArchivePath(rawRelative);
+      const archivePath = relative.replace(/^(?:\.\/)+/, '');
+      const output = path.join(destination, ...relative.split('/'));
+      if (type === 53 || (type === 0 && relative.endsWith('/'))) {
+        if (size) throw new Error(`directory entry ${relative} unexpectedly contains data`);
+        await mkdir(output, { recursive: true, mode: 0o700 });
+        continue;
+      }
+      if (type === 120 || type === 103) throw new Error('archive uses a PAX extension; CTG runtime release archives must use USTAR format');
+      if (type !== 0 && type !== 48) throw new Error(`archive contains unsupported link or special entry ${relative}`);
+      if (target.platform !== 'windows' && archivePath === `cli-${target.key}/${target.executable}` && !(mode & 0o111)) {
+        throw new Error('inner runtime executable is not marked executable');
+      }
+      await mkdir(path.dirname(output), { recursive: true, mode: 0o700 });
+      const handle = await open(output, 'wx', mode & 0o111 ? 0o700 : 0o600);
+      pendingSize = size;
+      pendingPadding = 0;
+      pending = { handle, remaining: size, output };
+      if (!size) { await handle.close(); pending = null; pendingPadding = 0; }
+    }
+  };
+  let pendingSize = 0;
+  let pendingPadding = 0;
+  try {
+    for await (const chunk of input) await consume(chunk);
+    if (pending) { await pending.handle.close().catch(() => {}); throw new Error(`truncated archive file ${pending.output}`); }
+    if (pendingPadding || (!ended && buffered.length)) throw new Error('truncated tar archive');
+    if (!ended) throw new Error('tar archive has no end marker');
+  } catch (error) {
+    await pending?.handle.close().catch(() => {});
+    throw error;
+  } finally { input.destroy(); }
+}
+
+function safeArchivePath(value) {
+  if (typeof value !== 'string' || !value || value.includes('\0') || value.includes('\\') || value.startsWith('/') || /^[a-zA-Z]:/.test(value)) {
+    throw new Error(`unsafe archive path: ${JSON.stringify(value)}`);
+  }
+  const parts = value.replace(/\/$/, '').split('/');
+  if (parts.some((part) => !part || part === '..')) throw new Error(`unsafe archive path: ${JSON.stringify(value)}`);
+  return parts.join('/');
+}
+function tarString(header, start, length) {
+  const end = header.indexOf(0, start);
+  return header.subarray(start, end >= start && end < start + length ? end : start + length).toString('utf8');
+}
+function parseTarOctal(value) {
+  const text = value.toString('ascii').replace(/\0.*$/, '').trim();
+  if (!text) return 0;
+  if (!/^[0-7]+$/.test(text)) throw new Error('archive has invalid tar numeric field');
+  const parsed = Number.parseInt(text, 8);
+  if (!Number.isSafeInteger(parsed)) throw new Error('archive tar numeric field exceeds supported range');
+  return parsed;
+}
+function validateTarChecksum(header) {
+  const expected = parseTarOctal(header.subarray(148, 156));
+  let actual = 0;
+  for (let index = 0; index < 512; index++) actual += index >= 148 && index < 156 ? 32 : header[index];
+  if (actual !== expected) throw new Error('archive tar header checksum is invalid');
+}

package/lib/opencode/runtime-github-transport.mjs

@@ -0,0 +1,121 @@
+const API_ROOT = 'https://api.github.com/repos/B-icy/Carthagent';
+const API_VERSION = '2022-11-28';
+const ASSET_NAMES = new Set([
+  'opencode-linux-x64.tar.gz',
+  'opencode-linux-arm64.tar.gz',
+  'opencode-darwin-x64.tar.gz',
+  'opencode-darwin-arm64.tar.gz',
+  'opencode-windows-x64.tar.gz',
+]);
+const MAX_RELEASE_PAGES = 20;
+const MAX_ASSET_PAGES = 20;
+
+/**
+ * Add opt-in authenticated access to one exact Carthagent release asset.
+ * The credential is used only for fixed api.github.com GET requests. Redirects
+ * are left to the ordinary downloader, which calls this wrapper again without
+ * credentials for every non-canonical URL.
+ */
+export function createRuntimeGithubFetch({ token, fetchImpl = globalThis.fetch } = {}) {
+  if (typeof token !== 'string' || !token.trim()) throw new TypeError('A non-empty GitHub token is required.');
+  if (typeof fetchImpl !== 'function') throw new TypeError('GitHub runtime transport requires fetch support.');
+
+  return async (input, init = {}) => {
+    const requested = new URL(input);
+    const match = requested.href.match(/^https:\/\/github\.com\/B-icy\/Carthagent\/releases\/download\/v(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?)\/([^/?#]+)$/);
+    if (!match || requested.search || requested.hash) return fetchImpl(input, init);
+
+    const [, version, encodedName] = match;
+    let assetName;
+    try { assetName = decodeURIComponent(encodedName); }
+    catch { throw new Error('Invalid encoded Carthagent runtime asset URL.'); }
+    // Non-runtime assets use the ordinary URL transport. Only this strict
+    // allowlist is eligible for credentials or draft lookup.
+    if (!ASSET_NAMES.has(assetName) || encodeURIComponent(assetName) !== encodedName) return fetchImpl(input, init);
+
+    const release = await findRelease({ version, token, fetchImpl, signal: init.signal });
+    const asset = await findAsset({ release, assetName, token, fetchImpl, signal: init.signal });
+    const response = await apiGet(`${API_ROOT}/releases/assets/${asset.id}`, token, fetchImpl, init.signal, 'application/octet-stream');
+    // GitHub may stream the bytes or redirect to a signed CDN URL. Keep the
+    // redirect manual so the downloader re-requests it without this token.
+    return response;
+  };
+}
+
+async function findRelease({ version, token, fetchImpl, signal }) {
+  const expectedTag = `v${version}`;
+  const matches = [];
+  for (let page = 1; page <= MAX_RELEASE_PAGES; page++) {
+    const result = await apiJson(`${API_ROOT}/releases?per_page=100&page=${page}`, token, fetchImpl, signal);
+    if (!Array.isArray(result)) throw new Error('GitHub returned invalid release-list metadata.');
+    matches.push(...result.filter((item) => item?.tag_name === expectedTag));
+    if (result.length < 100) {
+      if (matches.length !== 1) throw new Error(matches.length ? 'GitHub returned duplicate exact-version releases.' : 'The exact Carthagent runtime release was not found.');
+      const release = matches[0];
+      if (!Number.isSafeInteger(release.id) || release.id <= 0) throw new Error('GitHub returned invalid exact-version release metadata.');
+      return release;
+    }
+  }
+  throw new Error('GitHub release pagination exceeded its safety limit.');
+}
+
+async function findAsset({ release, assetName, token, fetchImpl, signal }) {
+  const matches = [];
+  for (let page = 1; page <= MAX_ASSET_PAGES; page++) {
+    const url = `${API_ROOT}/releases/${release.id}/assets?per_page=100&page=${page}`;
+    const result = await apiJson(url, token, fetchImpl, signal);
+    if (!Array.isArray(result)) throw new Error('GitHub returned invalid release-asset metadata.');
+    matches.push(...result.filter((item) => item?.name === assetName));
+    if (result.length < 100) {
+      if (matches.length !== 1) throw new Error(matches.length ? `GitHub returned duplicate ${assetName} assets.` : `The exact Carthagent runtime asset ${assetName} was not found.`);
+      const asset = matches[0];
+      const canonicalAssetUrl = `${API_ROOT}/releases/assets/${asset.id}`;
+      if (!Number.isSafeInteger(asset.id) || asset.id <= 0
+        || asset.state !== 'uploaded'
+        || !Number.isSafeInteger(asset.size) || asset.size <= 0
+        || asset.url !== canonicalAssetUrl) {
+        throw new Error(`GitHub returned invalid metadata for ${assetName}.`);
+      }
+      return asset;
+    }
+  }
+  throw new Error('GitHub release-asset pagination exceeded its safety limit.');
+}
+
+async function apiJson(url, token, fetchImpl, signal) {
+  const response = await apiGet(url, token, fetchImpl, signal, 'application/vnd.github+json');
+  if (response.status >= 300 && response.status < 400) {
+    await response.body?.cancel().catch(() => {});
+    throw new Error('GitHub API unexpectedly redirected a metadata request.');
+  }
+  if (!response.ok) throw new Error(`GitHub API metadata request failed with HTTP ${response.status}.`);
+  try { return await response.json(); }
+  catch { throw new Error('GitHub API returned invalid JSON metadata.'); }
+}
+
+async function apiGet(url, token, fetchImpl, signal, accept) {
+  let parsed;
+  try { parsed = new URL(url); }
+  catch { throw new Error('Invalid GitHub API request URL.'); }
+  if (parsed.origin !== 'https://api.github.com' || !parsed.pathname.startsWith('/repos/B-icy/Carthagent/')) {
+    throw new Error('Runtime transport refused a noncanonical GitHub API URL.');
+  }
+  let response;
+  try {
+    response = await fetchImpl(parsed, {
+      method: 'GET',
+      redirect: 'manual',
+      ...(signal ? { signal } : {}),
+      headers: {
+        accept,
+        authorization: `Bearer ${token}`,
+        'x-github-api-version': API_VERSION,
+      },
+    });
+  } catch {
+    // Do not propagate fetch errors or causes: an injected adapter may include
+    // request headers in its diagnostic text.
+    throw new Error('GitHub API request failed before a response was received.');
+  }
+  return response;
+}

package/lib/opencode/runtime-release.json

@@ -0,0 +1,36 @@
+{
+  "version": 1,
+  "releaseVersion": "1.1.0-preview.12",
+  "compatibilityVersion": "2.0.32",
+  "runtimeVersion": "0.0.0-ctg.2.0.32",
+  "sourceRevision": "843a6c514e606b436a7fe713422ace0a93ad3d61",
+  "patchSha256": "1f2309bb3a31dfb8e8a0827a6a1144a1f76a005abff58f6f48857639ec02478a",
+  "lockSha256": "9d78379cd264584a495440a217b9d2ecab524c9a56f7f8b4b5bed3926daa330d",
+  "assets": {
+    "linux-x64": {
+      "name": "opencode-linux-x64.tar.gz",
+      "archiveSha256": "d4c202e0825fc77321ccd23d91a7baede4951a4eb4cee28f258c171e72f03852",
+      "executableSha256": "24bcfff03d32db163e0d40c4d0b212eede300a71a3dc26aa23810b9088d52280"
+    },
+    "linux-arm64": {
+      "name": "opencode-linux-arm64.tar.gz",
+      "archiveSha256": "c3a1e68a6fd7db5909d2d38639c5b1e8df7a5de64fc40f6cc758211a280ea058",
+      "executableSha256": "b73708103d62de570e629a0bf9c2bce9b1a4db0a87a79b1c86c2d2ebe998db7b"
+    },
+    "darwin-x64": {
+      "name": "opencode-darwin-x64.tar.gz",
+      "archiveSha256": "d733d269bd06a652c858b62b24e5b78a629400fc687d7dc71a999bb03bfab1d5",
+      "executableSha256": "f2bb0e772744bc04b96368d32cc35582a6a1bca0be795897704c9395e5059f37"
+    },
+    "darwin-arm64": {
+      "name": "opencode-darwin-arm64.tar.gz",
+      "archiveSha256": "e0a0ac4c7f5b4d14eab8844428d717a9a596c61694b318d0e065080de5a42fda",
+      "executableSha256": "9bf83ef1fd9e1af8028a23941a05195f8256847deae271c2b016014d5363605b"
+    },
+    "windows-x64": {
+      "name": "opencode-windows-x64.tar.gz",
+      "archiveSha256": "0318a74ba0b67ee5119b4289c0b78124c620676c8770e48c24d347513e96e2aa",
+      "executableSha256": "b057ce293492cff6dabf3939d12072798f53d8b4cf7ab944fd97ef0bb0879bb9"
+    }
+  }
+}