agentxchain 2.79.0 → 2.81.0

package/builtin-plugins/plugin-slack-notify/README.md

@@ -0,0 +1,34 @@
+# @agentxchain/plugin-slack-notify
+
+Built-in AgentXchain plugin that posts advisory lifecycle notifications to a Slack incoming webhook.
+
+Install from this repo:
+
+```bash
+agentxchain plugin install ./plugins/plugin-slack-notify
+```
+
+Optional install-time config:
+
+```bash
+agentxchain plugin install ./plugins/plugin-slack-notify \
+  --config '{"webhook_env":"MY_SLACK_WEBHOOK_URL","mention":"@ops"}'
+```
+
+Runtime inputs:
+
+- `webhook_env` (optional): which env var contains the Slack incoming webhook URL
+- `mention` (optional): prefix added to each message
+- default webhook lookup is `AGENTXCHAIN_SLACK_WEBHOOK_URL`, then `SLACK_WEBHOOK_URL`
+- `AGENTXCHAIN_SLACK_MENTION` remains a runtime fallback when `mention` is not configured
+
+Hook phases:
+
+- `after_acceptance`
+- `before_gate`
+- `on_escalation`
+
+Failure semantics:
+
+- advisory only
+- missing webhook config or delivery failures return `warn`, never `block`

package/builtin-plugins/plugin-slack-notify/agentxchain-plugin.json

@@ -0,0 +1,47 @@
+{
+  "schema_version": "0.1",
+  "name": "@agentxchain/plugin-slack-notify",
+  "version": "0.1.0",
+  "description": "Posts governed lifecycle notifications to a Slack incoming webhook.",
+  "hooks": {
+    "after_acceptance": [
+      {
+        "name": "slack_notify_acceptance",
+        "type": "process",
+        "command": ["node", "./hooks/after-acceptance.js"],
+        "timeout_ms": 5000,
+        "mode": "advisory"
+      }
+    ],
+    "before_gate": [
+      {
+        "name": "slack_notify_gate",
+        "type": "process",
+        "command": ["node", "./hooks/before-gate.js"],
+        "timeout_ms": 5000,
+        "mode": "advisory"
+      }
+    ],
+    "on_escalation": [
+      {
+        "name": "slack_notify_escalation",
+        "type": "process",
+        "command": ["node", "./hooks/on-escalation.js"],
+        "timeout_ms": 5000,
+        "mode": "advisory"
+      }
+    ]
+  },
+  "config_schema": {
+    "type": "object",
+    "properties": {
+      "webhook_env": {
+        "type": "string",
+        "default": "AGENTXCHAIN_SLACK_WEBHOOK_URL"
+      },
+      "mention": {
+        "type": "string"
+      }
+    }
+  }
+}

package/builtin-plugins/plugin-slack-notify/hooks/_shared.js

@@ -0,0 +1,115 @@
+import http from 'node:http';
+import https from 'node:https';
+import process from 'node:process';
+
+export async function readEnvelope() {
+  let input = '';
+  for await (const chunk of process.stdin) {
+    input += chunk;
+  }
+  return input.trim() ? JSON.parse(input) : {};
+}
+
+function parsePluginConfig() {
+  try {
+    const parsed = JSON.parse(process.env.AGENTXCHAIN_PLUGIN_CONFIG || '{}');
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+      return null;
+    }
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+function resolveWebhookSetting(config) {
+  const configuredEnv = typeof config?.webhook_env === 'string' ? config.webhook_env.trim() : '';
+  if (configuredEnv) {
+    return {
+      envName: configuredEnv,
+      url: process.env[configuredEnv] || '',
+    };
+  }
+
+  return {
+    envName: 'AGENTXCHAIN_SLACK_WEBHOOK_URL or SLACK_WEBHOOK_URL',
+    url: process.env.AGENTXCHAIN_SLACK_WEBHOOK_URL || process.env.SLACK_WEBHOOK_URL || '',
+  };
+}
+
+function buildText(title, lines, config) {
+  const mention = typeof config?.mention === 'string' && config.mention.trim()
+    ? config.mention.trim()
+    : (process.env.AGENTXCHAIN_SLACK_MENTION || '');
+  return [mention, title, ...lines.filter(Boolean)].filter(Boolean).join('\n');
+}
+
+export async function sendSlackMessage(title, lines) {
+  const config = parsePluginConfig();
+  if (config === null) {
+    return {
+      verdict: 'warn',
+      message: 'Invalid AGENTXCHAIN_PLUGIN_CONFIG JSON',
+    };
+  }
+
+  const webhookSetting = resolveWebhookSetting(config);
+  const webhookUrl = webhookSetting.url;
+  if (!webhookUrl) {
+    return {
+      verdict: 'warn',
+      message: `Missing Slack webhook env ${webhookSetting.envName}`,
+    };
+  }
+
+  const body = JSON.stringify({
+    text: buildText(title, lines, config),
+  });
+
+  const url = new URL(webhookUrl);
+  const transport = url.protocol === 'https:' ? https : http;
+  let response;
+  try {
+    response = await new Promise((resolve, reject) => {
+      const req = transport.request(url, {
+        method: 'POST',
+        headers: {
+          'content-type': 'application/json',
+          'content-length': Buffer.byteLength(body),
+        },
+        timeout: 4000,
+      }, (res) => {
+        res.resume();
+        res.on('end', () => resolve({ ok: (res.statusCode || 500) >= 200 && (res.statusCode || 500) < 300, status: res.statusCode || 500 }));
+      });
+
+      req.on('timeout', () => {
+        req.destroy(new Error('request timed out'));
+      });
+      req.on('error', reject);
+      req.write(body);
+      req.end();
+    });
+  } catch (error) {
+    return {
+      verdict: 'warn',
+      message: `Slack webhook request failed: ${error.message}`,
+    };
+  }
+
+  if (!response.ok) {
+    return {
+      verdict: 'warn',
+      message: `Slack webhook failed with HTTP ${response.status}`,
+    };
+  }
+
+  return {
+    verdict: 'allow',
+    message: 'Slack notification delivered',
+  };
+}
+
+export function writeResult(result) {
+  process.stdout.write(JSON.stringify(result));
+}

package/builtin-plugins/plugin-slack-notify/hooks/after-acceptance.js

@@ -0,0 +1,16 @@
+import { readEnvelope, sendSlackMessage, writeResult } from './_shared.js';
+
+const envelope = await readEnvelope();
+const payload = envelope.payload || {};
+
+const result = await sendSlackMessage('AgentXchain accepted turn', [
+  `run: ${envelope.run_id || 'unknown'}`,
+  `phase: ${payload.phase || 'unknown'}`,
+  `role: ${payload.role_id || 'unknown'}`,
+  `turn: ${payload.turn_id || 'unknown'}`,
+  `decisions: ${payload.decisions_count ?? 0}`,
+  `objections: ${payload.objections_count ?? 0}`,
+  `status: ${payload.run_status || 'unknown'}`,
+]);
+
+writeResult(result);

package/builtin-plugins/plugin-slack-notify/hooks/before-gate.js

@@ -0,0 +1,18 @@
+import { readEnvelope, sendSlackMessage, writeResult } from './_shared.js';
+
+const envelope = await readEnvelope();
+const payload = envelope.payload || {};
+
+const title = payload.gate_type === 'run_completion'
+  ? 'AgentXchain run completion awaiting approval'
+  : 'AgentXchain phase gate awaiting approval';
+
+const result = await sendSlackMessage(title, [
+  `run: ${envelope.run_id || 'unknown'}`,
+  `gate type: ${payload.gate_type || 'unknown'}`,
+  `current phase: ${payload.current_phase || 'unknown'}`,
+  `target phase: ${payload.target_phase || 'n/a'}`,
+  `history length: ${payload.history_length ?? 0}`,
+]);
+
+writeResult(result);

package/builtin-plugins/plugin-slack-notify/hooks/on-escalation.js

@@ -0,0 +1,15 @@
+import { readEnvelope, sendSlackMessage, writeResult } from './_shared.js';
+
+const envelope = await readEnvelope();
+const payload = envelope.payload || {};
+
+const result = await sendSlackMessage('AgentXchain escalation', [
+  `run: ${envelope.run_id || 'unknown'}`,
+  `blocked reason: ${payload.blocked_reason || 'unknown'}`,
+  `recovery: ${payload.recovery_action || 'unknown'}`,
+  `role: ${payload.failed_role || 'unknown'}`,
+  `turn: ${payload.failed_turn_id || 'unknown'}`,
+  `error: ${payload.last_error || 'unknown'}`,
+]);
+
+writeResult(result);

package/builtin-plugins/plugin-slack-notify/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "@agentxchain/plugin-slack-notify",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "description": "Built-in AgentXchain plugin that posts advisory lifecycle notifications to Slack.",
+  "license": "MIT"
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentxchain",
-  "version": "2.79.0",
+  "version": "2.81.0",
   "description": "CLI for AgentXchain — governed multi-agent software delivery",
   "type": "module",
   "bin": {
@@ -17,6 +17,7 @@
     "src/",
     "dashboard/",
     "scripts/",
+    "builtin-plugins/",
     "README.md"
   ],
   "scripts": {

package/src/commands/doctor.js

@@ -8,6 +8,7 @@ import { getWatchPid } from './watch.js';
 import { loadNormalizedConfig, detectConfigVersion } from '../lib/normalized-config.js';
 import { readDaemonState, evaluateDaemonStatus } from '../lib/run-schedule.js';
 import { getGovernedVersionSurface, formatGovernedVersionLabel } from '../lib/protocol-version.js';
+import { PLUGIN_MANIFEST_FILE } from '../lib/plugins.js';
 
 export async function doctorCommand(opts = {}) {
   const root = findProjectRoot(process.cwd());
@@ -74,6 +75,7 @@ function governedDoctor(root, rawConfig, opts) {
     const check = checkRuntimeReachable(rtId, rt);
     checks.push(check);
   }
+  const connectorProbe = getConnectorProbeRecommendation(runtimes);
 
   // 4. State directory
   const stateDir = join(root, '.agentxchain');
@@ -130,6 +132,90 @@ function governedDoctor(root, rawConfig, opts) {
     }
   }
 
+  // 8. Installed plugin health (only when plugins are installed)
+  const installedPlugins = rawConfig.plugins || {};
+  const pluginNames = Object.keys(installedPlugins);
+  if (pluginNames.length > 0) {
+    for (const pluginName of pluginNames) {
+      const meta = installedPlugins[pluginName];
+      const checkId = `plugin_${pluginName.replace(/[^a-z0-9_-]/gi, '_')}`;
+
+      // Check install path exists
+      if (!meta.install_path) {
+        checks.push({ id: checkId, name: `Plugin: ${pluginName}`, level: 'fail', detail: 'No install_path recorded', plugin_name: pluginName });
+        continue;
+      }
+      const installAbsPath = join(root, meta.install_path);
+      if (!existsSync(installAbsPath)) {
+        checks.push({ id: checkId, name: `Plugin: ${pluginName}`, level: 'fail', detail: `Install path missing: ${meta.install_path}`, plugin_name: pluginName });
+        continue;
+      }
+
+      // Check manifest exists and is valid
+      const manifestPath = join(installAbsPath, PLUGIN_MANIFEST_FILE);
+      if (!existsSync(manifestPath)) {
+        checks.push({ id: checkId, name: `Plugin: ${pluginName}`, level: 'fail', detail: 'Manifest file missing', plugin_name: pluginName });
+        continue;
+      }
+      let manifest;
+      try {
+        manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+      } catch (err) {
+        checks.push({ id: checkId, name: `Plugin: ${pluginName}`, level: 'fail', detail: `Manifest is corrupt JSON: ${err.message}`, plugin_name: pluginName });
+        continue;
+      }
+
+      // Check hook files exist
+      const hookErrors = [];
+      if (manifest.hooks && typeof manifest.hooks === 'object') {
+        for (const [hookName, hookDef] of Object.entries(manifest.hooks)) {
+          if (!hookDef) continue;
+          const commands = Array.isArray(hookDef) ? hookDef : (hookDef.command ? [hookDef] : []);
+          for (const cmd of commands) {
+            const cmdArgs = cmd.command || cmd;
+            if (Array.isArray(cmdArgs) && cmdArgs.length > 0) {
+              const firstArg = cmdArgs[0];
+              if (typeof firstArg === 'string' && (firstArg.startsWith('./') || firstArg.startsWith('../'))) {
+                const hookFilePath = join(installAbsPath, firstArg);
+                if (!existsSync(hookFilePath)) {
+                  hookErrors.push(`${hookName}: ${firstArg}`);
+                }
+              }
+            }
+          }
+        }
+      }
+      if (hookErrors.length > 0) {
+        checks.push({ id: checkId, name: `Plugin: ${pluginName}`, level: 'fail', detail: `Missing hook files: ${hookErrors.join(', ')}`, plugin_name: pluginName });
+        continue;
+      }
+
+      // Check config env vars (warn only)
+      const envWarnings = [];
+      const pluginConfig = meta.config || {};
+      for (const [key, value] of Object.entries(pluginConfig)) {
+        if (typeof value === 'string' && value.startsWith('$')) {
+          const envVar = value.slice(1);
+          if (!process.env[envVar]) {
+            envWarnings.push(envVar);
+          }
+        }
+      }
+      // Also check webhook_env pattern from config
+      if (pluginConfig.webhook_env && !process.env[pluginConfig.webhook_env]) {
+        if (!envWarnings.includes(pluginConfig.webhook_env)) {
+          envWarnings.push(pluginConfig.webhook_env);
+        }
+      }
+
+      if (envWarnings.length > 0) {
+        checks.push({ id: checkId, name: `Plugin: ${pluginName}`, level: 'warn', detail: `Env var(s) not set: ${envWarnings.join(', ')}`, plugin_name: pluginName });
+      } else {
+        checks.push({ id: checkId, name: `Plugin: ${pluginName}`, level: 'pass', detail: `v${manifest.version || '?'}, ${Object.keys(manifest.hooks || {}).length} hooks`, plugin_name: pluginName });
+      }
+    }
+  }
+
   // Compute summary
   const failCount = checks.filter(c => c.level === 'fail').length;
   const warnCount = checks.filter(c => c.level === 'warn').length;
@@ -143,6 +229,9 @@ function governedDoctor(root, rawConfig, opts) {
       ...versionSurface,
       config_version: versionSurface.config_generation,
       overall,
+      connector_probe_recommended: connectorProbe.recommended,
+      connector_probe_runtime_ids: connectorProbe.runtimeIds,
+      connector_probe_detail: connectorProbe.detail,
       checks,
       fail_count: failCount,
       warn_count: warnCount,
@@ -173,6 +262,9 @@ function governedDoctor(root, rawConfig, opts) {
     } else {
       console.log(chalk.red(`  Not ready: ${failCount} failure${failCount > 1 ? 's' : ''}, ${warnCount} warning${warnCount > 1 ? 's' : ''}.`));
     }
+    if (failCount === 0 && connectorProbe.recommended) {
+      console.log(chalk.dim(`  Next: ${connectorProbe.detail}`));
+    }
     console.log('');
   }
 
@@ -236,6 +328,35 @@ function checkRuntimeReachable(rtId, rt) {
   }
 }
 
+function getConnectorProbeRecommendation(runtimes) {
+  const runtimeIds = [];
+
+  for (const [rtId, rt] of Object.entries(runtimes || {})) {
+    if (!rt || typeof rt !== 'object') continue;
+    if (rt.type === 'api_proxy' || rt.type === 'remote_agent') {
+      runtimeIds.push(rtId);
+      continue;
+    }
+    if (rt.type === 'mcp' && (rt.transport || 'stdio') === 'streamable_http') {
+      runtimeIds.push(rtId);
+    }
+  }
+
+  if (runtimeIds.length === 0) {
+    return {
+      recommended: false,
+      runtimeIds: [],
+      detail: null,
+    };
+  }
+
+  return {
+    recommended: true,
+    runtimeIds,
+    detail: 'run `agentxchain connector check` to live-probe api / remote HTTP runtimes before the first governed turn.',
+  };
+}
+
 function getCurrentPhase(root) {
   const statePath = join(root, '.agentxchain', 'state.json');
   if (!existsSync(statePath)) return null;

package/src/commands/plugin.js

@@ -1,7 +1,7 @@
 import { readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 
-import { installPlugin, listInstalledPlugins, removePlugin, upgradePlugin } from '../lib/plugins.js';
+import { installPlugin, listInstalledPlugins, listAvailablePlugins, removePlugin, upgradePlugin } from '../lib/plugins.js';
 
 function parsePluginConfigOptions(options) {
   if (options.config && options.configFile) {
@@ -117,6 +117,36 @@ export async function pluginRemoveCommand(name, options) {
   console.log(`  Path: ${result.install_path}`);
 }
 
+export async function pluginListAvailableCommand(options) {
+  const result = listAvailablePlugins();
+
+  if (!result.ok) {
+    console.error(result.error);
+    if (options.json) {
+      console.log(JSON.stringify({ ok: false, error: result.error }, null, 2));
+    }
+    process.exitCode = 1;
+    return;
+  }
+
+  if (options.json) {
+    console.log(JSON.stringify({ plugins: result.plugins }, null, 2));
+    return;
+  }
+
+  if (result.plugins.length === 0) {
+    console.log('No built-in plugins available.');
+    return;
+  }
+
+  console.log(`Available built-in plugins: ${result.plugins.length}`);
+  for (const plugin of result.plugins) {
+    console.log(`  ${plugin.short_name}`);
+    console.log(`    ${plugin.description}`);
+    console.log(`    Install: ${plugin.install_command}`);
+  }
+}
+
 export async function pluginUpgradeCommand(name, source, options) {
   const config = parsePluginConfigOptions(options);
   if (!config.ok) {

package/src/commands/replay.js

@@ -0,0 +1,120 @@
+import chalk from 'chalk';
+
+import { loadProjectContext } from '../lib/config.js';
+import { normalizeVerification } from '../lib/repo-observer.js';
+import { resolveAcceptedTurnHistoryReference } from '../lib/accepted-turn-history.js';
+import {
+  DEFAULT_VERIFICATION_REPLAY_TIMEOUT_MS,
+  replayVerificationMachineEvidence,
+} from '../lib/verification-replay.js';
+
+export async function replayTurnCommand(turnId, opts = {}) {
+  const context = loadProjectContext();
+  if (!context) {
+    console.log(chalk.red('No agentxchain.json found. Run `agentxchain init` first.'));
+    process.exit(2);
+  }
+
+  if (context.config.protocol_mode !== 'governed' || context.version !== 4) {
+    console.log(chalk.red('replay turn is only available in governed v4 projects.'));
+    process.exit(2);
+  }
+
+  const timeoutMs = Number.parseInt(String(opts.timeout || String(DEFAULT_VERIFICATION_REPLAY_TIMEOUT_MS)), 10);
+  if (!Number.isInteger(timeoutMs) || timeoutMs <= 0) {
+    console.log(chalk.red('replay turn requires a positive integer --timeout in milliseconds.'));
+    process.exit(2);
+  }
+
+  const { root, config } = context;
+  const resolved = resolveAcceptedTurnHistoryReference(root, turnId);
+  if (!resolved.ok) {
+    console.log(chalk.red(resolved.error));
+    process.exit(2);
+  }
+
+  const entry = resolved.entry;
+  const runtimeType = config.runtimes?.[entry.runtime_id]?.type || 'unknown';
+  const payload = {
+    source: 'history',
+    match_kind: resolved.match_kind,
+    turn_id: entry.turn_id,
+    resolved_turn_id: resolved.resolved_ref,
+    run_id: entry.run_id || null,
+    role: entry.role || null,
+    phase: entry.phase || null,
+    runtime_id: entry.runtime_id || null,
+    runtime_type: runtimeType,
+    accepted_at: entry.accepted_at || null,
+    declared_status: entry.verification?.status || 'skipped',
+    normalized_status: normalizeVerification(entry.verification, runtimeType).status,
+    timeout_ms: timeoutMs,
+    prior_verification_replay: entry.verification_replay || null,
+    ...replayVerificationMachineEvidence({
+      root,
+      verification: entry.verification,
+      timeoutMs,
+    }),
+  };
+
+  emitReplayTurn(payload, opts.json);
+  process.exit(payload.overall === 'match' ? 0 : 1);
+}
+
+function emitReplayTurn(payload, jsonMode) {
+  if (jsonMode) {
+    console.log(JSON.stringify(payload, null, 2));
+    return;
+  }
+
+  console.log('');
+  console.log(chalk.bold(`  Replay Turn: ${chalk.cyan(payload.turn_id)}`));
+  console.log(chalk.dim('  ' + '─'.repeat(44)));
+  console.log(`  ${chalk.dim('Source:')}     accepted history (${payload.match_kind})`);
+  console.log(`  ${chalk.dim('Run:')}        ${payload.run_id || '—'}`);
+  console.log(`  ${chalk.dim('Role:')}       ${payload.role || '—'}`);
+  console.log(`  ${chalk.dim('Phase:')}      ${payload.phase || '—'}`);
+  console.log(`  ${chalk.dim('Runtime:')}    ${payload.runtime_id || '—'} (${payload.runtime_type})`);
+  console.log(`  ${chalk.dim('Accepted:')}   ${payload.accepted_at || '—'}`);
+  console.log(`  ${chalk.dim('Declared:')}   ${payload.declared_status}`);
+  console.log(`  ${chalk.dim('Normalized:')} ${payload.normalized_status}`);
+  if (payload.prior_verification_replay) {
+    const prior = payload.prior_verification_replay;
+    const verifiedAt = prior.verified_at ? ` at ${prior.verified_at}` : '';
+    console.log(`  ${chalk.dim('Prior replay:')} ${prior.overall} (${prior.matched_commands || 0}/${prior.replayed_commands || 0})${verifiedAt}`);
+  }
+  console.log(`  ${chalk.dim('Outcome:')}    ${formatOutcome(payload.overall)}`);
+
+  if (payload.reason) {
+    console.log(`  ${chalk.dim('Reason:')}     ${payload.reason}`);
+    console.log('');
+    return;
+  }
+
+  console.log('');
+  for (const command of payload.commands || []) {
+    const marker = command.matched ? chalk.green('match') : chalk.red('mismatch');
+    console.log(`  [${marker}] ${command.command}`);
+    console.log(`    declared=${command.declared_exit_code} actual=${command.actual_exit_code == null ? 'null' : command.actual_exit_code}`);
+    if (command.signal) {
+      console.log(`    signal=${command.signal}`);
+    }
+    if (command.timed_out) {
+      console.log('    timed_out=true');
+    }
+    if (command.error) {
+      console.log(`    error=${command.error}`);
+    }
+  }
+
+  console.log('');
+  console.log(chalk.dim('  Replay uses the current workspace and shell environment. It verifies declared exit-code reproducibility, not historical stdout/stderr identity.'));
+  console.log('');
+}
+
+function formatOutcome(outcome) {
+  if (outcome === 'match') return chalk.green('match');
+  if (outcome === 'mismatch') return chalk.red('mismatch');
+  return chalk.yellow('not_reproducible');
+}
+

package/src/lib/accepted-turn-history.js

@@ -0,0 +1,84 @@
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+
+const HISTORY_PATH = '.agentxchain/history.jsonl';
+
+export function queryAcceptedTurnHistory(root) {
+  const filePath = join(root, HISTORY_PATH);
+  if (!existsSync(filePath)) return [];
+
+  let content;
+  try {
+    content = readFileSync(filePath, 'utf8').trim();
+  } catch {
+    return [];
+  }
+
+  if (!content) return [];
+
+  return content
+    .split('\n')
+    .filter(Boolean)
+    .map((line) => {
+      try {
+        return JSON.parse(line);
+      } catch {
+        return null;
+      }
+    })
+    .filter((entry) => entry && typeof entry.turn_id === 'string')
+    .reverse();
+}
+
+export function resolveAcceptedTurnHistoryReference(root, ref) {
+  const entries = queryAcceptedTurnHistory(root);
+
+  if (entries.length === 0) {
+    return {
+      ok: false,
+      error: 'No accepted turn history found. Accept at least one governed turn first.',
+    };
+  }
+
+  if (!ref) {
+    return {
+      ok: true,
+      entry: entries[0],
+      resolved_ref: entries[0].turn_id,
+      match_kind: 'latest',
+    };
+  }
+
+  const exact = entries.find((entry) => entry.turn_id === ref);
+  if (exact) {
+    return {
+      ok: true,
+      entry: exact,
+      resolved_ref: exact.turn_id,
+      match_kind: 'exact',
+    };
+  }
+
+  const prefixMatches = entries.filter((entry) => entry.turn_id.startsWith(ref));
+  if (prefixMatches.length === 1) {
+    return {
+      ok: true,
+      entry: prefixMatches[0],
+      resolved_ref: prefixMatches[0].turn_id,
+      match_kind: 'prefix',
+    };
+  }
+
+  if (prefixMatches.length > 1) {
+    return {
+      ok: false,
+      error: `Turn reference "${ref}" is ambiguous. Matches: ${prefixMatches.map((entry) => entry.turn_id).join(', ')}`,
+    };
+  }
+
+  return {
+    ok: false,
+    error: `Accepted turn ${ref} not found in history.`,
+  };
+}
+