create-walle 0.10.2 → 0.10.3

package/template/coding-task-manager/scripts/opencode-v2-contract-probe.js

@@ -0,0 +1,673 @@
+#!/usr/bin/env node
+'use strict';
+
+// WP-0 contract probe for OpenCode 2.x
+// (coding-task-manager/docs/opencode-v2-model-switch-standalone-plugin-2026-10-30.html §3.2, §6.3, §8 WP-0).
+//
+// Proves, on a real 2.x binary, the five vendor facts the 2.x model-carrier design depends on:
+//   P-S1   a CTM-chosen session id is honoured and the inline config model drives the first turn
+//   P-S3a  a resumed session keeps its own model: the inline config does NOT switch it
+//   P-S3b  a `plugins` entry whose setup calls ctx.session.switchModel() DOES switch it
+//   P-S4   the shared `service` ignores the tab's inline config (0 requests reach the tab listener)
+//   P-S6   a fresh ses_<32 hex> id is accepted and persisted in session_v2
+//
+// WP-4 adds three more (docs/opencode-followups-agent-word-v2-waiting-dev-route-2026-10-31.html §6.4):
+//   P-S9   a tool whose permission is "ask" emits permission.asked then permission.replied (OQ-2)
+//   P-S10  the planted 1.x ~/.config/opencode/plugins/ctm-status.js: load error logged, turn done (OQ-3)
+//   P-S11  a subagent child's permission ask: child id or parent id? (OQ-5; never fails the run)
+//
+// Isolation: every child runs with XDG_{CONFIG,DATA,STATE,CACHE}_HOME under a fresh mkdtemp root and
+// HOME pointing there too, so the user's ~/.config/opencode, ~/.local/share/opencode and
+// ~/.local/state/opencode are never read or written; credential/endpoint env vars are stripped, so
+// the probe cannot authenticate anywhere; the temp root is removed at the end unless --keep.
+// Process hygiene: the TUI runs under a pty via `script -q /dev/null <bin> ...`; only pids this
+// script started (the `script` pid and its `pgrep -P` descendants) are ever killed -- never pkill by
+// pattern. Each probe has a 90 s deadline.
+//
+//   node scripts/opencode-v2-contract-probe.js --opencode <2.x bin> [--json] [--keep] [--verbose]
+//   -> one JSON line per probe: {"id","expected","observed","pass"}; exit 0 iff every probe passed,
+//      1 when a probe failed, 2 when --opencode is missing or its version line is not v2.x.
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const net = require('node:net');
+const crypto = require('node:crypto');
+const { spawn, execFileSync } = require('node:child_process');
+
+const { startFakeAnthropic, requestsForPrompt, lastModelForPrompt } = require('./opencode-v2-contract-probe/fake-anthropic');
+
+const PROBE_PLUGIN_DIR = path.join(__dirname, 'opencode-v2-contract-probe', 'probe-plugin');
+const SCRIPT_BIN = fs.existsSync('/usr/bin/script') ? '/usr/bin/script' : 'script';
+const PGREP_BIN = fs.existsSync('/usr/bin/pgrep') ? '/usr/bin/pgrep' : 'pgrep';
+const LSOF_BIN = fs.existsSync('/usr/sbin/lsof') ? '/usr/sbin/lsof' : 'lsof';
+const PROBE_TIMEOUT_MS = 90000;      // per probe, per the design (§8 WP-0)
+const NEGATIVE_WAIT_MS = 20000;      // how long a probe that expects ZERO requests observes
+const EXPECTED_PROBES = 8;           // P-S1, P-S3a, P-S3b, P-S4, P-S6, P-S9, P-S10, P-S11
+
+// Never let the probe reach anything authenticated: the scratch runs inherited whatever the shell
+// had, but a probe must not be able to spend the user's credentials or read their real config.
+const STRIPPED_ENV = [
+  /^ANTHROPIC_/, /^OPENAI_/, /^GEMINI_/, /^GOOGLE_/, /^MOONSHOT/, /^ZAI_/, /^Z_AI/, /^OPENROUTER_/,
+  /^DEEPSEEK_/, /^FIREWORKS_/, /^PORTKEY_/, /^AWS_/, /^AZURE_/, /^COPILOT_/, /^CTM_LEAD_TOKEN$/,
+  /^OPENCODE_CONFIG$/, /^OPENCODE_CONFIG_CONTENT$/, /^OPENCODE_CONFIG_DIR$/,
+];
+
+const state = { verbose: false, tempRoot: null, entries: null, listener: null, results: [], startedPids: new Set(), opencodeBin: null, only: null };
+
+// ---- process tree -------------------------------------------------------------------------------
+
+function sleep(ms) {
+  return new Promise((resolve) => { setTimeout(resolve, ms); });
+}
+
+function sleepSync(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+function childPidsOf(pid) {
+  try {
+    return execFileSync(PGREP_BIN, ['-P', String(pid)], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] })
+      .split('\n')
+      .map((line) => parseInt(line.trim(), 10))
+      .filter((value) => Number.isInteger(value) && value > 0);
+  } catch { return []; /* expected: pgrep exits 1 when the pid has no children */ }
+}
+
+// Deepest descendants first, the root last: a child is signalled before its parent can re-parent it.
+function treePostOrder(rootPid) {
+  const order = [];
+  const walk = (pid) => {
+    for (const child of childPidsOf(pid)) walk(child);
+    order.push(pid);
+  };
+  walk(rootPid);
+  return order;
+}
+
+function killTree(rootPid) {
+  const pids = treePostOrder(rootPid);
+  for (const pid of pids) { try { process.kill(pid, 'SIGTERM'); } catch { /* expected: pid already exited */ } }
+  if (pids.length > 1) sleepSync(500);
+  for (const pid of pids) { try { process.kill(pid, 'SIGKILL'); } catch { /* expected: pid already exited */ } }
+  return pids;
+}
+
+function waitExit(child, ms) {
+  if (child.exitCode !== null || child.signalCode !== null) return Promise.resolve();
+  return new Promise((resolve) => {
+    const timer = setTimeout(resolve, ms);
+    child.once('exit', () => { clearTimeout(timer); resolve(); });
+  });
+}
+
+function portIsListening(port) {
+  return new Promise((resolve) => {
+    const socket = net.connect({ host: '127.0.0.1', port });
+    const done = (listening) => { socket.destroy(); resolve(listening); };
+    socket.once('connect', () => done(true));
+    socket.once('error', () => done(false));
+    socket.setTimeout(1000, () => done(false));
+  });
+}
+
+function listenerPidsOnPort(port) {
+  try {
+    return execFileSync(LSOF_BIN, ['-nP', '-iTCP:' + port, '-sTCP:LISTEN', '-t'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] })
+      .split('\n')
+      .map((line) => parseInt(line.trim(), 10))
+      .filter((value) => Number.isInteger(value) && value > 0);
+  } catch { return []; /* expected: lsof exits 1 when nothing listens on the port */ }
+}
+
+// ---- probe scaffolding --------------------------------------------------------------------------
+
+function parseArgs(argv) {
+  const args = { opencode: null, json: false, keep: false, verbose: false, only: null, help: false };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--opencode') { args.opencode = argv[i + 1] || null; i += 1; } else if (arg === '--json') { args.json = true; } else if (arg === '--keep') { args.keep = true; } else if (arg === '--verbose') { args.verbose = true; } else if (arg === '--only') { args.only = (argv[i + 1] || '').split(',').map((id) => id.trim()).filter(Boolean); i += 1; } else if (arg === '--help' || arg === '-h') { args.help = true; }
+  }
+  return args;
+}
+
+// `--only P-S9,P-S11` runs a subset while iterating on a probe; unset means the whole suite.
+function wanted(id) {
+  return !state.only || state.only.includes(id);
+}
+
+function note(message, verboseOnly = false) {
+  if (verboseOnly && !state.verbose) return;
+  process.stderr.write('[probe] ' + message + '\n');
+}
+
+function record(id, expected, observed, pass) {
+  const row = { id, expected, observed, pass: !!pass };
+  state.results.push(row);
+  process.stdout.write(JSON.stringify(row) + '\n');
+  return row;
+}
+
+function filteredEnv() {
+  const env = {};
+  for (const [key, value] of Object.entries(process.env)) {
+    if (value === undefined) continue;
+    if (STRIPPED_ENV.some((pattern) => pattern.test(key))) continue;
+    env[key] = value;
+  }
+  return env;
+}
+
+function xdgEnv(extra, root = state.tempRoot) {
+  const env = filteredEnv();
+  Object.assign(env, {
+    HOME: root,
+    XDG_CONFIG_HOME: path.join(root, 'config'),
+    XDG_DATA_HOME: path.join(root, 'data'),
+    XDG_STATE_HOME: path.join(root, 'state'),
+    XDG_CACHE_HOME: path.join(root, 'cache'),
+    OPENCODE_DISABLE_AUTOUPDATE: '1',
+    OPENCODE_DISABLE_TELEMETRY: '1',
+    OQ2_LOG: path.join(root, 'probe-plugin.log'),
+  });
+  return Object.assign(env, extra || {});
+}
+
+function inlineConfig({ model, port, plugins, permissions }) {
+  const config = {
+    model: 'probe/' + model,
+    provider: {
+      probe: {
+        npm: '@ai-sdk/anthropic',
+        options: { baseURL: 'http://127.0.0.1:' + port + '/v1', apiKey: 'x' },
+        models: { m1: { name: 'm1' }, m2: { name: 'm2' }, m3: { name: 'm3' } },
+      },
+    },
+  };
+  if (plugins) config.plugins = plugins;
+  // 2.2.4 config key (verified in the binary's Config.Info schema, not assumed): top-level
+  // `permissions` is an ordered ruleset of { action, resource, effect } appended to every agent's
+  // own rules; evaluation takes the LAST matching rule. The shell tool's permission action is
+  // `shell` (Agent.Info defaults use `read`/`shell`/`edit`/`webfetch`/...), so an `ask` rule for
+  // `shell`/`*` outranks the default `{ action: '*', resource: '*', effect: 'allow' }`.
+  if (permissions) config.permissions = permissions;
+  return JSON.stringify(config);
+}
+
+// The one permission rule P-S9/P-S11 need: the shell tool asks before it runs.
+const ASK_SHELL_PERMISSIONS = [{ action: 'shell', resource: '*', effect: 'ask' }];
+
+function pluginLog() {
+  const file = path.join(state.tempRoot, 'probe-plugin.log');
+  try {
+    return fs.readFileSync(file, 'utf8').split('\n').filter(Boolean).map((line) => {
+      try { return JSON.parse(line); } catch { return { ev: 'unparsed', raw: line.slice(0, 200) }; }
+    });
+  } catch { return []; /* expected: no plugin log when no plugin entry ran */ }
+}
+
+// ---- opencode invocations -----------------------------------------------------------------------
+
+// The version preflight runs under its own throwaway XDG/HOME root too: opencode's logger appends
+// <XDG_DATA_HOME>/opencode/log/opencode.log on EVERY invocation, `--version` included, so a bare run
+// would write into the user's ~/.local/share/opencode (AC-4d: nothing outside the OS temp dir).
+function opencodeVersionLine(bin) {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'oc2-probe-version-'));
+  try {
+    for (const dir of ['config', 'data', 'state', 'cache']) fs.mkdirSync(path.join(root, dir), { recursive: true });
+    return { text: execFileSync(bin, ['--version'], { encoding: 'utf8', timeout: 30000, env: xdgEnv({}, root) }).trim(), error: null };
+  } catch (err) {
+    const stdout = err && err.stdout ? String(err.stdout).trim() : '';
+    return { text: stdout, error: String((err && (err.message || err)) || err) };
+  } finally {
+    try { fs.rmSync(root, { recursive: true, force: true }); } catch { /* expected: best-effort temp cleanup */ }
+  }
+}
+
+// The TUI needs a pty, so it runs under `script -q /dev/null <bin> ...`. `--prompt <text>` submits
+// one turn, but the TUI itself stays up: the probe waits for the listener, then kills its own tree.
+// `prompt: null` means "expect no request at all" and observes for NEGATIVE_WAIT_MS instead.
+// `until` (P-S9/P-S11) replaces the request-count stop with a predicate over probe-owned state
+// (the plugin log), bounded by `deadlineMs` so a never-answered ask still ends the probe.
+async function runTui({ env, args, prompt, until, deadlineMs }) {
+  const child = spawn(SCRIPT_BIN, ['-q', '/dev/null', state.opencodeBin, ...args], {
+    cwd: state.tempRoot,
+    env,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  state.startedPids.add(child.pid);
+  const out = { stdout: '', stderr: '' };
+  child.stdout.on('data', (chunk) => { out.stdout += chunk; });
+  child.stderr.on('data', (chunk) => { out.stderr += chunk; });
+
+  let exited = false;
+  child.once('exit', () => { exited = true; });
+
+  const started = Date.now();
+  const deadline = started + (deadlineMs || PROBE_TIMEOUT_MS);
+  while (Date.now() < deadline) {
+    if (until) {
+      if (until()) { await sleep(1000); break; }
+      if (exited) { await sleep(500); break; }
+    } else if (prompt) {
+      if (requestsForPrompt(state.entries, prompt).length > 0) { await sleep(1500); break; }
+      if (exited) { await sleep(500); break; }
+    } else if (Date.now() - started >= NEGATIVE_WAIT_MS) {
+      break;
+    }
+    await sleep(250);
+  }
+
+  killTree(child.pid);
+  await waitExit(child, 5000);
+  return { exitCode: child.exitCode, elapsedMs: Date.now() - started, stdout: out.stdout, stderr: out.stderr };
+}
+
+function serviceRun(sub) {
+  try {
+    const stdout = execFileSync(state.opencodeBin, ['service', sub], {
+      cwd: state.tempRoot,
+      env: xdgEnv(),
+      encoding: 'utf8',
+      timeout: 60000,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    return { ok: true, stdout: String(stdout) };
+  } catch (err) {
+    return { ok: false, stdout: String((err && err.stdout) || ''), error: String((err && (err.message || err)) || err) };
+  }
+}
+
+function servicePortOf(stdout) {
+  const match = /(?:127\.0\.0\.1|localhost):(\d+)/.exec(stdout || '');
+  return match ? parseInt(match[1], 10) : null;
+}
+
+// `service start` double-forks, so the daemon is NOT a descendant of ours: `service stop` is the
+// only honest way to end it. If the port is still bound afterwards, the listening pid is resolved
+// BY PORT -- a pid that can only be the service our own `service start` just created.
+async function stopService(port) {
+  const stopped = serviceRun('stop');
+  if (!stopped.ok) note(`service stop reported: ${stopped.error}`, true);
+  if (!port) return stopped;
+  for (let i = 0; i < 10 && (await portIsListening(port)); i += 1) await sleep(500);
+  if (await portIsListening(port)) {
+    // Only OUR service is killed: OpenCode's service chdirs to HOME, which the probe set to its temp
+    // root, so a listener whose cwd is anything else (e.g. the user's own service) is left alone.
+    const root = fs.realpathSync(state.tempRoot);
+    const pids = listenerPidsOnPort(port).filter((pid) => {
+      try {
+        const out = execFileSync(LSOF_BIN, ['-a', '-p', String(pid), '-d', 'cwd', '-Fn'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+        return out.split('\n').some((line) => line === 'n' + root);
+      } catch { return false; /* expected: the pid exited between the two lsof calls */ }
+    });
+    note(`service port ${port} still bound after stop; killing ${pids.join(', ') || '(no probe-owned pid)'}`);
+    for (const pid of pids) killTree(pid);
+    await sleep(500);
+  }
+  note(`P-S4 service port ${port}: listening after stop = ${await portIsListening(port)}`, true);
+  return stopped;
+}
+
+// ---- probes -------------------------------------------------------------------------------------
+
+async function probeSessionSwitch(port, firstSid) {
+  if (!wanted('P-S1') && !wanted('P-S3a') && !wanted('P-S3b')) return;
+  // P-S1 -- the inline config model drives the first turn of a CTM-chosen session id.
+  const run1 = await runTui({
+    env: xdgEnv({ OPENCODE_CONFIG_CONTENT: inlineConfig({ model: 'm1', port }) }),
+    args: ['--standalone', '-s', firstSid, '--prompt', 'p1'],
+    prompt: 'p1',
+  });
+  const requests1 = requestsForPrompt(state.entries, 'p1');
+  const model1 = lastModelForPrompt(state.entries, 'p1');
+  const firstToolRequest = state.entries.find((entry) => Array.isArray(entry.tools) && entry.tools.length);
+  note('tools offered by the 2.x agent: ' + JSON.stringify(firstToolRequest ? firstToolRequest.tools : []), true);
+  record('P-S1',
+    'inline config probe/m1 drives the first turn of -s ' + firstSid,
+    'model=' + (model1 || 'none') + ' (requests for p1=' + requests1.length + ', tui exit=' + run1.exitCode + ', ' + Math.round(run1.elapsedMs / 1000) + 's)',
+    model1 === 'm1');
+
+  // P-S3a -- resume keeps the session's own model: the inline config does NOT switch it.
+  const run2 = await runTui({
+    env: xdgEnv({ OPENCODE_CONFIG_CONTENT: inlineConfig({ model: 'm2', port }) }),
+    args: ['--standalone', '-s', firstSid, '--prompt', 'p2'],
+    prompt: 'p2',
+  });
+  const requests2 = requestsForPrompt(state.entries, 'p2');
+  const model2 = lastModelForPrompt(state.entries, 'p2');
+  record('P-S3a',
+    'a resumed session keeps its own model (m1); inline config probe/m2 does not switch it',
+    'model=' + (model2 || 'none') + ' (requests for p2=' + requests2.length + ', tui exit=' + run2.exitCode + ', ' + Math.round(run2.elapsedMs / 1000) + 's)',
+    model2 === 'm1');
+
+  // P-S3b -- a `plugins` entry whose setup calls ctx.session.switchModel() DOES switch it.
+  const plugins = [{
+    package: PROBE_PLUGIN_DIR,
+    options: { sessionID: firstSid, model: { providerID: 'probe', id: 'm3' } },
+  }];
+  const run3 = await runTui({
+    env: xdgEnv({ OPENCODE_CONFIG_CONTENT: inlineConfig({ model: 'm1', port, plugins }), CTM_SESSION_ID: 'tab-E' }),
+    args: ['--standalone', '-s', firstSid, '--prompt', 'p3'],
+    prompt: 'p3',
+  });
+  const requests3 = requestsForPrompt(state.entries, 'p3');
+  const model3 = lastModelForPrompt(state.entries, 'p3');
+  const switchRows = pluginLog().filter((row) => row.ev === 'switch.ok' || row.ev === 'switch.err');
+  const switchNote = switchRows.length
+    ? switchRows.map((row) => row.ev + (row.err ? ':' + row.err : '')).join(',')
+    : 'plugin did not run (no log rows)';
+  record('P-S3b',
+    'a `plugins` entry calling ctx.session.switchModel() moves the resumed session to probe/m3',
+    'model=' + (model3 || 'none') + ' (plugin=' + switchNote + ', requests for p3=' + requests3.length + ', tui exit=' + run3.exitCode + ', ' + Math.round(run3.elapsedMs / 1000) + 's)',
+    model3 === 'm3' && switchRows.some((row) => row.ev === 'switch.ok'));
+}
+
+async function probeSharedService(port, sid) {
+  if (!wanted('P-S4')) return;
+  const started = serviceRun('start');
+  const servicePort = servicePortOf(started.stdout);
+  note(`P-S4 shared service start: ${started.ok ? 'ok' : 'FAILED ' + started.error}${servicePort ? ' port=' + servicePort : ''}`, true);
+
+  let observed;
+  let pass = false;
+  try {
+    if (!started.ok) {
+      observed = 'service start failed: ' + started.error;
+    } else {
+      const run = await runTui({
+        env: xdgEnv({ OPENCODE_CONFIG_CONTENT: inlineConfig({ model: 'm1', port }) }),
+        args: ['-s', sid, '--prompt', 'p4'],
+        prompt: null,
+      });
+      const hits = requestsForPrompt(state.entries, 'p4').length;
+      observed = 'listener requests for p4=' + hits + ' (observed ' + Math.round(NEGATIVE_WAIT_MS / 1000) + 's, tui exit=' + run.exitCode + ')';
+      pass = hits === 0;
+    }
+  } finally {
+    await stopService(servicePort);
+  }
+  record('P-S4',
+    'the shared service ignores the tab inline config: no request reaches the tab listener for p4',
+    observed,
+    pass);
+}
+
+async function probeFreshSession(port) {
+  if (!wanted('P-S6')) return;
+  const sid = 'ses_' + crypto.randomBytes(16).toString('hex');
+  const run = await runTui({
+    env: xdgEnv({ OPENCODE_CONFIG_CONTENT: inlineConfig({ model: 'm2', port }) }),
+    args: ['--standalone', '--session', sid, '--prompt', 'p6'],
+    prompt: 'p6',
+  });
+  const model = lastModelForPrompt(state.entries, 'p6');
+
+  let row = { exists: false, dbError: null };
+  const deadline = Date.now() + 5000;
+  do {
+    row = sessionRowExists(sid);
+    if (row.exists || row.dbError) break;
+    await sleep(500);
+  } while (Date.now() < deadline);
+
+  record('P-S6',
+    'a fresh --session ses_<32 hex> id is accepted, runs on config probe/m2 and is persisted in session_v2',
+    'model=' + (model || 'none') + '; session_v2 has ' + sid + '=' + row.exists + (row.dbError ? ' (db error: ' + row.dbError + ')' : '') + ' (tui exit=' + run.exitCode + ', ' + Math.round(run.elapsedMs / 1000) + 's)',
+    model === 'm2' && row.exists);
+}
+
+// ---- WP-4 probes: permission events (OQ-2), the 1.x plugin file (OQ-3), subagent asks (OQ-5) ----
+
+// The plugin log is append-only across probes: truncate it so a probe never reads an earlier
+// probe's events (P-S9's ask must not be mistaken for P-S11's child ask).
+function resetPluginLog() {
+  try { fs.writeFileSync(path.join(state.tempRoot, 'probe-plugin.log'), ''); } catch { /* expected: no log yet */ }
+}
+
+function probeEvents(sid) {
+  return pluginLog().filter((row) => row.ev === 'event' && (sid === undefined || row.sessionID === sid));
+}
+
+// A compact, order-preserving summary of the event types a run produced.
+function eventTypeSummary(rows) {
+  const seen = [];
+  for (const row of rows) if (!seen.includes(row.type)) seen.push(row.type);
+  return seen;
+}
+
+async function probePermissionEvents(port, sid) {
+  if (!wanted('P-S9')) return;
+  resetPluginLog();
+  // P-S9 (OQ-2) -- a turn calls the `shell` tool while its config permission is "ask". The probe
+  // plugin logs every subscribed event and answers the ask through the 2.x plugin-visible
+  // ctx.permission.reply({ sessionID, requestID, decision: 'once' }).
+  state.entries.length = 0;
+  state.listener.setScript([
+    { when: 'p9', toolUse: { name: 'shell', input: { command: 'true' } } },
+    { text: 'probe-ok' },
+  ]);
+  const plugins = [{
+    package: PROBE_PLUGIN_DIR,
+    options: { log_events: true, reply_permission: true, probe_session: sid },
+  }];
+  const run = await runTui({
+    env: xdgEnv({ OPENCODE_CONFIG_CONTENT: inlineConfig({ model: 'm1', port, plugins, permissions: ASK_SHELL_PERMISSIONS }) }),
+    args: ['--standalone', '-s', sid, '--prompt', 'p9'],
+    until: () => probeEvents(sid).some((row) => row.type === 'permission.replied'),
+    deadlineMs: 60000,
+  });
+  const rows = probeEvents(sid);
+  const types = eventTypeSummary(rows);
+  const asked = rows.find((row) => row.type === 'permission.asked');
+  const replied = rows.find((row) => row.type === 'permission.replied');
+  const askRows = pluginLog().filter((row) => row.ev === 'ask');
+  const replyRows = pluginLog().filter((row) => row.ev === 'reply.ok' || row.ev === 'reply.err');
+  const replyNote = askRows.concat(replyRows).map((row) => row.ev + (row.err ? ':' + row.err : '')).join(',') || 'none';
+  const ask = askRows[0] || {};
+  record('P-S9',
+    'a "shell" permission ask emits permission.asked for the probe session, then permission.replied after ctx.permission.reply',
+    'session=' + sid + ' events=' + JSON.stringify(types)
+      + ' asked.sessionID=' + (asked ? JSON.stringify(asked.sessionID) : 'none')
+      + ' asked.action=' + JSON.stringify(ask.action === undefined ? null : ask.action)
+      + ' asked.resources=' + JSON.stringify(ask.resources === undefined ? null : ask.resources)
+      + ' requestID=' + JSON.stringify(ask.requestID === undefined ? null : ask.requestID)
+      + ' replied=' + (replied ? 'seen' : 'not-seen')
+      + ' pluginReply=' + replyNote
+      + ' tui exit=' + run.exitCode + ', ' + Math.round(run.elapsedMs / 1000) + 's',
+    !!asked && asked.sessionID === sid);
+}
+
+// Load-error lines the 2.x private server printed while loading the planted 1.x plugin file.
+// 2.2.4 writes: level=WARN message="failed to load plugin" target=<path> cause="… PluginModule.LoadError: …"
+function loadErrorLines(text) {
+  return String(text || '').split('\n')
+    .map((line) => line.trim())
+    .filter((line) => /failed to load plugin|PluginModule\.LoadError|LoadError/i.test(line));
+}
+
+async function probeLegacyPluginFile(port, sid) {
+  if (!wanted('P-S10')) return;
+  resetPluginLog();
+  // P-S10 (OQ-3) -- plant the CTM-owned 1.x plugin EXACTLY as the installer writes it
+  // (lib/agent-hooks-opencode-plugin.js PLUGIN_SOURCE, never a hand copy) into this run's
+  // isolated config dir and check whether 2.x logs a load error and whether a turn still completes.
+  const { PLUGIN_SOURCE } = require('../lib/agent-hooks-opencode-plugin');
+  const pluginDir = path.join(state.tempRoot, 'config', 'opencode', 'plugins');
+  fs.mkdirSync(pluginDir, { recursive: true });
+  const planted = path.join(pluginDir, 'ctm-status.js');
+  fs.writeFileSync(planted, PLUGIN_SOURCE);
+
+  state.entries.length = 0;
+  state.listener.setScript(null);
+  const run = await runTui({
+    env: xdgEnv({ OPENCODE_CONFIG_CONTENT: inlineConfig({ model: 'm1', port }) }),
+    args: ['--standalone', '-s', sid, '--prompt', 'p10'],
+    prompt: 'p10',
+    deadlineMs: 60000,
+  });
+  const turnCompleted = requestsForPrompt(state.entries, 'p10').length > 0;
+
+  // The load error may land on stderr or in the isolated log dirs; count both.
+  const logs = [];
+  for (const dir of ['state', 'data', 'cache']) {
+    const root = path.join(state.tempRoot, dir);
+    const walk = (at) => {
+      let items = [];
+      try { items = fs.readdirSync(at, { withFileTypes: true }); } catch { return; /* expected: dir absent */ }
+      for (const item of items) {
+        const full = path.join(at, item.name);
+        if (item.isDirectory()) walk(full);
+        else if (/\.log$|log$/i.test(item.name)) {
+          try { logs.push({ file: full, text: fs.readFileSync(full, 'utf8') }); } catch { /* expected: log rotated away */ }
+        }
+      }
+    };
+    walk(root);
+  }
+  const sources = [{ file: '(stderr)', text: run.stderr }].concat(logs);
+  const lines = sources.flatMap((source) => loadErrorLines(source.text));
+  // The interesting part of the log line: the loader's own reason, without the log envelope.
+  const firstCause = lines.length
+    ? ((/PluginModule\.LoadError: ([^)\\]{0,200})/.exec(lines[0]) || /"cause":"?([^"]{0,200})/.exec(lines[0]) || [null, lines[0]])[1] || '').trim()
+    : null;
+  note('P-S10 log files: ' + sources.map((source) => source.file).join(', '), true);
+  record('P-S10',
+    'the planted 1.x ~/.config/opencode/plugins/ctm-status.js makes 2.x log a load error but a turn still completes',
+    'planted=' + planted + ' loadErrorLines=' + lines.length
+      + (firstCause ? ' cause=' + JSON.stringify(String(firstCause).slice(0, 220)) : '')
+      + ' turnCompleted=' + turnCompleted + ' requests=' + requestsForPrompt(state.entries, 'p10').length
+      + ' logFiles=' + logs.map((log) => path.basename(log.file)).join('|')
+      + ' tui exit=' + run.exitCode + ', ' + Math.round(run.elapsedMs / 1000) + 's',
+    turnCompleted);
+}
+
+async function probeSubagentPermission(port, sid) {
+  if (!wanted('P-S11')) return;
+  resetPluginLog();
+  // P-S11 (OQ-5) -- turn 1 calls `subagent`; the child's first turn calls `shell` under "ask".
+  // Record session.created (with parentID) and permission.asked ids: is the ask's sessionID the
+  // child's or the parent's? No expected value; this probe never fails the run.
+  state.entries.length = 0;
+  state.listener.setScript([
+    { when: 'p11', toolUse: { name: 'subagent', input: { agent: 'general', description: 'probe child', prompt: 'p11child run the true command' } } },
+    { when: 'p11child', toolUse: { name: 'shell', input: { command: 'true' } } },
+    { text: 'probe-ok' },
+  ]);
+  const plugins = [{
+    package: PROBE_PLUGIN_DIR,
+    options: { log_events: true, reply_permission: true, probe_session: sid },
+  }];
+  const run = await runTui({
+    env: xdgEnv({ OPENCODE_CONFIG_CONTENT: inlineConfig({ model: 'm1', port, plugins, permissions: ASK_SHELL_PERMISSIONS }) }),
+    args: ['--standalone', '-s', sid, '--prompt', 'p11'],
+    until: () => pluginLog().some((row) => row.ev === 'ask' && row.sessionID !== sid),
+    deadlineMs: 60000,
+  });
+  const rows = pluginLog().filter((row) => row.ev === 'event');
+  const created = rows.filter((row) => row.type === 'session.created')
+    .map((row) => ({ sessionID: row.sessionID, parentID: row.parentID }));
+  const asks = pluginLog().filter((row) => row.ev === 'ask')
+    .map((row) => ({ sessionID: row.sessionID, action: row.action, resources: row.resources }));
+  const childIds = created.filter((row) => row.parentID).map((row) => row.sessionID);
+
+  // The answer OQ-5 asks for: is the ask's sessionID the child's or the parent's?
+  let verdict = 'unmeasured: no permission.asked reached the plugin in ' + Math.round(run.elapsedMs / 1000) + 's';
+  if (asks.length) {
+    const ids = asks.map((ask) => ask.sessionID);
+    if (ids.every((id) => id === sid)) verdict = 'parent-id (the ask carries the ROOT session id ' + sid + ')';
+    else if (ids.every((id) => childIds.includes(id))) verdict = 'child-id (the ask carries the CHILD session id ' + JSON.stringify(ids) + ')';
+    else verdict = 'mixed/other: asked=' + JSON.stringify(ids);
+  }
+  record('P-S11',
+    'record which sessionID a subagent child permission.asked carries (child id vs parent), plus session.created parentID — no expected value',
+    'answer=' + verdict
+      + ' parent=' + sid
+      + ' session.created=' + JSON.stringify(created)
+      + ' permission.asked=' + JSON.stringify(asks)
+      + ' childIds=' + JSON.stringify(childIds)
+      + ' tui exit=' + run.exitCode + ', ' + Math.round(run.elapsedMs / 1000) + 's',
+    true);
+}
+
+// sqlite3-free read of the isolated DB, through the repo's own better-sqlite3 (readonly).
+function sessionRowExists(sid) {
+  const dbFile = path.join(state.tempRoot, 'data', 'opencode', 'opencode.db');
+  try {
+    const Database = require('better-sqlite3'); // resolves coding-task-manager/node_modules from scripts/
+    const db = new Database(dbFile, { readonly: true, fileMustExist: true });
+    try {
+      const row = db.prepare('SELECT id FROM session_v2 WHERE id = ?').get(sid);
+      return { exists: !!(row && row.id === sid), dbError: null };
+    } finally { db.close(); }
+  } catch (err) {
+    return { exists: false, dbError: String((err && (err.message || err)) || err) };
+  }
+}
+
+// ---- main ---------------------------------------------------------------------------------------
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  state.verbose = args.verbose;
+  state.only = args.only;
+
+  if (args.help || !args.opencode) {
+    process.stderr.write('usage: node scripts/opencode-v2-contract-probe.js --opencode <2.x bin> [--json] [--keep] [--verbose]\n');
+    return 2;
+  }
+  state.opencodeBin = args.opencode;
+
+  const version = opencodeVersionLine(args.opencode);
+  if (!/v2\./.test(version.text)) {
+    process.stdout.write(JSON.stringify({ error: 'not_v2', version: version.text, ...(version.error ? { detail: version.error } : {}) }) + '\n');
+    return 2;
+  }
+  note(`opencode ${version.text} at ${args.opencode}`);
+
+  state.tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'oc2-probe-'));
+  for (const dir of ['config', 'data', 'state', 'cache']) fs.mkdirSync(path.join(state.tempRoot, dir), { recursive: true });
+  note(`temp root ${state.tempRoot}`);
+
+  const listener = await startFakeAnthropic();
+  state.entries = listener.entries;
+  state.listener = listener;
+  note(`fake Anthropic listener on 127.0.0.1:${listener.port}`);
+
+  const switchSid = 'ses_ctmprobe' + crypto.randomBytes(10).toString('hex');
+  const serviceSid = 'ses_ctmprobe' + crypto.randomBytes(10).toString('hex');
+  const permissionSid = 'ses_ctmprobe' + crypto.randomBytes(10).toString('hex');
+  const legacySid = 'ses_ctmprobe' + crypto.randomBytes(10).toString('hex');
+  const subagentSid = 'ses_ctmprobe' + crypto.randomBytes(10).toString('hex');
+  note(`probe sessions: ${switchSid} (P-S1/P-S3a/P-S3b), ${serviceSid} (P-S4), ${permissionSid} (P-S9), ${legacySid} (P-S10), ${subagentSid} (P-S11)`);
+
+  try {
+    await probeSessionSwitch(listener.port, switchSid);
+    await probeSharedService(listener.port, serviceSid);
+    await probeFreshSession(listener.port);
+    await probePermissionEvents(listener.port, permissionSid);
+    await probeLegacyPluginFile(listener.port, legacySid);
+    await probeSubagentPermission(listener.port, subagentSid);
+  } catch (err) {
+    note(`fatal: ${(err && err.stack) || err}`);
+    process.exitCode = 1;
+  } finally {
+    for (const pid of state.startedPids) { if (pid) killTree(pid); }
+    try { await listener.stop(); } catch { /* expected: the listener socket is already closed */ }
+    if (args.keep) {
+      note(`temp root kept: ${state.tempRoot}`);
+    } else {
+      try { fs.rmSync(state.tempRoot, { recursive: true, force: true }); } catch (err) { note(`temp root cleanup failed: ${err}`); }
+    }
+  }
+
+  const failed = state.results.filter((row) => !row.pass);
+  const expected = state.only ? state.only.length : EXPECTED_PROBES;
+  note(`${state.results.length} probes, ${failed.length} failed (expected ${expected})`);
+  return failed.length === 0 && state.results.length === expected ? 0 : 1;
+}
+
+main().then((code) => { process.exitCode = code; }).catch((err) => {
+  process.stderr.write('[probe] fatal: ' + ((err && err.stack) || err) + '\n');
+  process.exitCode = 1;
+});