carthagent 1.0.7 → 1.1.0-beta.1

package/lib/opencode/cli.mjs

@@ -0,0 +1,252 @@
+/**
+ * OpenCode-facing command-line adapter.
+ *
+ * The CLI deliberately depends on a small runtime port rather than importing
+ * OpenCode implementation modules. The native service owns process startup,
+ * authentication, model discovery, and session execution; this module owns
+ * stable ctg argv compatibility and output/exit-code behavior.
+ */
+
+const VALUE_FLAGS = new Map([
+  ['--provider', 'provider'], ['--model', 'model'], ['--thinking', 'thinking'],
+  ['--theme', 'theme'], ['--engine-cli', 'engineCli'], ['--agent-cli', 'engineCli'],
+  ['--session', 'session'], ['--validators', 'validators'], ['--context', 'context'],
+  ['--bash-cap', 'bashCap'], ['--max-tools', 'maxTools'], ['--max-seconds', 'maxSeconds'],
+  ['--max-repairs', 'maxRepairs'], ['--review', 'review'], ['--glyphs', 'glyphs'],
+  ['--codegraph-max-files', 'codegraphMaxFiles'], ['--workflow', 'workflow'],
+  ['--rewrite-cap', 'rewriteCap'], ['--tool-output-cap', 'toolOutputCap'], ['--turn-delay-ms', 'turnDelayMs'],
+  ['--jev-provider', 'jevProvider'],
+]);
+
+const BOOL_FLAGS = new Map([
+  ['--isolate', ['isolate', true]], ['--strict', ['strict', true]], ['--no-strict', ['strict', false]],
+  ['--no-delivery', ['delivery', false]], ['--delivery', ['delivery', true]],
+  ['--no-guide', ['autoFraming', false]], ['--guide', ['autoFraming', true]],
+  ['--ascii', ['ascii', true]], ['--json', ['json', true]], ['-p', ['print', true]],
+  ['--protect-existing', ['protectExisting', true]], ['--jev', ['jev', true]], ['--no-jev', ['jev', false]],
+  ['--print', ['print', true]], ['--demo', ['demo', true]], ['-c', ['continue', true]],
+  ['--continue', ['continue', true]], ['-r', ['resume', true]], ['--resume', ['resume', true]],
+]);
+
+const aliases = new Map([
+  ['ui', 'tui'], ['interactive', 'tui'], ['sessions', 'resume'], ['s', 'status'],
+  ['fingerprint', 'hash'], ['c', 'check'], ['auth', 'login'], ['cloud', 'account'], ['upgrade', 'update'],
+  ['archives', 'archive'],
+  ['web', 'serve'], ['start', 'serve'],
+]);
+
+export function parseOpenCodeArgs(argv) {
+  const options = {};
+  const prompt = [];
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--') {
+      prompt.push(...argv.slice(i + 1));
+      break;
+    }
+    if (VALUE_FLAGS.has(arg)) {
+      const value = argv[++i];
+      if (value === undefined || value.startsWith('--')) throw new Error(`Missing value for ${arg}`);
+      options[VALUE_FLAGS.get(arg)] = value;
+      continue;
+    }
+    if (BOOL_FLAGS.has(arg)) {
+      const [key, value] = BOOL_FLAGS.get(arg);
+      options[key] = value;
+      continue;
+    }
+    if (arg.startsWith('-')) throw new Error(`Unknown flag: ${arg}`);
+    prompt.push(arg);
+  }
+  if (prompt.length) options.prompt = prompt.join(' ');
+  return options;
+}
+
+export function cliHelp(version = '') {
+  return `\n\x1b[1m\x1b[36mCarthagent\x1b[0m${version ? ` \x1b[90m${version}\x1b[0m` : ''} \x1b[2m(ctg)\x1b[0m
+
+\x1b[1mUSAGE:\x1b[0m
+  ctg                            Launch the native Carthagent delivery console
+  ctg <task>                     Start a session and deliver <task>
+  ctg --list-models [search]     List available provider models
+  ctg <command> [options]
+  ctg service stop        Stop this profile’s background service safely
+  ctg review workspace --request-file <task.txt> [--provider <name> --model <id>]
+
+\x1b[1mCOMMANDS:\x1b[0m
+  native [args]           Compatibility alias; native is now the default
+  \x1b[32mtui\x1b[0m, \x1b[32mui\x1b[0m                 Interactive console
+  \x1b[32mresume\x1b[0m, \x1b[32msessions\x1b[0m          Open the session picker
+  \x1b[32mcontinue\x1b[0m               Continue the most recent session
+  \x1b[32mdemo\x1b[0m                  Run the scripted demonstration
+  \x1b[32mstatus\x1b[0m, \x1b[32ms\x1b[0m             Display workspace fingerprint, contract and checks
+  \x1b[32mcheck\x1b[0m [id], \x1b[32mc\x1b[0m [id]     Execute a declared check
+  \x1b[32mhash\x1b[0m, \x1b[32mfingerprint\x1b[0m     Calculate workspace SHA-256 fingerprint
+  \x1b[32mvalidate\x1b[0m <file.json> Validate acceptance contract
+  \x1b[32mlogin\x1b[0m, \x1b[32mauth\x1b[0m             Connect an AI provider
+  \x1b[32maccount\x1b[0m               Show Ship credit, plan, grants and CLI sessions
+  \x1b[32mbilling\x1b[0m [checkout|portal] Open Ship billing
+  \x1b[32mlogout-cloud\x1b[0m [session] Revoke the current or named Ship session
+  \x1b[32marchive\x1b[0m [list|search|read|export] Read-only legacy session archive
+  \x1b[32mreview\x1b[0m                Configure self-review or review a PR
+  \x1b[32mserve\x1b[0m, \x1b[32mweb\x1b[0m, \x1b[32mstart\x1b[0m     Start the web dashboard
+  \x1b[32mtest\x1b[0m                   Run core tests
+  \x1b[32meval\x1b[0m [args...]         Run evaluation harness
+  \x1b[32mupdate\x1b[0m [--check] [--channel stable|beta|experimental]  Update Carthagent
+  \x1b[32mhelp\x1b[0m, \x1b[32m--help\x1b[0m, \x1b[32m-h\x1b[0m       Display this help
+
+\x1b[1mOPTIONS:\x1b[0m
+  --provider <name>       Provider for the agent
+  --model <id>            Model id or pattern
+  --thinking <level>      off|minimal|low|medium|high|xhigh|max
+  --theme <name>          Carthagent theme name
+  --engine-cli, --agent-cli <path>  Explicit native runtime executable override
+  --session <path|id>     Resume a specific session
+  --continue, -c          Resume the most recent session
+  --resume, -r            Open the session picker
+  --validators <file>     Required-validator manifest
+  --context <file>        Extra task context file
+  --bash-cap <sec>        Cap shell tool timeouts
+  --max-tools <n>          Session tool-call budget (0 disables)
+  --max-seconds <n>        Session elapsed-time budget (0 disables)
+  --max-repairs <n>        Automatic-repair budget (0 disables)
+  --protect-existing      Preserve files present at session start
+  --rewrite-cap <n>        Whole-file writes per path (0 disables)
+  --tool-output-cap <n>    Bound text output per tool result
+  --turn-delay-ms <n>      Pace tool loops
+  --jev, --no-jev          Enable/disable advisory plan analysis (on for Ship models)
+  --jev-provider <name>    ship|openrouter|typesafe
+  --review <mode>          Self-review: ask|yes|no
+  --isolate                Isolate extension/skill discovery (not a worktree)
+  --no-strict              Disable delivery-plan write gate
+  --no-delivery            Run without delivery behavior
+  --no-guide               Disable prompt framing
+  -p, --print              Headless text output
+  --json                   Headless JSONL events
+`;
+}
+
+const commandNames = new Set([
+  'tui', 'resume', 'continue', 'demo', 'status', 'hash', 'check', 'validate', 'login',
+  'account', 'billing', 'logout-cloud', 'archive', 'serve', 'test', 'eval', 'review', 'update', 'quit', 'q', 'exit',
+  'logout', 'service',
+]);
+
+function fail(message, code = 1, io = console) {
+  io.error(message);
+  return code;
+}
+
+function ensureMethod(runtime, method) {
+  if (typeof runtime?.[method] !== 'function') {
+    throw new Error(`Native Carthagent CLI runtime does not provide ${method}()`);
+  }
+  return runtime[method].bind(runtime);
+}
+
+/**
+ * Execute a CLI invocation using the native runtime port.
+ *
+ * Runtime contract (all operations are real operations, not optional no-ops):
+ * run({mode, options, prompt, args}), listModels({query}), login(), account(),
+ * billing({action}), logout({session}), review({args}), domain({command,args}),
+ * and help/version metadata are supplied by the caller. Interactive vs
+ * headless selection is made here so all aliases share identical behavior.
+ */
+export async function runOpenCodeCli({ argv = [], runtime, io = console, stdoutIsTTY = Boolean(process.stdout.isTTY), version = '' } = {}) {
+  const first = argv[0];
+  const normalized = aliases.get(first) || first;
+  const rest = commandNames.has(normalized) ? argv.slice(1) : (first === '--list-models' ? [] : argv);
+
+  if (['help', '--help', '-h'].includes(first)) {
+    io.log(cliHelp(version));
+    return 0;
+  }
+  if (['--version', '-v'].includes(first)) {
+    io.log(version);
+    return 0;
+  }
+  if (first === '--list-models') {
+    try { await ensureMethod(runtime, 'listModels')({ query: argv.slice(1).join(' ') }); return 0; }
+    catch (error) {
+      if (error?.name === 'AbortError' || error?.code === 'SIGINT') return 130;
+      return fail(error.message, 1, io);
+    }
+  }
+  if (['status', 'hash', 'fingerprint', 'check', 'c', 'validate'].includes(normalized)) {
+    try { return Number((await ensureMethod(runtime, 'domain')({ command: normalized, args: rest })) ?? 0); }
+    catch (error) { return fail(error.message, 1, io); }
+  }
+  if (normalized === 'review') {
+    try { return Number((await ensureMethod(runtime, 'review')({ args: rest, cwd: process.cwd() })) ?? 0); }
+    catch (error) { return fail(error.message, error.exitCode ?? 1, io); }
+  }
+  if (normalized === 'login' || normalized === 'auth') {
+    if (!stdoutIsTTY) return fail('login requires an interactive terminal — or set a provider API key environment variable', 1, io);
+    try { return Number((await ensureMethod(runtime, 'login')({ args: rest })) ?? 0); }
+    catch (error) {
+      if (error?.name === 'AbortError' || error?.code === 'SIGINT') return 130;
+      return fail(error.message, 1, io);
+    }
+  }
+  if (normalized === 'logout') return fail('Use `logout-cloud` to revoke a Carthagent Ship session; provider credentials are managed by the native runtime.', 1, io);
+  if (normalized === 'account' || normalized === 'cloud') {
+    try { return Number((await ensureMethod(runtime, 'account')({ args: rest })) ?? 0); }
+    catch (error) { return fail(error.message, 1, io); }
+  }
+  if (normalized === 'billing') {
+    const action = rest[0] || 'checkout';
+    if (!['checkout', 'portal'].includes(action)) return fail('Usage: ctg billing [checkout|portal]', 1, io);
+    try { return Number((await ensureMethod(runtime, 'billing')({ action })) ?? 0); }
+    catch (error) { return fail(error.message, 1, io); }
+  }
+  if (normalized === 'logout-cloud') {
+    try { return Number((await ensureMethod(runtime, 'logout')({ session: rest[0] })) ?? 0); }
+    catch (error) { return fail(error.message, 1, io); }
+  }
+  if (normalized === 'archive') {
+    try { return Number((await ensureMethod(runtime, 'archive')({ args: rest })) ?? 0); }
+    catch (error) { return fail(error.message, error.exitCode ?? 1, io); }
+  }
+  if (['serve', 'service', 'test', 'eval', 'update', 'quit', 'q', 'exit', 'demo'].includes(normalized)) {
+    try { return Number((await ensureMethod(runtime, 'command')({ command: normalized, args: rest })) ?? 0); }
+    catch (error) { return fail(error.message, error.exitCode ?? 1, io); }
+  }
+
+  let mode = normalized;
+  let args = rest;
+  if (first === undefined) { mode = 'tui'; args = []; }
+  else if (!commandNames.has(normalized)) {
+    if (first.startsWith('-') && !VALUE_FLAGS.has(first) && !BOOL_FLAGS.has(first)) {
+      io.error(`Unknown command or flag: ${first}`);
+      io.log(cliHelp(version));
+      return 1;
+    }
+    mode = 'tui';
+  }
+  if (mode === 'resume') mode = 'tui';
+  if (mode === 'continue') mode = 'tui';
+  if (mode === 'demo') mode = 'tui';
+
+  let options;
+  try { options = parseOpenCodeArgs(args); }
+  catch (error) { return fail(error.message, 1, io); }
+  if (normalized === 'resume' || normalized === 'continue' || normalized === 'demo') {
+    options[normalized === 'resume' ? 'resume' : normalized === 'continue' ? 'continue' : 'demo'] = true;
+  }
+  if (options.demo && !stdoutIsTTY) return fail('demo requires an interactive terminal', 1, io);
+  const headless = options.print || options.json || !stdoutIsTTY;
+  if (headless && options.resume) { options.resume = false; options.continue = true; }
+  if (headless && !options.prompt) return fail('non-interactive mode requires a prompt', 1, io);
+  try { return Number((await ensureMethod(runtime, 'run')({ mode: headless ? 'headless' : 'interactive', options, prompt: options.prompt, args })) ?? 0); }
+  catch (error) {
+    if (error?.name === 'AbortError' || error?.code === 'SIGINT') return 130;
+    return fail(error.message, Number.isInteger(error?.exitCode) ? error.exitCode : 1, io);
+  }
+}
+
+export const openCodeCliManifest = Object.freeze({
+  aliases: Object.freeze(Object.fromEntries(aliases)),
+  valueFlags: Object.freeze(Object.fromEntries(VALUE_FLAGS)),
+  boolFlags: Object.freeze(Object.fromEntries([...BOOL_FLAGS].map(([flag, [key, value]]) => [flag, { key, value }]))),
+});

package/lib/opencode/credentials.mjs

@@ -8,6 +8,8 @@ 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';
+import { Credential } from '@opencode/schema/credential';
+import { Schema } from 'effect';
 
 export const CTG_CREDENTIAL_NAMESPACE = 'ctg.credentials/';
 const refreshFlights = new Map();
@@ -45,12 +47,60 @@ export function nativeCredentialFile(env = process.env, platform = process.platf
   return join(dataHome, 'opencode', 'auth.json');
 }
 
+/** OpenCode 2.0.32 packages/cli/src/database-path.ts and util/global-roots.ts.
+ * Unlike legacy auth.json, the native credential vault is in the channel DB.
+ * The running host supplies its channel; never infer it from a release label. */
+export function nativeCredentialDatabaseFile(env = process.env, channel, home = os.homedir()) {
+  if (!channel) throw new Error('The native runtime channel is required to locate its credential vault.');
+  const data = join(env.XDG_DATA_HOME || join(home, '.local', 'share'), 'opencode');
+  const filename = env.OPENCODE_DB ?? (['latest', 'dev', 'beta', 'next', 'prod'].includes(channel)
+    || ['1', 'true'].includes(env.OPENCODE_DISABLE_CHANNEL_DB)
+    ? 'opencode.db' : `opencode-${channel.replace(/[^a-zA-Z0-9._-]/g, '-')}.db`);
+  if (filename === ':memory:') throw new Error('Native OAuth refresh requires a file-backed credential vault.');
+  return resolve(data, filename);
+}
+
+/** Raw read only: connection.resolve() refreshes expired OAuth and must never
+ * be called from its own refresh callback. Schema provenance: pinned 2.0.32
+ * packages/core/src/credential/sql.ts; value is Credential.Value JSON. Opening
+ * read-only must fail for missing/changed vaults, never create a parallel store.
+ * Bun is the native host; node:sqlite supports the same regression under Node.
+ * @param {{credentialFile: string, credentialID?: string, integrationID: string, methodID: string, refreshToken?: string}} options
+ */
+export async function readNativeOAuthCredential({ credentialFile, credentialID = undefined, integrationID, methodID, refreshToken = undefined }) {
+  const db = typeof globalThis.Bun !== 'undefined'
+    ? new (await import('bun:sqlite')).Database(credentialFile, { readonly: true, strict: true })
+    : new (await import('node:sqlite')).DatabaseSync(credentialFile, { readOnly: true });
+  try {
+    // Capture the callback's original row, never the current active selection.
+    // LIMIT 2 detects duplicate grants without selecting an arbitrary account.
+    const query = credentialID
+      ? 'SELECT id, value FROM credential WHERE id = ? AND integration_id = ?'
+      : `SELECT id, value FROM credential WHERE integration_id = ? AND json_extract(value, '$.type') = 'oauth'
+        AND json_extract(value, '$.methodID') = ? AND json_extract(value, '$.refresh') = ? LIMIT 2`;
+    const statement = typeof db.prepare === 'function' ? db.prepare(query) : db.query(query);
+    const rows = credentialID ? statement.all(credentialID, integrationID) : statement.all(integrationID, methodID, refreshToken);
+    if (rows.length > 1) throw new Error('Ambiguous native OAuth credential identity; no refresh was attempted.');
+    const row = rows[0];
+    if (!row) throw new Error('The native OAuth credential is no longer stored; reconnect before refreshing.');
+    // Do not include SQLite/JSON/schema errors or their input values in logs.
+    let value;
+    try { value = Schema.decodeUnknownSync(Credential.Value)(JSON.parse(row.value)); }
+    catch { throw new Error('Unsupported native credential vault value; no refresh was attempted.'); }
+    if (value.type !== 'oauth' || value.methodID !== methodID) {
+      throw new Error('The native OAuth credential method changed; no refresh was attempted.');
+    }
+    return credentialID ? value : row.id;
+  } finally { db.close(); }
+}
+
 /** 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
+ * @param {{credential: any, credentialFile: string, credentialID?: string, reread: () => Promise<any>, refresh: (credential: any) => Promise<any>, timeout?: number}} options
  */
 export async function refreshNativeCredential({
   credential,
   credentialFile,
+  credentialID,
   reread,
   refresh,
   timeout = 15_000,
@@ -63,6 +113,8 @@ export async function refreshNativeCredential({
   // 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`;
+  // Keep the existing token-scoped lock path so old hosts cannot rotate in
+  // parallel. Old unbound receipts are uncertain and must not be adopted.
   const pending = `${lock}.pending`;
   const credentialDigest = value => createHash('sha256')
     .update(`${value?.methodID || credential.methodID || ''}\0${value?.refresh || ''}`).digest('hex').slice(0, 32);
@@ -74,7 +126,6 @@ export async function refreshNativeCredential({
       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
@@ -82,9 +133,13 @@ export async function refreshNativeCredential({
     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 });
+      receipt.raw = JSON.stringify({ pid: receipt.pid, owner: receipt.owner, from: receipt.from, to: receipt.to, stage: receipt.stage, createdAt: receipt.createdAt, credentialID: receipt.credentialID });
     }
     catch (error) { if (error.code !== 'ENOENT') throw new Error('Invalid pending native credential refresh receipt; inspect the CTG refresh receipt before retrying.'); }
+    if (credentialID && receipt && receipt.credentialID !== credentialID) {
+      throw new Error('Unbound or different native credential refresh receipt; no rotation was attempted. Reauthenticate or inspect the receipt before retrying.');
+    }
+    const current = await reread();
     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(() => '');
@@ -108,22 +163,22 @@ export async function refreshNativeCredential({
           // 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.');
+          throw new Error('The native refresh owner exited before Carthagent runtime 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.');
+      throw new Error('Timed out waiting for Carthagent runtime 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 initialReceipt = JSON.stringify({ pid: process.pid, owner, from: digest, stage: 'refreshing', createdAt: Date.now(), credentialID });
     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(); }
+      try { await handle.writeFile(JSON.stringify({ ...value, credentialID })); await handle.sync(); }
       finally { await handle.close(); }
       if (await readFile(pending, 'utf8').catch(() => '') !== initialReceipt) {
         await rm(temporary, { force: true });
@@ -201,5 +256,5 @@ export async function legacyOAuthForOpenCode(options = {}) {
 }
 
 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.';
+  return 'Existing Carthagent Ship OAuth can be migrated from the legacy auth.json credential into Carthagent runtime integration storage; other provider credentials remain BYOK and may be reconnected through Carthagent runtime if their format is unsupported.';
 }

package/lib/opencode/demo.mjs

@@ -0,0 +1,53 @@
+import { mkdtemp, mkdir, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { runCommand } from '../delivery.mjs';
+
+/** Run an honest, isolated offline walkthrough; it never contacts a provider. */
+/** @param {{ io?: Console, execute?: typeof runCommand, signal?: AbortSignal, nodeBinary?: string }} options */
+export async function runOfflineDemo({ io = console, execute = runCommand, signal, nodeBinary = process.env.CTG_NODE_EXECUTABLE || process.execPath } = {}) {
+  signal?.throwIfAborted();
+  const workspace = await mkdtemp(join(tmpdir(), 'carthagent-native-demo-'));
+  try {
+    await mkdir(join(workspace, 'test'));
+    await writeFile(join(workspace, 'app.mjs'), `export function summarize(items) {
+  return items.filter(item => item.done).map(item => item.title).join(', ');
+}
+`);
+    await writeFile(join(workspace, 'test', 'app.test.mjs'), `import test from 'node:test';
+import assert from 'node:assert/strict';
+import { summarize } from '../app.mjs';
+
+test('summarize includes completed items and preserves their order', () => {
+  assert.equal(summarize([{ title: 'Plan', done: true }, { title: 'Ship', done: false }, { title: 'Test', done: true }]), 'Plan, Test');
+});
+
+test('summarize handles an empty list', () => {
+  assert.equal(summarize([]), '');
+});
+`);
+    io.log('Carthagent native offline demo');
+    io.log('Scripted fixture only: no provider/API calls, no edits to your project, and no claim of project delivery evidence.');
+    io.log('\nPlan: implement a tiny completed-task summarizer, then verify ordering and the empty case.');
+    io.log(`\nFixture workspace: ${workspace}`);
+    const env = { ...process.env };
+    // Node's test runner marks subprocesses as nested workers; clear the marker
+    // so the fixture really runs when /demo is itself exercised from node:test.
+    delete env.NODE_TEST_CONTEXT;
+    const result = await execute([nodeBinary, '--test', 'test/app.test.mjs'], { cwd: workspace, timeoutSeconds: 30, signal, env });
+    if (result.output?.trim()) io.log(`\n${result.output.trim()}`);
+    if (result.cancelled || signal?.aborted) {
+      io.log('\nOffline demo cancelled; no completion is claimed.');
+      return 130;
+    }
+    if (result.code !== 0 || result.timedOut || result.cancelled) {
+      io.error(`Offline demo check failed${result.timedOut ? ' (timed out)' : ''}: ${result.output?.trim() || 'no test output'}`);
+      return 1;
+    }
+    io.log('\nVerification: isolated Node test suite passed (2 tests).');
+    io.log('Finish: the sample behavior is verified only inside this disposable demo fixture.');
+    return 0;
+  } finally {
+    await rm(workspace, { recursive: true, force: true });
+  }
+}

package/lib/opencode/evaluation-budget-plugin/index.ts

@@ -84,6 +84,9 @@ export default Plugin.define({
         await pendingWrites.get(event.sessionID);
         const session = await ctx.session.get({ sessionID: event.sessionID });
         const configured = session.metadata?.[budgetKey];
+        // This hook is an admission guard for evaluation sessions, not a
+        // general model-request gate for unrelated native host workflows.
+        if (configured === undefined) return;
         if (!configured || typeof configured !== 'object'
           || configured.maxTurns !== maxTurns || configured.maxCost !== maxCost) {
           throw Error('Evaluation session budget handshake is missing or differs from the active admission guard');

package/lib/opencode/evaluation.mjs

@@ -37,13 +37,14 @@ async function bounded(promise, milliseconds, fallback) {
 
 /** Run one native OpenCode session with fail-closed accounting and cancellation. */
 export async function runNativeEvaluation({ directory, prompt, systemPrompt = '', model, provider, timeoutSeconds = 600, maxTurns = 100, maxCost = 3,
-  signal, onEvent = () => {}, client, baseUrl = process.env.CTG_OPENCODE_URL, headers = {}, version = '2.0.32', outcomeTimeoutSeconds = 10 }) {
+  signal, onEvent = () => {}, client, baseUrl = process.env.CTG_OPENCODE_URL, headers = {}, version = '2.0.32', outcomeTimeoutSeconds = 10,
+  agent, metadata = {} }) {
   positive(timeoutSeconds, 'timeoutSeconds', 3600);
   positive(maxTurns, 'maxTurns', 1000);
   positive(maxCost, 'maxCost');
   positive(outcomeTimeoutSeconds, 'outcomeTimeoutSeconds', 60);
   if (!directory || !prompt || !model || !provider) throw Error('directory, prompt, provider, and model are required');
-  if (!client && !baseUrl) throw Error('CTG_OPENCODE_URL must identify the isolated native OpenCode service; shared service discovery is disabled.');
+  if (!client && !baseUrl) throw Error('CTG_OPENCODE_URL must identify the isolated native Carthagent runtime service; shared service discovery is disabled.');
   if (!client && !Object.keys(headers).length && process.env.CTG_OPENCODE_AUTHORIZATION) headers = { authorization: process.env.CTG_OPENCODE_AUTHORIZATION };
   const api = client || OpenCode.make({ baseUrl, headers });
   const controller = new AbortController();
@@ -55,7 +56,7 @@ export async function runNativeEvaluation({ directory, prompt, systemPrompt = ''
   const timer = setTimeout(() => controller.abort(new Error('Evaluation wall-time limit')), timeoutSeconds * 1000);
   const started = Date.now();
   const state = { turns: 0, productiveTurns: 0, providerErrors: 0, cost: null, tokens: 0, tools: {}, errors: [], lastStop: null, budgetReason: null, deliveryStatus: null };
-  let session, streamTask, streamError, outcome;
+  let session, streamTask, streamError, outcome, actualRuntimeVersion;
   let interruptionStatus = 'not-needed';
   let finished = false;
   let stopAfterIdle = false;
@@ -76,7 +77,7 @@ export async function runNativeEvaluation({ directory, prompt, systemPrompt = ''
           state.lastStop = data.finish;
         } else if (event.type === 'session.execution.failed') {
           state.providerErrors++;
-          state.errors.push(data.error?.message || 'OpenCode execution failed');
+          state.errors.push(data.error?.message || 'Carthagent runtime execution failed');
         } else if (event.type === 'session.tool.called') {
           toolByCallID.set(data.id, data);
           const name = data.tool || data.name;
@@ -106,7 +107,7 @@ export async function runNativeEvaluation({ directory, prompt, systemPrompt = ''
     do {
       const info=await api.session.get({sessionID:session.id},{signal:AbortSignal.timeout(5000)});
       if(info.outcome) return info;
-      if(Date.now()>=deadline) throw Error('OpenCode session terminal outcome did not become available');
+      if(Date.now()>=deadline) throw Error('Carthagent runtime session terminal outcome did not become available');
       await new Promise(resolve=>setTimeout(resolve,25));
     } while(true);
   };
@@ -114,15 +115,20 @@ export async function runNativeEvaluation({ directory, prompt, systemPrompt = ''
   try {
     if (controller.signal.aborted) throw controller.signal.reason;
     const info = await api.server.info({ signal: controller.signal });
-    if (info.version && !info.version.startsWith('2.')) throw Error(`OpenCode 2 required, received ${info.version}`);
+    actualRuntimeVersion = info.version;
+    const ownedRuntimeVersion = `0.0.0-ctg.${version}`;
+    if (actualRuntimeVersion !== version && actualRuntimeVersion !== ownedRuntimeVersion) {
+      throw Error(`Carthagent runtime compatible with ${version} required, received ${actualRuntimeVersion ?? 'unknown'}`);
+    }
     const plugins = await api.plugin.list({ location: { directory } }, { signal: controller.signal });
     const guard = plugins.data.find(plugin => plugin.id === EVALUATION_BUDGET_PLUGIN);
     if (guard?.state.status !== 'active') throw Error(`Evaluation admission guard ${EVALUATION_BUDGET_PLUGIN} is not active`);
     session = await api.session.create({
+      ...(agent ? { agent } : {}),
       model: { providerID: provider, id: model },
       location: { directory },
       title: `CTG evaluation ${NATIVE_EVALUATION_RUNTIME}`,
-      metadata: { [EVALUATION_BUDGET_METADATA]: { maxTurns, maxCost } },
+      metadata: { ...metadata, [EVALUATION_BUDGET_METADATA]: { maxTurns, maxCost } },
     }, { signal: controller.signal });
     streamTask = onEventStream();
     // Subscription has no replay; allow its connection to establish before admission.
@@ -140,7 +146,7 @@ export async function runNativeEvaluation({ directory, prompt, systemPrompt = ''
     // authoritative terminal outcome is visible; absence is never success.
     const sessionInfo = await pollOutcome();
     outcome = sessionInfo.outcome;
-    if (outcome !== 'succeeded') state.errors.push(`OpenCode session ended with authoritative outcome: ${outcome}`);
+    if (outcome !== 'succeeded') state.errors.push(`Carthagent runtime session ended with authoritative outcome: ${outcome}`);
 
     // Fetch only this session's assistant transcript; /session/stats is project-wide.
     const transcript = await allMessages(api, session.id, { signal: AbortSignal.timeout(15000) });
@@ -159,7 +165,7 @@ export async function runNativeEvaluation({ directory, prompt, systemPrompt = ''
     }
     const tokenUsage = sessionInfo.tokens;
     if (!Number.isFinite(sessionInfo.cost) || sessionInfo.cost < 0 || !tokenUsage || !['input','output','reasoning'].every(key => Number.isFinite(tokenUsage[key]) && tokenUsage[key] >= 0) || !tokenUsage.cache || !['read','write'].every(key => Number.isFinite(tokenUsage.cache[key]) && tokenUsage.cache[key] >= 0)) {
-      throw Error('OpenCode session aggregate usage is unavailable; refusing evaluation without enforceable max-cost');
+      throw Error('Carthagent runtime session aggregate usage is unavailable; refusing evaluation without enforceable max-cost');
     }
     state.cost = sessionInfo.cost;
     state.tokens = tokenUsage.input + tokenUsage.output + tokenUsage.reasoning + tokenUsage.cache.read + tokenUsage.cache.write;
@@ -177,7 +183,7 @@ export async function runNativeEvaluation({ directory, prompt, systemPrompt = ''
       if (controller.signal.aborted && Date.now() - started >= timeoutSeconds * 1000) state.budgetReason = 'wall-time limit';
       else if (controller.signal.aborted && signal?.aborted && /wall.?time/i.test(String(signal.reason?.message || signal.reason || ''))) state.budgetReason = 'wall-time limit';
       else if (controller.signal.aborted && signal?.aborted) state.budgetReason = 'cancelled';
-      else state.budgetReason = 'native OpenCode request failed';
+      else state.budgetReason = 'native Carthagent runtime request failed';
     }
     state.errors.push(error instanceof Error ? error.message : String(error));
     if (session && !outcome) {
@@ -236,7 +242,21 @@ export async function runNativeEvaluation({ directory, prompt, systemPrompt = ''
   }
   if (!outcome && !state.budgetReason) {
     state.budgetReason = 'missing terminal session outcome';
-    state.errors.push('OpenCode session has no authoritative terminal outcome.');
+    state.errors.push('Carthagent runtime session has no authoritative terminal outcome.');
   }
-  return { ...state, outcome: outcome || null, interruptionStatus, exitCode: state.budgetReason || streamError ? 1 : 0, timedOut: state.budgetReason === 'wall-time limit', durationMs: Date.now() - started, sessionID: session?.id || null, runtime: NATIVE_EVALUATION_RUNTIME, opencodeVersion: version };
+  return {
+    ...state,
+    outcome: outcome || null,
+    interruptionStatus,
+    exitCode: state.budgetReason || streamError ? 1 : 0,
+    timedOut: state.budgetReason === 'wall-time limit',
+    durationMs: Date.now() - started,
+    sessionID: session?.id || null,
+    runtime: NATIVE_EVALUATION_RUNTIME,
+    compatibilityVersion: version,
+    runtimeVersion: actualRuntimeVersion ?? null,
+    // Kept for consumers of the prior result shape; this is the actual server
+    // version, not the compatibility target supplied to the evaluator.
+    opencodeVersion: actualRuntimeVersion ?? null,
+  };
 }

package/lib/opencode/headless.mjs

@@ -26,7 +26,7 @@ export async function runHeadless(service, workspace, prompt, options = {}) {
       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');
+    if (!id) throw new Error('Carthagent runtime did not return a valid session identifier');
     session = created ?? { id };
     await setSessionEnvironment(service, id, options.env ?? process.env, { location: workspace, signal });
     promptStarted = true;
@@ -35,7 +35,7 @@ export async function runHeadless(service, workspace, prompt, options = {}) {
       signal,
       body: { ...(options.prompt ?? {}), ...(options.parts ? { parts: options.parts } : {}), text: prompt },
     });
-    await serviceRequest(service, 'POST', `/api/experimental/session/${encodeURIComponent(id)}/wait`, { signal, location: workspace });
+    await waitForSession(service, id, workspace, signal);
     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);
@@ -72,6 +72,19 @@ export async function runHeadless(service, workspace, prompt, options = {}) {
   }
 }
 
+async function waitForSession(service, id, workspace, signal) {
+  // The host keeps executing when Node's HTTP headers deadline expires on this
+  // long-held observation request. Reattach the observer, never replay prompt.
+  for (;;) {
+    signal.throwIfAborted();
+    try {
+      return await serviceRequest(service, 'POST', `/api/experimental/session/${encodeURIComponent(id)}/wait`, { signal, location: workspace });
+    } catch (error) {
+      if (signal.aborted || (error?.cause?.code ?? error?.code) !== 'UND_ERR_HEADERS_TIMEOUT') throw error;
+    }
+  }
+}
+
 function preAdmissionResult(sessionID, reason, cause, abortReason) {
   const outcome = reason === 'aborted' ? 'interrupted' : 'timed-out';
   return {
@@ -123,18 +136,22 @@ async function incompleteResult(service, sessionID, workspace, accepted, session
   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);
+  // The session-level outcome may belong to a previously completed turn. Only
+  // an idle message bounded to this accepted prompt can establish a terminal
+  // outcome for the current turn.
+  const outcome = idle?.outcome;
   const result = extractAssistant(messages, accepted);
   const reasonText = session.ctg?.reason ?? reason;
   const finalOutcome = outcome ?? (reason === 'timed-out' ? 'timed-out' : 'interrupted');
+  const { outcome: _priorOutcome, ...sessionWithoutPriorOutcome } = session;
   return {
-    session: { ...session, ...(outcome ? { outcome } : {}), error: session.error ?? idle?.error },
+    session: { ...sessionWithoutPriorOutcome, ...(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),
+    terminal: Boolean(idle),
     reason: reasonText,
     budgetReason: finalOutcome === 'timed-out' || finalOutcome === 'failed' ? reasonText : undefined,
     cause: cause?.message,