carthagent 0.0.0-stage → 1.0.7

package/tests/opencode-runtime.test.mjs

@@ -0,0 +1,455 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import os from 'node:os';
+import path from 'node:path';
+import { getEventListeners } from 'node:events';
+import { mkdir, mkdtemp, readFile, rm, stat, writeFile } from 'node:fs/promises';
+import { spawn } from 'node:child_process';
+import { nativeCommandConfig } from '../lib/opencode/compatibility.mjs';
+import { provisionRuntime, resolveOpenCode, runtimeEnvironment, runtimePaths, withFileLock, workspaceEnvironment } from '../lib/opencode/runtime.mjs';
+import { cancelSession, createSession, ensureService, getSession, launchTui, promptSession, serviceRequest, sessionMessages, setSessionEnvironment, stopService } from '../lib/opencode/service.mjs';
+import { runHeadless } from '../lib/opencode/headless.mjs';
+
+function pendingUntilAbort(signal) {
+  return new Promise((_, reject) => {
+    const keepAlive = setTimeout(() => {}, 5000);
+    const aborted = () => {
+      clearTimeout(keepAlive);
+      reject(new DOMException('Aborted', 'AbortError'));
+    };
+    signal.addEventListener('abort', aborted, { once: true });
+    if (signal.aborted) aborted();
+  });
+}
+
+test('CTG runtime paths and env are isolated from host OpenCode roots', () => {
+  const root = path.join(os.tmpdir(), 'ctg-test-profile');
+  const paths = runtimePaths({ root });
+  const env = runtimeEnvironment({ root, env: { ANTHROPIC_API_KEY: 'test' } });
+  assert.equal(env.XDG_CONFIG_HOME, paths.config);
+  assert.equal(env.XDG_DATA_HOME, paths.data);
+  assert.equal(env.XDG_STATE_HOME, paths.state);
+  assert.equal(env.XDG_CACHE_HOME, paths.cache);
+  assert.equal(env.HOME, paths.home);
+  assert.equal(env.APPDATA, path.join(paths.home, 'AppData', 'Roaming'));
+  assert.equal(env.LOCALAPPDATA, path.join(paths.home, 'AppData', 'Local'));
+  assert.equal(env.OPENCODE_TEST_HOME, paths.home);
+  assert.equal(env.OPENCODE_CONFIG_DIR, paths.configDir);
+  assert.equal(env.OPENCODE_CONFIG_PROJECT_DISABLE, 'true');
+  assert.equal(env.OPENCODE_DB, path.join(paths.data, 'opencode.db'));
+  assert.equal(env.ANTHROPIC_API_KEY, 'test');
+  assert.equal(env.OPENCODE_CUSTOM_CONFIG, undefined);
+  assert.notEqual(paths.serviceFile, path.join(os.homedir(), '.local/state/opencode/service.json'));
+});
+
+test('runtime removes inherited OpenCode profile overrides', () => {
+  const root = path.resolve('/tmp/ctg-isolated');
+  const paths = runtimePaths({ root });
+  const env = runtimeEnvironment({ root, env: {
+    OPENCODE_CONFIG_DIR: '/user/config',
+    OPENCODE_CONFIG: '/user/opencode.json',
+    OPENCODE_CONFIG_PROJECT_DISABLE: 'false',
+    OPENCODE_SERVER_PASSWORD: 'user-service-secret',
+    OPENAI_API_KEY: 'preserved',
+  } });
+  assert.equal(env.OPENCODE_CONFIG_DIR, paths.configDir);
+  assert.equal(env.OPENCODE_CONFIG, paths.configFile);
+  assert.equal(env.OPENCODE_CONFIG_PROJECT_DISABLE, 'true');
+  assert.equal(env.OPENCODE_SERVER_PASSWORD, undefined);
+  assert.equal(env.OPENAI_API_KEY, 'preserved');
+  assert.equal(env.APPDATA, paths.appData);
+  assert.equal(env.LOCALAPPDATA, paths.localAppData);
+});
+
+test('runtime overrides inherited Windows profile roots with CTG-owned paths', () => {
+  const root = path.resolve('/tmp/ctg-windows-roots');
+  const paths = runtimePaths({ root });
+  const env = runtimeEnvironment({ root, env: {
+    APPDATA: 'C:\\Users\\foreign\\AppData\\Roaming',
+    LOCALAPPDATA: 'C:\\Users\\foreign\\AppData\\Local',
+    OPENCODE_CONFIG_PROJECT_DISABLE: 'false',
+  } });
+  assert.equal(env.APPDATA, paths.appData);
+  assert.equal(env.LOCALAPPDATA, paths.localAppData);
+  assert.equal(env.OPENCODE_CONFIG_PROJECT_DISABLE, 'true');
+});
+
+test('stale-lock recovery is serialized across independent processes', async () => {
+  const root = await mkdtemp(path.join(os.tmpdir(), 'ctg-stale-recovery-'));
+  const lock = path.join(root, 'lifecycle.lock');
+  const gate = path.join(root, 'go');
+  const worker = path.join(root, 'worker.mjs');
+  const markerDir = path.join(root, 'active');
+  await mkdir(markerDir);
+  await writeFile(lock, JSON.stringify({ pid: 2_000_000_000, token: 'dead-owner', startedAt: 0 }));
+  await writeFile(worker, `
+    import { readFile, rm, writeFile } from 'node:fs/promises';
+    import { withFileLock } from ${JSON.stringify(new URL('../lib/opencode/runtime.mjs', import.meta.url).href)};
+    const [lock, gate, markerDir, name] = process.argv.slice(2);
+    while (true) { try { await readFile(gate); break; } catch { await new Promise(r => setTimeout(r, 5)); } }
+    await withFileLock(lock, async () => {
+      const marker = markerDir + '/' + name;
+      await writeFile(marker, 'active');
+      const current = await (await import('node:fs/promises')).readdir(markerDir);
+      if (current.includes('a') && current.includes('b')) await writeFile(markerDir + '/overlap', current.join(','));
+      await new Promise(r => setTimeout(r, 120));
+      await rm(marker);
+    }, { staleLockAge: 0, timeout: 5000, pollInterval: 2, afterStaleLockCheck: async () => {
+      await writeFile(markerDir + '/checked-' + name, 'yes');
+      while (true) {
+        try { await readFile(markerDir + '/checked-a'); await readFile(markerDir + '/checked-b'); break; }
+        catch { await new Promise(r => setTimeout(r, 2)); }
+      }
+    } });
+  `);
+  try {
+    const a = spawn(process.execPath, [worker, lock, gate, markerDir, 'a'], { stdio: 'ignore' });
+    const b = spawn(process.execPath, [worker, lock, gate, markerDir, 'b'], { stdio: 'ignore' });
+    await new Promise((resolve) => setTimeout(resolve, 100));
+    await writeFile(gate, 'go');
+    const exited = Promise.all([a, b].map((child) => new Promise((resolve, reject) => {
+      child.once('error', reject);
+      child.once('exit', (code) => code === 0 ? resolve() : reject(new Error(`lock worker exited ${code}`)));
+    })));
+    await exited;
+    await assert.rejects(readFile(path.join(markerDir, 'overlap')), { code: 'ENOENT' });
+  } finally { await rm(root, { recursive: true, force: true }); }
+});
+
+test('persistent stale recovery marker fails closed at the lock deadline with manual recovery guidance', async () => {
+  const root = await mkdtemp(path.join(os.tmpdir(), 'ctg-stale-recovery-stuck-'));
+  const lock = path.join(root, 'lifecycle.lock');
+  try {
+    await writeFile(lock, JSON.stringify({ pid: 2_000_000_000, token: 'dead-owner', startedAt: 0 }));
+    await writeFile(`${lock}.recovery`, JSON.stringify({ pid: 2_000_000_000, token: 'abandoned-recovery' }));
+    const startedAt = Date.now();
+    await assert.rejects(withFileLock(lock, async () => assert.fail('must not acquire lock'), {
+      timeout: 75,
+      pollInterval: 250,
+      staleLockAge: 0,
+    }), (error) => {
+      assert.match(error.message, /Timed out waiting for CTG runtime lock/);
+      assert.match(error.message, /inspect and remove the stale lock\/recovery files/);
+      assert.ok(error.message.includes(`${lock}.recovery`), 'manual guidance must name the recovery marker path');
+      return true;
+    });
+    assert.ok(Date.now() - startedAt < 400, 'recovery-marker retries must observe the bounded deadline');
+    assert.equal((await readFile(`${lock}.recovery`, 'utf8')).includes('abandoned-recovery'), true, 'stale marker remains for deliberate manual recovery');
+  } finally { await rm(root, { recursive: true, force: true }); }
+});
+
+test('profile provisioning creates private isolated profile and absolute plugin reference', async () => {
+  const root = await mkdtemp(path.join(os.tmpdir(), 'ctg-runtime-'));
+  try {
+    const paths = await provisionRuntime({ root, pluginPath: path.join(root, 'plugins/carthagent'), profile: { model: 'fake/test' } });
+    const config = JSON.parse(await readFile(paths.configFile, 'utf8'));
+    assert.equal(config.model, 'fake/test');
+    assert.deepEqual(config.plugins, [path.join(root, 'plugins/carthagent')]);
+    if (process.platform !== 'win32') assert.equal((await stat(paths.configFile)).mode & 0o777, 0o600);
+    assert.equal((await stat(paths.appData)).isDirectory(), true);
+    assert.equal((await stat(paths.localAppData)).isDirectory(), true);
+    await writeFile(paths.configFile, JSON.stringify({ model: 'kept/model', plugins: ['kept-plugin'], commands: { keep: 'hello' } }));
+    await provisionRuntime({ root, pluginPath: path.join(root, 'plugins/carthagent'), profile: { theme: 'kept-theme' } });
+    const updated = JSON.parse(await readFile(paths.configFile, 'utf8'));
+    assert.equal(updated.model, 'kept/model');
+    assert.equal(updated.theme, 'kept-theme');
+    assert.deepEqual(updated.commands, { keep: 'hello' });
+    assert.deepEqual(updated.plugins, ['kept-plugin', path.join(root, 'plugins/carthagent')]);
+  } finally { await rm(root, { recursive: true, force: true }); }
+});
+
+test('workspace environment records workspace without leaking CTG XDG overrides', () => {
+  const workspace = path.resolve('/tmp/workspace');
+  const env = workspaceEnvironment(workspace, { XDG_CONFIG_HOME: '/host/config', OPENAI_API_KEY: 'secret' });
+  assert.equal(env.XDG_CONFIG_HOME, '/host/config');
+  assert.equal(env.CTG_WORKSPACE, workspace);
+  assert.equal(env.OPENAI_API_KEY, 'secret');
+});
+
+test('native slash command conversion validates and preserves template', () => {
+  assert.deepEqual(nativeCommandConfig({ review: { description: 'Review', template: 'Inspect $ARGUMENTS', agent: 'build' } }), {
+    review: { description: 'Review', template: 'Inspect $ARGUMENTS', agent: 'build' },
+  });
+  assert.throws(() => nativeCommandConfig({ 'Bad Name': 'no' }), /Invalid slash command/);
+});
+
+test('native API requests preserve structured responses and reject status failures', async () => {
+  const original = globalThis.fetch;
+  try {
+    globalThis.fetch = async () => new Response('{"ok":true}', { status: 200 });
+    assert.deepEqual(await serviceRequest({ url: 'http://127.0.0.1:1', headers: {} }, 'GET', '/api/info'), { ok: true });
+    globalThis.fetch = async () => new Response('{"message":"bad"}', { status: 500 });
+    await assert.rejects(serviceRequest({ url: 'http://127.0.0.1:1', headers: {} }, 'GET', '/api/info'), /failed \(500\)/);
+  } finally { globalThis.fetch = original; }
+});
+
+test('session API helpers use the v2 envelope, prompt payload, and endpoint contracts', async () => {
+  const original = globalThis.fetch;
+  const calls = [];
+  const work = path.resolve('/work');
+  const workspace = path.resolve('/workspace');
+  try {
+    globalThis.fetch = async (url, init) => {
+      calls.push({ url: String(url), init });
+      return new Response('{"data":{"id":"ses_example"}}', { status: 200 });
+    };
+    const service = { url: 'http://127.0.0.1:1234', headers: {} };
+    assert.deepEqual(await createSession(service, work), { id: 'ses_example' });
+    assert.equal(JSON.parse(calls[0].init.body).location.directory, work);
+    await promptSession(service, 'ses_example', 'hello');
+    assert.equal(new URL(calls[1].url).pathname, '/api/session/ses_example/prompt');
+    assert.equal(JSON.parse(calls[1].init.body).text, 'hello');
+    await setSessionEnvironment(service, 'ses_example', { API_KEY: 'fixture' }, { location: workspace });
+    assert.equal(calls[2].init.method, 'PUT');
+    assert.equal(new URL(calls[2].url).pathname, '/api/session/ses_example/environment');
+    assert.equal(JSON.parse(calls[2].init.body).variables.API_KEY, 'fixture');
+    assert.equal(JSON.parse(calls[2].init.body).variables.CTG_WORKSPACE, workspace);
+    assert.equal(new URL(calls[0].url).searchParams.get('location[directory]'), work);
+    await sessionMessages(service, 'ses_example', { location: { directory: workspace } });
+    assert.equal(new URL(calls[3].url).searchParams.get('location[directory]'), workspace);
+    await cancelSession(service, 'ses_example', { location: { directory: workspace }, timeout: 100 });
+    const interrupt = new URL(calls[4].url);
+    assert.equal(interrupt.pathname, '/api/session/ses_example/interrupt');
+    assert.equal(interrupt.searchParams.get('location[directory]'), workspace);
+    assert.equal(interrupt.searchParams.get('resume'), 'false');
+    assert.ok(calls[4].init.signal instanceof AbortSignal, 'interrupt requests have a bounded abort signal');
+    await getSession(service, 'ses_example', { location: workspace });
+    assert.equal(new URL(calls[5].url).pathname, '/api/session/ses_example');
+    assert.equal(new URL(calls[5].url).searchParams.get('location[directory]'), workspace);
+  } finally { globalThis.fetch = original; }
+});
+
+test('native TUI attaches to the ensured authenticated service', () => {
+  let captured;
+  const service = {
+    url: 'http://127.0.0.1:4567',
+    info: { password: 'ctg-test-password' },
+    binary: '/ctg/opencode',
+    paths: { root: '/ctg/profile' },
+  };
+  launchTui(service, '/work', { sessionID: 'ses_123', spawnImpl: (...args) => (captured = args) });
+  assert.deepEqual(captured[0], '/ctg/opencode');
+  assert.deepEqual(captured[1], ['--server', 'http://127.0.0.1:4567', '/work', '--session', 'ses_123']);
+  assert.equal(captured[2].env.OPENCODE_PASSWORD, 'ctg-test-password');
+  assert.equal(captured[2].cwd, '/work');
+});
+
+test('a live registered process is retained when health inspection fails', async () => {
+  const root = await mkdtemp(path.join(os.tmpdir(), 'ctg-live-unhealthy-'));
+  const paths = runtimePaths({ root });
+  const original = globalThis.fetch;
+  try {
+    await provisionRuntime({ root });
+    const record = { id: 'ctg-live', pid: process.pid, url: 'http://127.0.0.1:1', password: 'test', version: '2.0.32' };
+    await writeFile(paths.serviceFile, JSON.stringify(record));
+    globalThis.fetch = async () => { throw new Error('temporary outage'); };
+    const options = { root, binary: '/missing/binary' };
+    // stopService does not need to resolve an executable and must not discard ownership.
+    await assert.rejects(stopService(options), /alive but its service identity cannot be verified/);
+    assert.deepEqual(JSON.parse(await readFile(paths.serviceFile, 'utf8')), record);
+  } finally { globalThis.fetch = original; await rm(root, { recursive: true, force: true }); }
+});
+
+test('ensure and stop serialize on the same lifecycle lock', async () => {
+  const root = await mkdtemp(path.join(os.tmpdir(), 'ctg-lifecycle-race-'));
+  const script = path.join(root, 'fake-opencode.cjs');
+  const source = `if (process.argv[2] === '--version') { console.log('2.0.32'); process.exit(0); }\nconst http = require('node:http'); const server = http.createServer((req,res) => { if (req.url === '/api/info') { res.setHeader('content-type','application/json'); res.end(JSON.stringify({version:'2.0.32',pid:process.pid})); } else { res.statusCode=404; res.end(); } }); server.listen(Number(process.argv[process.argv.indexOf('--port')+1]), '127.0.0.1', () => console.log('server listening on http://127.0.0.1:'+server.address().port));\n`;
+  try {
+    await writeFile(script, source);
+    const spawnImpl = (command, args, options) => spawn(command, [script, ...args], options);
+    const options = { root, binary: process.execPath, spawnImpl, startupTimeout: 5000, stopTimeout: 3000 };
+    const [ensured, stopped] = await Promise.all([ensureService(options), stopService(options)]);
+    assert.equal(typeof stopped, 'boolean');
+    if (ensured?.pid) {
+      // It either remains the correctly registered live service or stop removed it.
+      const current = await readFile(runtimePaths({ root }).serviceFile, 'utf8').then(JSON.parse).catch(() => undefined);
+      if (current) assert.equal(current.pid, ensured.pid);
+    }
+    await stopService(options).catch(() => {});
+    assert.equal(await readFile(runtimePaths({ root }).serviceFile, 'utf8').then(JSON.parse).catch(() => undefined), undefined);
+  } finally { await rm(root, { recursive: true, force: true }); }
+});
+
+test('an explicitly selected unusable OpenCode binary does not fall back', async () => {
+  await assert.rejects(resolveOpenCode({ binary: '/missing/ctg-opencode' }), /ENOENT|not found/i);
+});
+
+test('headless runner passes workspace environment and returns assistant content and status', async () => {
+  const original = globalThis.fetch;
+  const calls = [];
+  try {
+    globalThis.fetch = async (url, init = {}) => {
+      const pathname = new URL(url).pathname;
+      calls.push({ pathname, init });
+      if (pathname === '/api/session') return new Response('{"data":{"id":"ses_headless"}}');
+      if (pathname.endsWith('/environment')) return new Response(null, { status: 204 });
+      if (pathname.endsWith('/prompt')) return new Response('{"data":{"id":"user_headless"}}');
+      if (pathname.endsWith('/wait')) return new Response(null, { status: 204 });
+      if (/\/api\/session\/ses_headless$/.test(pathname)) return new Response('{"data":{"id":"ses_headless","outcome":"succeeded"}}');
+      if (pathname.endsWith('/message')) return new Response(JSON.stringify({ data: [{ type: 'assistant', finish: 'stop', content: [{ type: 'text', text: 'fixture result' }] }] }));
+      throw new Error(`Unexpected endpoint ${pathname}`);
+    };
+    const result = await runHeadless({ url: 'http://127.0.0.1:3333', headers: {} }, '/workspace', 'say the fixture', { env: { FIXTURE_KEY: 'injected' } });
+    assert.deepEqual(result.result, {
+      status: 'stop',
+      text: 'fixture result',
+      error: undefined,
+      message: { type: 'assistant', finish: 'stop', content: [{ type: 'text', text: 'fixture result' }] },
+    });
+    assert.equal(calls.find((call) => call.pathname.endsWith('/environment')).init.method, 'PUT');
+    assert.equal(JSON.parse(calls.find((call) => call.pathname.endsWith('/environment')).init.body).variables.FIXTURE_KEY, 'injected');
+    assert.equal(JSON.parse(calls.find((call) => call.pathname.endsWith('/prompt')).init.body).text, 'say the fixture');
+    assert.equal(result.outcome, 'succeeded');
+    assert.equal(result.terminal, true);
+    assert.equal(result.budgetReason, undefined, 'a successful terminal session has no budget failure reason');
+  } finally { globalThis.fetch = original; }
+});
+
+test('pre-aborted headless calls do not create or resume a session or return prior output', async () => {
+  const original = globalThis.fetch;
+  let requests = 0;
+  try {
+    globalThis.fetch = async () => { requests += 1; throw new Error('pre-aborted execution must not make API requests'); };
+    const controller = new AbortController();
+    controller.abort(new Error('already cancelled'));
+    const service = { url: 'http://127.0.0.1:3333', headers: {} };
+    for (let attempt = 0; attempt < 3; attempt += 1) {
+      const created = await runHeadless(service, '/workspace', 'new work', { signal: controller.signal });
+      assert.equal(created.outcome, 'interrupted');
+      assert.equal(created.result, undefined);
+      assert.deepEqual(created.messages, []);
+      assert.equal(created.accepted, undefined);
+      assert.equal(created.budgetReason, undefined);
+      assert.equal(getEventListeners(controller.signal, 'abort').length, 0, 'pre-aborted initial calls must not leak forwarding listeners');
+      const resumed = await runHeadless(service, '/workspace', 'more work', { sessionID: 'ses_old_success', signal: controller.signal });
+      assert.equal(resumed.outcome, 'interrupted');
+      assert.equal(resumed.session.id, 'ses_old_success');
+      assert.equal(resumed.result, undefined, 'must not reuse a prior successful assistant from the resumed session');
+      assert.deepEqual(resumed.messages, []);
+      assert.equal(getEventListeners(controller.signal, 'abort').length, 0, 'pre-aborted resumed calls must not leak forwarding listeners');
+    }
+    assert.equal(requests, 0);
+  } finally { globalThis.fetch = original; }
+});
+
+test('headless result uses newest terminal assistant from chronological conversation history', async () => {
+  const original = globalThis.fetch;
+  try {
+    globalThis.fetch = async (url) => {
+      const pathname = new URL(url).pathname;
+      if (pathname === '/api/session') return new Response('{"data":{"id":"ses_resume"}}');
+      if (pathname.endsWith('/environment') || pathname.endsWith('/wait')) return new Response(null, { status: 204 });
+      if (pathname.endsWith('/prompt')) return new Response('{"data":{"id":"user-new"}}');
+      if (pathname === '/api/session/ses_resume') return new Response('{"data":{"id":"ses_resume","outcome":"succeeded"}}');
+      if (pathname.endsWith('/message')) return new Response(JSON.stringify({ data: [
+        { id: 'assistant-final', type: 'assistant', time: { created: 300 }, finish: 'stop', content: [{ type: 'text', text: 'final answer' }] },
+        { id: 'assistant-tool', type: 'assistant', time: { created: 250 }, finish: 'tool-calls', content: [{ type: 'tool-call', text: '' }] },
+        { id: 'user-new', type: 'user', time: { created: 200 }, content: [{ type: 'text', text: 'new prompt' }] },
+        { id: 'assistant-old', type: 'assistant', time: { created: 100 }, finish: 'stop', content: [{ type: 'text', text: 'old result' }] },
+      ] }));
+      throw new Error(`Unexpected endpoint ${pathname}`);
+    };
+    const result = await runHeadless({ url: 'http://127.0.0.1:3333', headers: {} }, '/workspace', 'continue', { sessionID: 'ses_resume' });
+    assert.deepEqual(result.messages.map((item) => item.id), ['user-new', 'assistant-tool', 'assistant-final']);
+    assert.equal(result.result.text, 'final answer');
+    assert.equal(result.result.message.id, 'assistant-final', 'a preceding tool-call assistant must not replace the final response');
+    assert.equal(result.budgetReason, undefined, 'a terminal successful resumed turn has no budget failure reason');
+  } finally { globalThis.fetch = original; }
+});
+
+test('headless fails closed for 503 outcome projection and preserves terminal idle errors', async () => {
+  const original = globalThis.fetch;
+  let projectionCalls = 0;
+  try {
+    globalThis.fetch = async (url) => {
+      const pathname = new URL(url).pathname;
+      if (pathname === '/api/session') return new Response('{"data":{"id":"ses_projection"}}');
+      if (pathname.endsWith('/environment') || pathname.endsWith('/wait')) return new Response(null, { status: 204 });
+      if (pathname.endsWith('/prompt')) return new Response('{"data":{"id":"inbox_projection"}}');
+      if (pathname === '/api/session/ses_projection') {
+        projectionCalls += 1;
+        return new Response('{"error":"projection unavailable"}', { status: 503 });
+      }
+      if (pathname.endsWith('/message')) return new Response(JSON.stringify({ data: [
+        { id: 'idle-error', type: 'idle', outcome: 'failed', error: { message: 'provider offline' }, time: { created: 300 } },
+        { id: 'user-current', type: 'user', time: { created: 200 } },
+      ] }));
+      throw new Error(`Unexpected endpoint ${pathname}`);
+    };
+    const result = await runHeadless({ url: 'http://127.0.0.1:3333', headers: {} }, '/workspace', 'go', { timeout: 100 });
+    assert.equal(projectionCalls > 0, true);
+    assert.equal(result.outcome, 'failed');
+    assert.equal(result.terminal, true);
+    assert.equal(result.error.message, 'provider offline');
+    assert.equal(result.result, undefined, 'idle failure must not accidentally select an earlier assistant result');
+  } finally { globalThis.fetch = original; }
+});
+
+test('aborting headless execution sends a native interrupt for that session', async () => {
+  const original = globalThis.fetch;
+  const paths = [];
+  try {
+    globalThis.fetch = async (url, init = {}) => {
+      const pathname = new URL(url).pathname;
+      paths.push(pathname);
+      if (pathname === '/api/session') return new Response('{"data":{"id":"ses_cancel"}}');
+      if (pathname.endsWith('/environment')) return new Response(null, { status: 204 });
+      if (pathname.endsWith('/prompt')) return new Response('{"data":{"id":"inbox_cancel"}}');
+      if (pathname.endsWith('/wait')) return pendingUntilAbort(init.signal);
+      if (pathname.endsWith('/interrupt')) return new Response(null, { status: 204 });
+      throw new Error(`Unexpected endpoint ${pathname}`);
+    };
+    const controller = new AbortController();
+    const resultPromise = runHeadless({ url: 'http://127.0.0.1:3333', headers: {} }, '/workspace', 'wait', { signal: controller.signal });
+    await new Promise((resolve) => setTimeout(resolve, 20));
+    controller.abort(new Error('test cancellation'));
+    const result = await resultPromise;
+    assert.equal(result.outcome, 'interrupted');
+    assert.equal(result.budgetReason, undefined);
+    assert.ok(paths.includes('/api/session/ses_cancel/interrupt'));
+  } finally { globalThis.fetch = original; }
+});
+
+test('headless timeout aborts the wait request and interrupts the native session', async () => {
+  const original = globalThis.fetch;
+  const paths = [];
+  try {
+    globalThis.fetch = async (url, init = {}) => {
+      const pathname = new URL(url).pathname;
+      paths.push(pathname);
+      if (pathname === '/api/session') return new Response('{"data":{"id":"ses_timeout"}}');
+      if (pathname.endsWith('/environment')) return new Response(null, { status: 204 });
+      if (pathname.endsWith('/prompt')) return new Response('{"data":{"id":"inbox_timeout"}}');
+      if (pathname.endsWith('/wait')) return pendingUntilAbort(init.signal);
+      if (pathname.endsWith('/interrupt')) return new Response(null, { status: 204 });
+      if (pathname.endsWith('/message')) return new Response('{"data":[{"id":"idle-timeout","type":"idle","outcome":"interrupted","time":{"created":3}}]}');
+      throw new Error(`Unexpected endpoint ${pathname}`);
+    };
+    const result = await runHeadless({ url: 'http://127.0.0.1:3333', headers: {} }, '/workspace', 'hang', { timeout: 30 });
+    assert.equal(result.outcome, 'interrupted');
+    assert.equal(result.terminal, true);
+    assert.equal(result.budgetReason, undefined);
+    assert.ok(paths.includes('/api/session/ses_timeout/interrupt'));
+  } finally { globalThis.fetch = original; }
+});
+
+test('headless reports timeout distinctly when no terminal outcome can be observed', async () => {
+  const original = globalThis.fetch;
+  try {
+    globalThis.fetch = async (url, init = {}) => {
+      const pathname = new URL(url).pathname;
+      if (pathname === '/api/session') return new Response('{"data":{"id":"ses_no_outcome"}}');
+      if (pathname.endsWith('/environment')) return new Response(null, { status: 204 });
+      if (pathname.endsWith('/prompt')) return new Response('{"data":{"id":"inbox_no_outcome"}}');
+      if (pathname.endsWith('/wait')) return pendingUntilAbort(init.signal);
+      if (pathname.endsWith('/interrupt')) return new Response(null, { status: 204 });
+      if (pathname.endsWith('/message')) return new Response('{"data":[]}');
+      if (pathname === '/api/session/ses_no_outcome') return new Response('{"data":{"id":"ses_no_outcome"}}');
+      throw new Error(`Unexpected endpoint ${pathname}`);
+    };
+    const result = await runHeadless({ url: 'http://127.0.0.1:3333', headers: {} }, '/workspace', 'hang', { timeout: 25 });
+    assert.equal(result.outcome, 'timed-out');
+    assert.equal(result.terminal, false);
+    assert.equal(result.budgetReason, 'timed-out');
+  } finally { globalThis.fetch = original; }
+});

package/tests/opencode-session-controls.test.mjs

@@ -0,0 +1,115 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { createJiti } from 'jiti';
+
+const jiti = createJiti(import.meta.url);
+const { registerSessionControls } = await jiti.import('../plugins/carthagent/src/server/session-controls.ts');
+
+function fixture(options = {}, sessions = {}) {
+  const values = new Map();
+  const hooks = {};
+  const calls = [];
+  let handlers;
+  const ctx = {
+    options, location: { directory: '/project' },
+    storage: { get: async key => values.get(key), set: async (key, value) => values.set(key, value) },
+    session: {
+      get: async ({ sessionID }) => ({ location: { directory: sessionID === 'foreign' ? '/other' : '/project' }, ...sessions[sessionID] }),
+      hook: async (name, hook) => { hooks[name] = hook; return { dispose: async () => { delete hooks[name]; } }; },
+      synthetic: async input => { calls.push(['synthetic', input]); },
+      compact: async input => { calls.push(['compact', input]); },
+    },
+    rpc: { register: async (_definition, implementation) => { handlers = implementation; return { dispose: async () => { handlers = undefined; } }; } },
+  };
+  return { ctx, hooks, calls, values, get handlers() { return handlers; } };
+}
+const call = () => ({
+  signal: new AbortController().signal,
+  error(type, message, data) { throw Object.assign(new Error(message), { type, data }); },
+});
+
+test('native framing is session-scoped, raw-safe and preserves attachments', async () => {
+  const f = fixture();
+  const cleanup = await registerSessionControls(f.ctx);
+  const event = { sessionID: 'a', prompt: { text: 'Implement a parser', files: [{ uri: 'file:///project/input', mention: { start: 0, end: 2, text: 'im' } }] } };
+  await f.hooks.prompt(event);
+  assert.notEqual(event.prompt.text, 'Implement a parser');
+  assert.equal(event.metadata['ctg.original'], 'Implement a parser');
+  assert.equal(event.prompt.files[0].uri, 'file:///project/input');
+  assert.equal(event.prompt.files[0].mention, undefined);
+  const once = event.prompt.text;
+  await f.hooks.prompt(event);
+  assert.equal(event.prompt.text, once);
+  const raw = { sessionID: 'a', prompt: { text: 'Implement a parser' }, metadata: { 'ctg.raw': true } };
+  await f.hooks.prompt(raw);
+  assert.equal(raw.prompt.text, 'Implement a parser');
+  await f.handlers.framing({ sessionID: 'a', enabled: false }, call());
+  const a = { sessionID: 'a', prompt: { text: 'Implement a parser' } };
+  const b = { sessionID: 'b', prompt: { text: 'Implement a parser' } };
+  await f.hooks.prompt(a);
+  await f.hooks.prompt(b);
+  assert.equal(a.prompt.text, 'Implement a parser');
+  assert.notEqual(b.prompt.text, a.prompt.text);
+  await assert.rejects(f.handlers.framing({ sessionID: 'foreign' }, call()), { type: 'wrong_workspace', data: { sessionID: 'foreign' } });
+  await cleanup();
+  assert.equal(f.hooks.prompt, undefined);
+});
+
+test('concurrent framing toggles serialize and override a disabled launch default', async () => {
+  const f = fixture({ guide: false });
+  await registerSessionControls(f.ctx);
+  const results = await Promise.all([f.handlers.framing({ sessionID: 'a' }, call()), f.handlers.framing({ sessionID: 'a' }, call())]);
+  assert.deepEqual(results, [{ enabled: true }, { enabled: false }]);
+  await f.handlers.framing({ sessionID: 'a', enabled: true }, call());
+  const event = { sessionID: 'a', prompt: { text: 'Implement a parser' } };
+  await f.hooks.prompt(event);
+  assert.notEqual(event.prompt.text, 'Implement a parser');
+});
+
+test('compaction notes precede queued compaction and cancellation prevents admission', async () => {
+  const f = fixture();
+  await registerSessionControls(f.ctx);
+  assert.deepEqual(await f.handlers.compact({ sessionID: 'a', notes: 'Preserve unresolved decisions' }, call()), { admitted: true });
+  assert.deepEqual(f.calls.map(item => item[0]), ['synthetic', 'compact']);
+  assert.match(f.calls[0][1].text, /Preserve unresolved decisions/);
+  assert.ok(f.calls.every(item => item[1].sessionID === 'a' && item[1].delivery === 'queue'));
+  await assert.rejects(f.handlers.compact({ sessionID: 'a' }, { signal: AbortSignal.abort() }));
+  assert.equal(f.calls.length, 2);
+});
+
+test('persisted per-session launcher settings control framing without affecting neighbors', async () => {
+  const f = fixture({}, {
+    a: { metadata: { 'carthagent.options': { guide: false } } },
+    b: { metadata: { 'carthagent.options': { delivery: false } } },
+  });
+  await registerSessionControls(f.ctx);
+  for (const sessionID of ['a', 'b']) {
+    const event = { sessionID, prompt: { text: 'Implement a parser' } };
+    await f.hooks.prompt(event);
+    assert.equal(event.prompt.text, 'Implement a parser');
+  }
+  assert.deepEqual(await f.handlers.framing({ sessionID: 'a' }, call()), { enabled: true });
+  const event = { sessionID: 'a', prompt: { text: 'Implement a parser' } };
+  await f.hooks.prompt(event);
+  assert.notEqual(event.prompt.text, 'Implement a parser');
+});
+
+test('queued controls recheck ownership after a session moves', async () => {
+  const f = fixture();
+  let releaseWrite;
+  let beganWrite;
+  const writing = new Promise(resolve => { beganWrite = resolve; });
+  const gate = new Promise(resolve => { releaseWrite = resolve; });
+  let directory = '/project';
+  f.ctx.session.get = async () => ({ location: { directory } });
+  f.ctx.storage.set = async () => { beganWrite(); await gate; };
+  await registerSessionControls(f.ctx);
+  const first = f.handlers.framing({ sessionID: 'a', enabled: true }, call());
+  await writing;
+  const queued = f.handlers.compact({ sessionID: 'a', notes: 'Must not be admitted after move' }, call());
+  directory = '/other';
+  releaseWrite();
+  await first;
+  await assert.rejects(queued, { type: 'wrong_workspace', data: { sessionID: 'a' } });
+  assert.deepEqual(f.calls, []);
+});

package/tests/opencode-session-options.test.mjs

@@ -0,0 +1,26 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { resolve } from 'node:path';
+import { effectiveSessionOptions, normalizeSessionOptions, sessionOptionsMetadata } from '../lib/opencode/session-options.mjs';
+
+test('native session options isolate concurrent settings and resolve paths at the owning worktree', () => {
+  const defaults = { maxTools: 5, workflow: 'standard' };
+  const a = { location: { directory: resolve('first') }, metadata: sessionOptionsMetadata({ maxTools: '8', guide: false, validators: 'checks.json' }, resolve('first'), { other: true }) };
+  const b = { location: { directory: resolve('second') }, metadata: sessionOptionsMetadata({ maxTools: 2, workflow: 'strict' }, resolve('second')) };
+  assert.equal(effectiveSessionOptions(a, defaults).maxTools, 8);
+  assert.equal(effectiveSessionOptions(b, defaults).maxTools, 2);
+  assert.equal(effectiveSessionOptions(a, defaults).validators, resolve('first/checks.json'));
+  assert.equal(effectiveSessionOptions(a, defaults).guide, false);
+  assert.equal(effectiveSessionOptions(b, defaults).guide, true);
+  assert.deepEqual(defaults, { maxTools: 5, workflow: 'standard' });
+  assert.equal(a.metadata.other, true);
+});
+
+test('invalid persisted limits fail closed and non-runtime options never enter metadata', () => {
+  for (const options of [{ maxTools: -1 }, { maxSeconds: 'no' }, { codegraphMaxFiles: 0 }, { guide: 'false' }, { workflow: 'anything' }]) {
+    assert.throws(() => normalizeSessionOptions(options));
+  }
+  assert.deepEqual(normalizeSessionOptions({ delivery: false, maxTools: 1 }), { delivery: false, maxTools: 1 }, 'budget remains configured independently of delivery workflow participation');
+  assert.deepEqual(normalizeSessionOptions({ apiKey: 'secret', theme: 'carthage', model: 'provider/model', guide: false }), { guide: false });
+  assert.throws(() => effectiveSessionOptions({ location: { directory: resolve('.') }, metadata: { 'carthagent.options': [] } }), /persisted/);
+});