carthagent 0.0.0-stage → 1.0.7

package/tests/update-channels.test.mjs

@@ -0,0 +1,129 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { createServer } from 'node:http';
+import { once } from 'node:events';
+import { cp, mkdir, mkdtemp, readFile, rm, symlink, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { fetchLatestRelease, latestReleaseCached, normalizeRelease } from '../lib/update.mjs';
+import { parseUpdateOptions, readUpdateChannel, writeUpdateChannel } from '../lib/update-channel.mjs';
+
+const release = (version, extra = {}) => ({ tag_name: `v${version}`, draft: false, prerelease: version.includes('-'), ...extra });
+async function fixture(t, pages = [[]], stable = release('1.0.7')) {
+  const dir = await mkdtemp(join(tmpdir(), 'ctg-update-channels-'));
+  const env = { CARTHAGENT_UPDATE_CHANNEL_FILE: join(dir, 'channel.json') };
+  const requests = [];
+  const server = createServer((req, res) => {
+    const url = new URL(req.url, 'http://localhost');
+    requests.push({ url, headers: req.headers });
+    const body = url.pathname.endsWith('/releases/latest') ? stable : pages[Number(url.searchParams.get('page') || 1) - 1] ?? [];
+    res.writeHead(200, { 'content-type': 'application/json' });
+    res.end(JSON.stringify(body));
+  });
+  server.listen(0, '127.0.0.1');
+  await once(server, 'listening');
+  t.after(async () => { server.closeAllConnections(); await new Promise(resolve => server.close(resolve)); await rm(dir, { recursive: true, force: true }); });
+  const base = `http://127.0.0.1:${server.address().port}`;
+  const fetchImpl = (url, options) => fetch(`${base}${new URL(url).pathname}${new URL(url).search}`, options);
+  return { dir, env, requests, base, options: { env, agentDir: join(dir, 'agent'), cloudUrl: base, fetchImpl } };
+}
+
+test('channel flags are explicit, validated, and do not reinterpret arbitrary update arguments', () => {
+  assert.deepEqual(parseUpdateOptions([]), { checkOnly: false, force: false, channel: null });
+  assert.deepEqual(parseUpdateOptions(['--channel', 'experimental', '--check']), { checkOnly: true, force: false, channel: 'experimental' });
+  assert.equal(parseUpdateOptions(['--channel=beta', '--force']).channel, 'beta');
+  for (const args of [['--channel'], ['--channel', 'nightly'], ['--channel', 'beta', '--channel', 'stable'], ['--tag', 'main']]) assert.throws(() => parseUpdateOptions(args));
+});
+
+test('channel preference defaults stable, is versioned and isolated, and rejects corrupt opt-in', async t => {
+  const f = await fixture(t);
+  assert.equal(readUpdateChannel(f.env), 'stable');
+  writeUpdateChannel('experimental', f.env);
+  assert.equal(readUpdateChannel(f.env), 'experimental');
+  assert.deepEqual(JSON.parse(await readFile(f.env.CARTHAGENT_UPDATE_CHANNEL_FILE, 'utf8')), { version: 1, channel: 'experimental' });
+  assert.throws(() => writeUpdateChannel('main', f.env));
+  await writeFile(f.env.CARTHAGENT_UPDATE_CHANNEL_FILE, '{broken');
+  assert.throws(() => readUpdateChannel(f.env), /channel/i);
+});
+
+test('stable refuses prereleases even when misadvertised by the control plane or latest API', async t => {
+  const f = await fixture(t, [], release('9.0.0-beta.1'));
+  await assert.rejects(fetchLatestRelease(f.options), /stable/i);
+  assert.equal(f.requests.length, 2);
+  assert.equal(normalizeRelease({ version: '1.0.7', tag: 'main' }), null);
+});
+
+test('beta selects the greatest eligible semver, ignores drafts, and excludes experimental tags', async t => {
+  const f = await fixture(t, [[release('2.0.0-beta.2'), release('2.0.0-beta.10'), release('3.0.0-experimental.1'), release('99.0.0-beta.1', { draft: true }), release('1.0.7'), release('2.0.0-rc.1')]]);
+  const result = await fetchLatestRelease({ ...f.options, channel: 'beta' });
+  assert.equal(result.release.version, '2.0.0-rc.1');
+  assert.equal(result.release.installSpec, 'github:B-icy/Carthagent#v2.0.0-rc.1');
+  assert.equal(f.requests.length, 1);
+  assert.equal(f.requests[0].headers['x-carthagent-install-id'], undefined);
+});
+
+test('experimental opts into all published prereleases and follows saved preference', async t => {
+  const f = await fixture(t, [[release('1.1.0-preview.1'), release('1.0.7'), release('1.1.0-beta.2'), release('8.0.0-alpha.1', { draft: true })]]);
+  writeUpdateChannel('experimental', f.env);
+  const result = await fetchLatestRelease(f.options);
+  assert.equal(result.release.version, '1.1.0-preview.1');
+  assert.equal(result.source, 'github');
+});
+
+test('release selection paginates instead of trusting GitHub creation order', async t => {
+  const f = await fixture(t, [Array.from({ length: 100 }, (_, i) => release(`1.0.${i}`)), [release('2.0.0-beta.5')]]);
+  assert.equal((await fetchLatestRelease({ ...f.options, channel: 'beta' })).release.version, '2.0.0-beta.5');
+  assert.equal(f.requests.length, 2);
+});
+
+test('published stable versions supersede beta versions without accepting unknown beta labels', async t => {
+  const f = await fixture(t, [[release('2.0.0-beta.2'), release('2.0.0'), release('3.0.0-nightly.1'), release('3.0.0-beta-unsafe.1')]]);
+  assert.equal((await fetchLatestRelease({ ...f.options, channel: 'beta' })).release.version, '2.0.0');
+});
+
+test('channel caches never leak a cached experimental release into stable', async t => {
+  const f = await fixture(t, [[release('2.0.0-preview.1')]]);
+  const cachePath = join(f.dir, 'cache.json');
+  const first = await latestReleaseCached({ ...f.options, cachePath, channel: 'experimental' });
+  assert.equal(first.release.version, '2.0.0-preview.1');
+  const stable = await latestReleaseCached({ ...f.options, cachePath, channel: 'stable' });
+  assert.equal(stable.release.version, '1.0.7');
+  await writeFile(cachePath, JSON.stringify({ checkedAt: Date.now(), channel: 'experimental', release: first.release }));
+  const offline = await latestReleaseCached({ ...f.options, cachePath, channel: 'stable', fetchImpl: async () => { throw Error('offline'); } });
+  assert.equal(offline.release, null);
+});
+
+test('CLI --check previews channel rollback without persisting or installing', async t => {
+  const f = await fixture(t, [], release('0.0.1'));
+  writeUpdateChannel('experimental', f.env);
+  const child = spawn(process.execPath, ['bin/ctg.mjs', 'update', '--channel', 'stable', '--check'], {
+    cwd: new URL('..', import.meta.url), env: { ...process.env, ...f.env, CARTHAGENT_CLOUD_URL: f.base, CARTHAGENT_CODING_AGENT_DIR: join(f.dir, 'agent') }, stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  let output = ''; child.stdout.on('data', data => output += data); child.stderr.on('data', data => output += data);
+  const [code] = await once(child, 'close');
+  assert.equal(code, 0, output);
+  assert.match(output, /0\.0\.1.*available/);
+  assert.match(output, /stable/);
+  assert.equal(readUpdateChannel(f.env), 'experimental');
+});
+
+
+test('failed real clone update does not persist a requested channel switch', async t => {
+  const f = await fixture(t, [], release('999.0.0'));
+  const copy = join(f.dir, 'broken-clone');
+  await mkdir(copy);
+  for (const name of ['lib', 'bin', 'package.json']) await cp(new URL(`../${name}`, import.meta.url), join(copy, name), { recursive: true });
+  await symlink(fileURLToPath(new URL('../node_modules', import.meta.url)), join(copy, 'node_modules'), 'junction');
+  await mkdir(join(copy, '.git'));
+  writeUpdateChannel('experimental', f.env);
+  const child = spawn(process.execPath, [join(copy, 'bin/ctg.mjs'), 'update', '--channel', 'stable'], {
+    cwd: copy, env: { ...process.env, ...f.env, CARTHAGENT_CLOUD_URL: f.base, CARTHAGENT_CODING_AGENT_DIR: join(f.dir, 'agent') }, stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  let output = ''; child.stdout.on('data', data => output += data); child.stderr.on('data', data => output += data);
+  const [code] = await once(child, 'close');
+  assert.equal(code, 1, output);
+  assert.match(output, /Cannot inspect the clone/);
+  assert.equal(readUpdateChannel(f.env), 'experimental');
+});

package/tests/update.test.mjs

@@ -0,0 +1,175 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { basename, join } from 'node:path';
+import {
+  cleanStaleGlobalInstall,
+  compareVersions,
+  detectInstallMethod,
+  fetchLatestRelease,
+  latestReleaseCached,
+  normalizeRelease,
+  staleGlobalInstallPaths,
+  updateCheckEnabled,
+} from '../lib/update.mjs';
+
+const manifest = { version: '0.3.0', tag: 'v0.3.0', installSpec: 'github:B-icy/Carthagent#v0.3.0', minNode: '22.19.0' };
+
+function withTempDir(fn) {
+  const dir = mkdtempSync(join(tmpdir(), 'ctg-update-'));
+  return Promise.resolve().then(() => fn(dir)).finally(() => rmSync(dir, { recursive: true, force: true }));
+}
+
+// ---- compareVersions
+
+test('compareVersions orders numeric triples', () => {
+  assert.equal(compareVersions('0.2.0', '0.3.0') < 0, true);
+  assert.equal(compareVersions('1.0.0', '0.9.9') > 0, true);
+  assert.equal(compareVersions('0.3.0', '0.3.0'), 0);
+});
+
+test('compareVersions strips a leading v and ignores build metadata', () => {
+  assert.equal(compareVersions('v0.3.0', '0.3.0+build7'), 0);
+});
+
+test('compareVersions ranks a release above its prereleases', () => {
+  assert.equal(compareVersions('0.3.0-rc.1', '0.3.0') < 0, true);
+  assert.equal(compareVersions('0.3.0-beta', '0.3.0-rc.1') < 0, true);
+  assert.equal(compareVersions('0.3.0-alpha.2', '0.3.0-alpha.10') < 0, true);
+});
+
+test('compareVersions rejects non-semver input', () => {
+  assert.throws(() => compareVersions('latest', '0.3.0'), /cannot compare/);
+});
+
+// ---- normalizeRelease
+
+test('normalizeRelease accepts the control-plane manifest shape', () => {
+  const rel = normalizeRelease({ ...manifest, publishedAt: '2026-01-01T00:00:00Z' });
+  assert.equal(rel.version, '0.3.0');
+  assert.equal(rel.tag, 'v0.3.0');
+  assert.equal(rel.installSpec, 'github:B-icy/Carthagent#v0.3.0');
+  assert.equal(rel.publishedAt, '2026-01-01T00:00:00Z');
+});
+
+test('normalizeRelease maps a GitHub release payload', () => {
+  const rel = normalizeRelease({
+    tag_name: 'v0.4.0',
+    published_at: '2026-02-01T00:00:00Z',
+    name: 'Carthagent 0.4.0',
+  });
+  assert.equal(rel.version, '0.4.0');
+  assert.equal(rel.tag, 'v0.4.0');
+  assert.equal(rel.installSpec, 'github:B-icy/Carthagent#v0.4.0');
+  assert.equal(rel.note, 'Carthagent 0.4.0');
+});
+
+test('normalizeRelease fills defaults and returns null on unusable payloads', () => {
+  assert.equal(normalizeRelease(null), null);
+  assert.equal(normalizeRelease({ tag_name: 'release-2' }), null);
+  const filled = normalizeRelease({ version: '0.5.0' });
+  assert.equal(filled.tag, 'v0.5.0');
+  assert.equal(filled.installSpec, 'github:B-icy/Carthagent#v0.5.0');
+});
+
+test('normalizeRelease rejects install specs that do not install the release tag', () => {
+  // The manifest doubles as an install instruction: a tampered spec must
+  // never reach `npm install -g`.
+  assert.equal(normalizeRelease({ ...manifest, installSpec: 'github:attacker/evil#v9.9.9' }), null);
+  assert.equal(normalizeRelease({ ...manifest, installSpec: 'github:B-icy/Carthagent#v0.2.0' }), null);
+  assert.equal(normalizeRelease({ ...manifest, installSpec: 'carthagent@latest' }), null);
+  assert.equal(normalizeRelease(manifest).installSpec, 'github:B-icy/Carthagent#v0.3.0');
+});
+
+test('fetchLatestRelease falls back to GitHub when the manifest fails validation', async () => {
+  // A control-plane 200 whose installSpec is rejected must not dead-end the
+  // update — the GitHub release still resolves.
+  const urls = [];
+  const fetchImpl = async url => {
+    urls.push(url);
+    if (url.includes('/v1/cli/releases/latest')) {
+      return { status: 200, json: async () => ({ ...manifest, installSpec: 'carthagent@latest' }) };
+    }
+    return { status: 200, json: async () => ({ tag_name: 'v0.3.1', published_at: '2026-03-01T00:00:00Z' }) };
+  };
+  const { release, source } = await fetchLatestRelease({ cloudUrl: 'https://cloud.test', fetchImpl });
+  assert.equal(source, 'github');
+  assert.equal(release.version, '0.3.1');
+  assert.equal(release.installSpec, 'github:B-icy/Carthagent#v0.3.1');
+  assert.equal(urls.length, 2);
+});
+
+// ---- latestReleaseCached
+
+test('latestReleaseCached fetches once, then serves the cache', () => withTempDir(async dir => {
+  const cachePath = join(dir, 'update-check.json');
+  let calls = 0;
+  const fetchImpl = async () => { calls++; return { status: 200, json: async () => manifest }; };
+  // Pinned clock: a slow runner must not outrun the cache TTL mid-test.
+  const t0 = Date.now();
+  const first = await latestReleaseCached({ cachePath, intervalMs: 1000, now: t0, fetchImpl });
+  assert.equal(first.release.version, '0.3.0');
+  assert.equal(first.fresh, false);
+  assert.equal(calls, 1);
+  const second = await latestReleaseCached({ cachePath, intervalMs: 1000, now: t0 + 500, fetchImpl });
+  assert.equal(second.release.version, '0.3.0');
+  assert.equal(second.fresh, true);
+  assert.equal(calls, 1);
+}));
+
+test('latestReleaseCached returns stale data when refresh fails', () => withTempDir(async dir => {
+  const cachePath = join(dir, 'update-check.json');
+  writeFileSync(cachePath, JSON.stringify({ checkedAt: Date.now() - 60_000, release: manifest }));
+  const result = await latestReleaseCached({ cachePath, intervalMs: 1000, fetchImpl: async () => { throw new Error('offline'); } });
+  assert.equal(result.release.version, '0.3.0');
+  assert.equal(result.fresh, false);
+}));
+
+test('latestReleaseCached swallows a cold-cache failure', () => withTempDir(async dir => {
+  const result = await latestReleaseCached({ cachePath: join(dir, 'update-check.json'), intervalMs: 1000, fetchImpl: async () => { throw new Error('offline'); } });
+  assert.equal(result.release, null);
+}));
+
+// ---- updateCheckEnabled / detectInstallMethod
+
+test('updateCheckEnabled honours opt-out env vars', () => {
+  assert.equal(updateCheckEnabled({}), true);
+  assert.equal(updateCheckEnabled({ CARTHAGENT_NO_UPDATE_CHECK: '1' }), false);
+  assert.equal(updateCheckEnabled({ CARTHAGENT_UPDATE_CHECK: '0' }), false);
+  assert.equal(updateCheckEnabled({ CARTHAGENT_UPDATE_CHECK: 'false' }), false);
+  assert.equal(updateCheckEnabled({ CARTHAGENT_UPDATE_CHECK: '1' }), true);
+});
+
+test('detectInstallMethod distinguishes clones from packed installs', () => withTempDir(dir => {
+  assert.equal(detectInstallMethod(dir), 'npm');
+  mkdirSync(join(dir, '.git'));
+  assert.equal(detectInstallMethod(dir), 'clone');
+}));
+
+// ---- staleGlobalInstallPaths / cleanStaleGlobalInstall
+
+test('staleGlobalInstallPaths flags non-directory carthagent and stash leftovers', () => withTempDir(dir => {
+  writeFileSync(join(dir, 'carthagent'), 'stray file');
+  mkdirSync(join(dir, '.carthagent-WHcGBFBt'));
+  mkdirSync(join(dir, 'other-pkg'));
+  const stale = staleGlobalInstallPaths(dir).map(p => basename(p));
+  assert.deepEqual(stale.sort(), ['.carthagent-WHcGBFBt', 'carthagent']);
+}));
+
+test('staleGlobalInstallPaths leaves a real carthagent install alone', () => withTempDir(dir => {
+  mkdirSync(join(dir, 'carthagent'));
+  assert.deepEqual(staleGlobalInstallPaths(dir), []);
+}));
+
+test('staleGlobalInstallPaths ignores a missing npm root', () => {
+  assert.deepEqual(staleGlobalInstallPaths(join(tmpdir(), 'ctg-no-such-dir')), []);
+});
+
+test('cleanStaleGlobalInstall removes flagged entries and reports them', () => withTempDir(dir => {
+  writeFileSync(join(dir, 'carthagent'), 'stray file');
+  writeFileSync(join(dir, '.carthagent-abandoned'), 'stash leftover');
+  const removed = cleanStaleGlobalInstall(dir);
+  assert.equal(removed.length, 2);
+  assert.deepEqual(staleGlobalInstallPaths(dir), []);
+}));

package/tests/webdriver.test.mjs

@@ -0,0 +1,31 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const tool = fileURLToPath(new URL('../tools/webdriver-check.mjs', import.meta.url));
+test('WebDriver CLI rejects unsupported options and unavailable driver without fallback', () => {
+  for (const args of [['--console-clean'], ['--endpoint', 'http://127.0.0.1:1', '--assert', '#app'], ['--endpoint', 'http://127.0.0.1:1', '--assert', '#app', '--wait-ms', 'NaN'], ['--endpoint', 'http://127.0.0.1:1', '--assert', '#app', '--url', 'file:///tmp/test'], ['--endpoint', 'http://127.0.0.1:1', '--assert', '#app', '--url', 'http://localhost', '--root', '.']]) {
+    const result = spawnSync(process.execPath, [tool, ...args], { encoding: 'utf8', timeout: 10000 });
+    assert.equal(result.status, 1, result.stderr);
+    const failure = JSON.parse(result.stderr);
+    assert.equal(failure.pass, false);
+    assert.ok(['driver', 'configuration'].includes(failure.category));
+  }
+});
+
+test('missing BiDi support fails closed before navigation and deletes session', async () => {
+  const { createServer } = await import('node:http');
+  const { webdriverCheck } = await import('../lib/webdriver.mjs');
+  const requests = [];
+  const server = createServer((req, res) => {
+    requests.push([req.method, req.url]);
+    res.setHeader('content-type', 'application/json');
+    res.end(JSON.stringify({ value: req.method === 'POST' ? { sessionId: 'test', capabilities: {} } : null }));
+  });
+  await new Promise(r => server.listen(0, '127.0.0.1', r));
+  try {
+    await assert.rejects(webdriverCheck({ endpoint: `http://127.0.0.1:${server.address().port}`, url: 'http://localhost' }), error => error.category === 'capture');
+    assert.deepEqual(requests, [['POST', '/session'], ['DELETE', '/session/test']]);
+  } finally { await new Promise(r => server.close(r)); }
+});

package/tests/workflow.test.mjs

@@ -0,0 +1,47 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { validateWorkflow, workflowGraph, workflowD2, architectureGraph } from '../lib/workflow.mjs';
+import { planD2WithProgress } from '../lib/delivery.mjs';
+import { parseD2 } from '../lib/tui/d2.mjs';
+
+function plan() {
+  const node = (id, step, dependsOn = []) => ({ id, step, dependsOn, title: `Task ${id}`, type: 'work', requirements: ['Works'], components: ['policy'], checks: ['unit'], inputs: [], artifacts: [], effects: ['write'] });
+  return { goal: 'Workflow', steps: [{ id: 'api', title: 'API' }, { id: 'ui', title: 'UI' }], acceptance: [{ requirement: 'Works', checks: ['unit'] }], checks: [{ id: 'unit' }], design: { components: [{ id: 'policy', responsibility: 'Policy', layer: 'core', dependencies: [] }], ports: [] }, workflow: { nodes: [node('server', 'api'), node('client', 'ui', ['server'])], recovery: [{ from: 'client', to: 'server', when: 'Contract mismatch', maxAttempts: 2, stop: 'Report blocked' }] } };
+}
+test('agent workflow preserves branches/recovery and mandatory gate overlay', () => {
+  const p = plan();
+  assert.deepEqual(validateWorkflow(p), []);
+  const graph = workflowGraph(p);
+  assert.ok(graph.authored);
+  assert.equal(graph.nodes.filter(n => n.type === 'gate').length, 4);
+  assert.ok(graph.edges.some(e => e.kind === 'recovery' && e.maxAttempts === 2));
+  const source = planD2WithProgress(p, { step0: 'done' });
+  assert.match(source, /Task server \[done\]/);
+  assert.equal(parseD2(source).nodes.length, 6);
+  assert.equal(architectureGraph(p).nodes[0].layer, 'core');
+});
+test('invalid workflow references, cycles, effects, steps and unbounded recovery fail', () => {
+  for (const mutate of [
+    p => p.workflow.nodes[0].dependsOn.push('client'),
+    p => p.workflow.nodes[0].dependsOn.push('missing'),
+    p => p.workflow.nodes[0].id = 'gate_design',
+    p => p.workflow.nodes[0].effects.push('deploy'),
+    p => p.workflow.nodes.pop(),
+    p => p.workflow.recovery[0].maxAttempts = 0,
+    p => p.workflow.nodes[0].components.push('missing'),
+  ]) {
+    const p = plan(); mutate(p);
+    assert.ok(validateWorkflow(p).length);
+    assert.throws(() => workflowGraph(p));
+  }
+});
+test('labels are data, not injectable D2 commands; legacy projection is available', () => {
+  const p = plan();
+  p.workflow.nodes[0].title = 'quoted "title"\ngate_design -> hacked';
+  const graph = parseD2(workflowD2(p));
+  assert.equal(graph.nodes.length, 6);
+  assert.equal(graph.nodes.find(n => n.id === 'server').label, p.workflow.nodes[0].title + ' [pending]');
+  delete p.workflow;
+  assert.equal(workflowGraph(p).authored, false);
+  assert.match(planD2WithProgress(p), /Verify checks/);
+});

package/tests/workspace-rpc.test.mjs

@@ -0,0 +1,236 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { execFileSync } from 'node:child_process';
+import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createRequire } from 'node:module';
+import { createReport } from '../lib/reports.mjs';
+import { checkDigest, fingerprint } from '../lib/delivery.mjs';
+import { selectReport } from '../lib/workspace.mjs';
+
+const require = createRequire(import.meta.url);
+const { createJiti } = require('jiti');
+const jiti = createJiti(import.meta.url);
+const { registerWorkspaceRpc } = await jiti.import('../plugins/carthagent/src/server/workspace-rpc.ts');
+
+function git(cwd, ...args) { return execFileSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim(); }
+
+test('native workspace RPC snapshots journaled sessions, enforces location ownership, and aborts requests', async t => {
+  const base = mkdtempSync(join(tmpdir(), 'workspace-rpc-')); t.after(() => rmSync(base, { recursive: true, force: true }));
+  const root = join(base, 'project'); mkdirSync(root); git(root, 'init', '-q');
+  const other = join(base, 'other'); mkdirSync(other);
+  const sessionMap = new Map([
+    ['root-session', { id: 'root-session', projectID: 'project-id', location: { directory: root }, title: 'Untracked UI session', outcome: 'succeeded', time: { updated: Date.now() } }],
+    ['task-session', { id: 'task-session', projectID: 'project-id', location: { directory: join(base, 'worktree'), workspaceID: 'workspace' }, title: 'Task session', outcome: 'failed', time: { updated: Date.now() } }],
+    ['foreign-session', { id: 'foreign-session', projectID: 'other-project', location: { directory: other }, title: 'Not ours', time: { updated: Date.now() } }],
+  ]);
+  const registered = {};
+  const eventQueue = [];
+  let wake;
+  const events = {
+    push(event) { eventQueue.push(event); wake?.(); },
+    async *[Symbol.asyncIterator]({ signal } = {}) {
+      while (true) {
+        if (signal?.aborted) return;
+        if (!eventQueue.length) await new Promise(resolve => {
+          wake = resolve;
+          signal?.addEventListener('abort', resolve, { once: true });
+        });
+        wake = undefined;
+        while (eventQueue.length) yield eventQueue.shift();
+      }
+    },
+  };
+  const emitted = [];
+  const ctx = {
+    location: { directory: root, project: { id: 'project-id', canonical: root } },
+    session: {
+      async get({ sessionID }, options) { options?.signal?.throwIfAborted(); const found = sessionMap.get(sessionID); if (!found) throw Error('missing'); return found; },
+      async create(input, options) { options?.signal?.throwIfAborted(); const id = `created-${sessionMap.size}`; sessionMap.set(id, { id, projectID: 'project-id', location: input.location, title: input.title, time: { updated: Date.now() } }); return { id }; },
+    },
+    worktree: { async create({ projectID, name }, options) { options?.signal?.throwIfAborted(); assert.equal(projectID, 'project-id'); assert.ok(name); return { directory: join(base, 'new-worktree') }; } },
+    rpc: { async register(_definition, handlers) { Object.assign(registered, handlers); return { events: { async emit(name, payload) { emitted.push({ name, payload }); } }, dispose() {} }; } },
+    event: { subscribe: ({ signal }) => ({ [Symbol.asyncIterator]: () => events[Symbol.asyncIterator]({ signal }) }) },
+  };
+  const taskDir = join(base, 'worktree'); mkdirSync(taskDir);
+  const statePath = join(root, '.harness/opencode-tasks.json'); mkdirSync(join(root, '.harness'));
+  writeFileSync(statePath, JSON.stringify({ version: 1, tasks: [{ id: 'task-1', task: 'Tracked task', sessionID: 'task-session', worktree: taskDir, status: 'active' }], operations: [] }));
+  const dispose = await registerWorkspaceRpc(ctx);
+  t.after(dispose);
+
+  const data = await registered.snapshot({}, { signal: new AbortController().signal });
+  assert.equal(data.sessions.length, 1, 'only task sessions can be inventoried by the plugin Context');
+  assert.deepEqual(data.tasks.map(task => task.id), ['task-1']);
+  assert.equal(data.tasks[0].attention, true, 'native failed outcome is surfaced');
+  assert.equal(Object.hasOwn(data.tasks[0], 'branch'), false, 'undefined optional branch is omitted from RPC output');
+  assert.equal(data.sessions[0].id, 'task-session');
+
+  await assert.rejects(registered.open({ sessionID: 'foreign-session' }, { signal: new AbortController().signal }), /another workspace location/);
+  assert.deepEqual(await registered.open({ sessionID: 'root-session' }, { signal: new AbortController().signal }), { opened: true, directory: root });
+  assert.deepEqual(await registered.createWorktree({ projectID: 'project-id', name: 'task' }, { signal: new AbortController().signal }), { directory: join(base, 'new-worktree') });
+  await assert.rejects(registered.createWorktree({ projectID: 'other-project', name: 'task' }, { signal: new AbortController().signal }), /outside this OpenCode workspace/);
+  const controller = new AbortController(); controller.abort(new Error('cancelled'));
+  await assert.rejects(registered.snapshot({}, { signal: controller.signal }), /cancelled/);
+  await new Promise(resolve => setTimeout(resolve, 20));
+  events.push({ id: 'event-1', created: Date.now(), type: 'session.execution.started', data: { sessionID: 'task-session' }, durable: { aggregateID: 'task-session', seq: 2, version: 1 } });
+  const deadline = Date.now() + 1000;
+  while (!emitted.length && Date.now() < deadline) await new Promise(resolve => setTimeout(resolve, 10));
+  assert.equal(emitted[0]?.name, 'updated');
+  assert.deepEqual(Object.keys(emitted[0]?.payload ?? {}), ['revision']);
+  const inFlight = await registered.snapshot({}, { signal: new AbortController().signal });
+  assert.equal(inFlight.sessions[0].status, 'running');
+});
+
+test('registration failures reject setup and cannot leave an active unregistered bridge', async t => {
+  const root = mkdtempSync(join(tmpdir(), 'workspace-rpc-register-')); t.after(() => rmSync(root, { recursive: true, force: true }));
+  git(root, 'init', '-q');
+  let subscribed = false;
+  const ctx = {
+    location: { directory: root, project: { id: 'project-id', canonical: root } }, session: {}, worktree: {},
+    rpc: { async register() { throw new Error('registration rejected'); } },
+    event: { subscribe: () => { subscribed = true; return { async *[Symbol.asyncIterator]() {} }; } },
+  };
+  await assert.rejects(registerWorkspaceRpc(ctx), /registration rejected/);
+  assert.equal(subscribed, false, 'event stream should not start when RPC registration fails');
+});
+
+test('durable task creation propagates cancellation into native worktree creation', async t => {
+  const base = mkdtempSync(join(tmpdir(), 'workspace-rpc-cancel-')); t.after(() => rmSync(base, { recursive: true, force: true }));
+  const root = join(base, 'project'); mkdirSync(root); git(root, 'init', '-q');
+  const registered = {};
+  const controller = new AbortController();
+  const ctx = {
+    location: { directory: root, project: { id: 'project-id', canonical: root } }, session: {},
+    worktree: { async create(_input, { signal }) { assert.equal(signal, controller.signal); controller.abort(new Error('cancelled create')); signal.throwIfAborted(); } },
+    rpc: { async register(_definition, handlers) { Object.assign(registered, handlers); return { events: { async emit() {} }, dispose() {} }; } },
+    event: { subscribe: () => ({ async *[Symbol.asyncIterator]() {} }) },
+  };
+  const dispose = await registerWorkspaceRpc(ctx, { reviewModel: { providerID: 'fixture', id: 'review-model' } }); t.after(dispose);
+  await assert.rejects(registered.createTask({ task: 'cancel me' }, { signal: controller.signal }), /cancelled create/);
+  const journal = JSON.parse(readFileSync(join(root, '.harness/opencode-tasks.json'), 'utf8'));
+  assert.equal(journal.operations[0].status, 'recovery-required');
+});
+
+test('delivery RPC returns bounded authoritative session report projections and rejects stale, foreign, and corrupt reports', async t => {
+  const root = mkdtempSync(join(tmpdir(), 'workspace-rpc-delivery-')); t.after(() => rmSync(root, { recursive: true, force: true }));
+  git(root, 'init', '-q');
+  writeFileSync(join(root, 'source.txt'), 'before');
+  const sessionID = 'delivery-session';
+  const session = { id: sessionID, projectID: 'project-id', location: { directory: root }, title: 'Delivery', time: { updated: Date.now() } };
+  const sessions = new Map([[sessionID, session], ['foreign-session', { ...session, id: 'foreign-session' }]]);
+  const registered = {};
+  let workspaceContract;
+  const ctx = {
+    location: { directory: root, project: { id: 'project-id', canonical: root } },
+    session: { async get({ sessionID: id }) { const value = sessions.get(id); if (!value) throw Error('missing'); return value; } },
+    worktree: {},
+    rpc: { async register(definition, handlers) { workspaceContract = definition; Object.assign(registered, handlers); return { events: { async emit() {} }, dispose() {} }; } },
+    event: { subscribe: () => ({ async *[Symbol.asyncIterator]() {} }) },
+  };
+  const dispose = await registerWorkspaceRpc(ctx); t.after(dispose);
+  const check = { id: 'unit', kind: 'test', argv: ['node', '--test'], timeoutSeconds: 20 };
+  const plan = {
+    goal: 'Deliver a visible feature', verification: 'required', artifacts: ['.'], outputs: [],
+    steps: [{ id: 'implement', title: 'Implement feature', dependsOn: [], checks: ['unit'] }],
+    acceptance: [{ requirement: 'Feature is visible', checks: ['unit'] }], checks: [check],
+    design: { components: [{ id: 'core', responsibility: 'Own feature behavior', layer: 'core', excludes: ['UI'], dependencies: [], requirements: ['Feature is visible'] }], ports: [] },
+  };
+  const runId = 'run-1';
+  const current = fingerprint(root, ['.']);
+  const report = createReport(root, { runId, revision: 2, status: 'implementing', plan,
+    stepStatus: { step0: 'active' }, reviewEvidence: { runId, revision: 2, fingerprint: current },
+    evidence: { unit: { runId, revision: 2, checkDigest: checkDigest(check), passed: true, fingerprint: current, executedRevision: 2, durationMs: 9, code: 0, logPath: join(root, '.harness', sessionID, runId, 'logs', 'unit.log'), outputTail: 'must not leave the report DTO' } },
+  }, sessionID);
+  selectReport(root, report.path);
+  const signal = new AbortController().signal;
+  const result = await registered.delivery({ sessionID }, { signal });
+  assert.equal(result.status, 'implementing');
+  assert.equal(result.freshness, 'current');
+  assert.equal(result.runId, runId);
+  assert.equal(result.revision, 2);
+  assert.deepEqual(result.plan.acceptance, [{ requirement: 'Feature is visible', checks: ['unit'] }]);
+  assert.equal(result.plan.steps[0].status, 'active');
+  assert.ok(result.workflow.nodes.some(node => node.id === 'gate_verify'));
+  assert.equal(result.architecture.nodes[0].title, 'Own feature behavior');
+  assert.deepEqual(result.evidence, [{ id: 'unit', status: 'fresh', executedRevision: 2, code: 0, filename: 'unit.log' }]);
+  assert.equal(JSON.stringify(result).includes('must not leave the report DTO'), false);
+  assert.equal(JSON.stringify(result).includes(root), false, 'only a log filename, never the report’s absolute path, is exposed');
+  const deliverySchema = workspaceContract.methods.delivery.output;
+  assert.equal(deliverySchema.oneOf.length, 2);
+  assert.deepEqual(deliverySchema.oneOf.map(branch => branch.properties.status.enum), [['active', 'implementing', 'verifying', 'verified', 'blocked', 'stale'], ['unavailable', 'invalid']]);
+  assert.equal(deliverySchema.oneOf[0].additionalProperties, false);
+  assert.deepEqual(Object.keys(deliverySchema.oneOf[0].properties).sort(), ['architecture', 'completion', 'evidence', 'fingerprint', 'freshness', 'gate', 'plan', 'revision', 'runId', 'status', 'truncation', 'workflow']);
+  assert.deepEqual(deliverySchema.oneOf[0].required, Object.keys(deliverySchema.oneOf[0].properties));
+  assert.equal(deliverySchema.oneOf[1].additionalProperties, false);
+  assert.deepEqual(deliverySchema.oneOf[1].required, ['status']);
+  assert.deepEqual(Object.keys(deliverySchema.oneOf[1].properties), ['status']);
+  assert.equal(deliverySchema.oneOf[0].properties.plan.additionalProperties, false);
+
+  writeFileSync(join(root, 'source.txt'), 'edited');
+  const stale = await registered.delivery({ sessionID }, { signal });
+  assert.equal(stale.freshness, 'stale');
+  assert.equal(stale.evidence[0].status, 'stale');
+
+  const changedFingerprint = fingerprint(root, ['.']);
+  const completeState = {
+    runId: 'complete-run', revision: 1, status: 'verified', workflowMode: 'standard', plan: {
+      ...plan, steps: [{ ...plan.steps[0], checks: ['unit'] }],
+    }, stepStatus: { step0: 'done' },
+  };
+  const freshReceipt = { runId: 'complete-run', revision: 1, checkDigest: checkDigest(check), passed: true, fingerprint: changedFingerprint, executedRevision: 1, durationMs: 5, code: 0 };
+  for (const [name, receipt] of [['missing', undefined], ['failed', { ...freshReceipt, passed: false }]]) {
+    const state = { ...completeState, runId: `${name}-run`, evidence: receipt ? { unit: { ...receipt, runId: `${name}-run` } } : {}, reviewEvidence: { runId: `${name}-run`, revision: 1, fingerprint: changedFingerprint } };
+    const report = createReport(root, state, sessionID);
+    selectReport(root, report.path);
+    const projected = await registered.delivery({ sessionID }, { signal });
+    assert.notEqual(projected.status, 'verified', `a forged verified state with ${name} evidence cannot be projected as verified`);
+    assert.equal(projected.completion, 'incomplete');
+  }
+
+  const staleReviewState = { ...completeState, evidence: { unit: freshReceipt }, reviewEvidence: { runId: 'complete-run', revision: 1, fingerprint: '0'.repeat(64) } };
+  const staleReviewReport = createReport(root, staleReviewState, sessionID);
+  selectReport(root, staleReviewReport.path);
+  const staleReview = await registered.delivery({ sessionID }, { signal });
+  assert.equal(staleReview.status, 'stale', 'stale required final-review receipt blocks verified status');
+  assert.equal(staleReview.completion, 'incomplete');
+
+  const lockedState = { ...completeState, runId: 'locked-run', workflowMode: 'strict', evidence: { unit: { ...freshReceipt, runId: 'locked-run' } }, reviewEvidence: { runId: 'locked-run', revision: 1, fingerprint: changedFingerprint } };
+  const lockedReport = createReport(root, lockedState, sessionID);
+  selectReport(root, lockedReport.path);
+  const locked = await registered.delivery({ sessionID }, { signal });
+  assert.notEqual(locked.status, 'verified', 'a locked planning gate blocks a forged verified status');
+  assert.equal(locked.gate, 'locked');
+  assert.equal(locked.completion, 'incomplete');
+
+  const informationalState = { ...completeState, runId: 'informational-run', plan: { ...plan, verification: 'none', steps: [{ ...plan.steps[0], checks: [] }], checks: [], acceptance: [] }, evidence: {}, reviewEvidence: undefined };
+  const informationalReport = createReport(root, informationalState, sessionID);
+  selectReport(root, informationalReport.path);
+  const informational = await registered.delivery({ sessionID }, { signal });
+  assert.notEqual(informational.status, 'verified', 'informational plans cannot claim verified completion');
+  assert.equal(informational.completion, 'incomplete');
+
+  const manyChecks = Array.from({ length: 101 }, (_, index) => ({ id: `check_${String(index).padStart(3, '0')}`, kind: 'test', argv: ['node', '--test'], timeoutSeconds: 20 }));
+  const manyPlan = { ...plan, steps: [{ ...plan.steps[0], checks: manyChecks.map(item => item.id) }], checks: manyChecks, acceptance: [{ requirement: 'Feature is visible', checks: manyChecks.map(item => item.id) }] };
+  const manyEvidence = Object.fromEntries(manyChecks.map((item, index) => [item.id, {
+    runId: 'many-run', revision: 1, checkDigest: checkDigest(item), passed: true,
+    fingerprint: index === 100 ? '0'.repeat(64) : changedFingerprint, executedRevision: 1, durationMs: 2, code: 0,
+  }]));
+  const manyReport = createReport(root, { runId: 'many-run', revision: 1, status: 'implementing', workflowMode: 'standard', plan: manyPlan, stepStatus: { step0: 'done' }, evidence: manyEvidence, reviewEvidence: { runId: 'many-run', revision: 1, fingerprint: changedFingerprint } }, sessionID);
+  selectReport(root, manyReport.path);
+  const manyResult = await registered.delivery({ sessionID }, { signal });
+  assert.equal(manyResult.status, 'stale', 'staleness in a receipt beyond the DTO cap still affects overall status');
+  assert.deepEqual(manyResult.truncation.checks, { returned: 100, total: 101 });
+  assert.equal(manyResult.completion, 'incomplete');
+
+  const foreign = createReport(root, { runId: 'foreign-run', revision: 1, status: 'verified', plan, evidence: {} }, 'foreign-session');
+  selectReport(root, foreign.path);
+  assert.deepEqual(await registered.delivery({ sessionID }, { signal }), { status: 'unavailable' });
+
+  selectReport(root, report.path);
+  writeFileSync(report.path, '{corrupt');
+  assert.deepEqual(await registered.delivery({ sessionID }, { signal }), { status: 'invalid' });
+
+  writeFileSync(join(root, '.harness', 'active.json'), '{corrupt');
+  assert.deepEqual(await registered.delivery({ sessionID }, { signal }), { status: 'invalid' });
+});