a2acalling 0.6.44 → 0.6.45

package/docs/plans/2026-02-16-e2e-test-prompt-sequence.md

@@ -0,0 +1,1812 @@
+# E2E Test & Prompt Sequence for A2A Install/Onboarding/Invite Flow
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Build an AI-agent-driven E2E testing system where an orchestrator spawns a subagent that installs a2acalling from npm, runs onboarding, exercises the invite flow between two isolated servers, and reports results (including auto-filing bugs in Linear).
+
+**Architecture:** The test system uses isolated temp directories (extending the existing `tmpConfigDir` pattern) to spin up two independent a2a servers on ephemeral ports. A CLI runner wraps all `a2a` commands with structured output parsing. The orchestrator script coordinates the full sequence: environment setup → install verification → onboarding → token creation → invite exchange → cross-server call → report generation. A prompt document gives a Claude subagent the exact steps and expected outcomes.
+
+**Tech Stack:** Node.js, Express (ephemeral ports), child_process (CLI invocation), existing zero-dependency test runner, Linear API (for bug filing via MCP or REST)
+
+**Linear ticket:** A2A-21
+
+---
+
+## Phase 1: E2E Environment & CLI Runner
+
+### Task 1: Create E2E environment isolation utility
+
+**Files:**
+- Create: `test/e2e/env.js`
+- Test: `test/e2e/env.test.js`
+
+**Step 1: Write the failing test**
+
+```javascript
+// test/e2e/env.test.js
+module.exports = function (test, assert, helpers) {
+  test('createE2EEnv returns isolated dir with cleanup', () => {
+    const { createE2EEnv } = require('./env');
+    const env = createE2EEnv('test-basic');
+
+    assert.ok(env.dir, 'Should have a directory');
+    assert.ok(env.configDir, 'Should have a config directory');
+    assert.ok(env.env.A2A_CONFIG_DIR, 'Should set A2A_CONFIG_DIR');
+
+    const fs = require('fs');
+    assert.ok(fs.existsSync(env.dir), 'Directory should exist');
+    assert.ok(fs.existsSync(env.configDir), 'Config dir should exist');
+
+    env.cleanup();
+    assert.equal(fs.existsSync(env.dir), false, 'Should clean up');
+  });
+
+  test('createE2EEnv provides isolated process env', () => {
+    const { createE2EEnv } = require('./env');
+    const envA = createE2EEnv('env-a');
+    const envB = createE2EEnv('env-b');
+
+    assert.ok(envA.configDir !== envB.configDir, 'Should be different dirs');
+
+    envA.cleanup();
+    envB.cleanup();
+  });
+
+  test('createE2EEnv finds available port', async () => {
+    const { createE2EEnv } = require('./env');
+    const env = createE2EEnv('port-test');
+
+    const port = await env.findAvailablePort();
+    assert.ok(port >= 3001 && port <= 65535, 'Should return valid port');
+
+    env.cleanup();
+  });
+};
+```
+
+**Step 2: Run test to verify it fails**
+
+Run: `node test/run.js --filter "createE2EEnv"`
+Expected: FAIL — module not found
+
+**Step 3: Write minimal implementation**
+
+```javascript
+// test/e2e/env.js
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const net = require('net');
+
+/**
+ * Create a fully isolated E2E test environment.
+ *
+ * Returns { dir, configDir, env, findAvailablePort, cleanup }.
+ *
+ * - dir: root temp directory for this test run
+ * - configDir: path that A2A_CONFIG_DIR points to
+ * - env: process.env clone with A2A_CONFIG_DIR set
+ * - findAvailablePort(): resolves to an unused port
+ * - cleanup(): removes all temp files
+ */
+function createE2EEnv(prefix = 'a2a-e2e') {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), `${prefix}-`));
+  const configDir = path.join(dir, 'config');
+  fs.mkdirSync(configDir, { recursive: true });
+
+  const env = {
+    ...process.env,
+    A2A_CONFIG_DIR: configDir,
+    // Prevent postinstall from running quickstart
+    CI: 'true'
+  };
+
+  function findAvailablePort(startPort = 3001) {
+    return new Promise((resolve, reject) => {
+      const server = net.createServer();
+      server.listen(0, '127.0.0.1', () => {
+        const port = server.address().port;
+        server.close(() => resolve(port));
+      });
+      server.on('error', reject);
+    });
+  }
+
+  function cleanup() {
+    try {
+      fs.rmSync(dir, { recursive: true, force: true });
+    } catch (e) { /* best-effort */ }
+  }
+
+  return { dir, configDir, env, findAvailablePort, cleanup };
+}
+
+module.exports = { createE2EEnv };
+```
+
+**Step 4: Run test to verify it passes**
+
+Run: `node test/run.js --filter "createE2EEnv"`
+Expected: PASS (all 3 tests)
+
+**Step 5: Commit**
+
+```bash
+git add test/e2e/env.js test/e2e/env.test.js
+git commit -m "feat(e2e): add isolated environment utility"
+```
+
+---
+
+### Task 2: Create CLI runner utility
+
+**Files:**
+- Create: `test/e2e/cli-runner.js`
+- Test: `test/e2e/cli-runner.test.js`
+
+**Step 1: Write the failing test**
+
+```javascript
+// test/e2e/cli-runner.test.js
+module.exports = function (test, assert, helpers) {
+  const { createE2EEnv } = require('./env');
+
+  test('CLIRunner.run executes a2a command and returns output', async () => {
+    const env = createE2EEnv('cli-run');
+    const { CLIRunner } = require('./cli-runner');
+    const runner = new CLIRunner(env);
+
+    // 'a2a help' should work without onboarding
+    const result = await runner.run('help');
+    assert.equal(result.exitCode, 0, 'Should exit 0');
+    assert.ok(result.stdout.length > 0, 'Should have stdout');
+
+    env.cleanup();
+  });
+
+  test('CLIRunner.run captures non-zero exit codes', async () => {
+    const env = createE2EEnv('cli-fail');
+    const { CLIRunner } = require('./cli-runner');
+    const runner = new CLIRunner(env);
+
+    // 'a2a call' without onboarding should fail
+    const result = await runner.run('call', ['nobody', 'hello']);
+    assert.ok(result.exitCode !== 0, 'Should exit non-zero');
+
+    env.cleanup();
+  });
+
+  test('CLIRunner.run respects timeout', async () => {
+    const env = createE2EEnv('cli-timeout');
+    const { CLIRunner } = require('./cli-runner');
+    const runner = new CLIRunner(env, { timeout: 500 });
+
+    // Running a command that hangs should time out
+    const result = await runner.run('server', ['99999'], { timeout: 500 });
+    assert.ok(result.timedOut || result.exitCode !== 0, 'Should timeout or fail');
+
+    env.cleanup();
+  });
+
+  test('CLIRunner.onboard completes full onboarding via --submit', async () => {
+    const env = createE2EEnv('cli-onboard');
+    const { CLIRunner } = require('./cli-runner');
+    const runner = new CLIRunner(env);
+
+    const fs = require('fs');
+    const path = require('path');
+
+    // Pre-set config to awaiting_disclosure (skip port detection step)
+    const configPath = path.join(env.configDir, 'a2a-config.json');
+    fs.writeFileSync(configPath, JSON.stringify({
+      onboarding: { version: 2, step: 'awaiting_disclosure' },
+      agent: { hostname: 'localhost:3001', name: 'e2e-test-agent' },
+      tiers: {}
+    }));
+
+    const result = await runner.onboard({
+      personalityNotes: 'E2E test agent — direct and minimal',
+      topics: [{ topic: 'Testing', description: 'Automated E2E tests' }]
+    });
+
+    assert.ok(result.success, 'Onboarding should succeed');
+    assert.ok(result.stdout.includes('Onboarding complete'), 'Should say complete');
+
+    env.cleanup();
+  });
+};
+```
+
+**Step 2: Run test to verify it fails**
+
+Run: `node test/run.js --filter "CLIRunner"`
+Expected: FAIL — module not found
+
+**Step 3: Write minimal implementation**
+
+```javascript
+// test/e2e/cli-runner.js
+const { execFile } = require('child_process');
+const path = require('path');
+
+const CLI_PATH = path.join(__dirname, '..', '..', 'bin', 'cli.js');
+
+/**
+ * Wraps the a2a CLI for structured E2E testing.
+ *
+ * Each method runs the CLI as a child process in the
+ * given E2E environment, returning { stdout, stderr, exitCode, timedOut }.
+ */
+class CLIRunner {
+  constructor(e2eEnv, options = {}) {
+    this.env = e2eEnv;
+    this.defaultTimeout = options.timeout || 30000;
+  }
+
+  /**
+   * Run an a2a CLI command.
+   * @param {string} command - The a2a subcommand (e.g., 'list', 'create')
+   * @param {string[]} args - Additional arguments
+   * @param {object} options - { timeout }
+   * @returns {Promise<{stdout, stderr, exitCode, timedOut}>}
+   */
+  run(command, args = [], options = {}) {
+    const timeout = options.timeout || this.defaultTimeout;
+    const fullArgs = [CLI_PATH, command, ...args];
+
+    return new Promise((resolve) => {
+      const child = execFile(process.execPath, fullArgs, {
+        env: this.env.env,
+        encoding: 'utf8',
+        timeout,
+        maxBuffer: 1024 * 1024
+      }, (error, stdout, stderr) => {
+        resolve({
+          stdout: stdout || '',
+          stderr: stderr || '',
+          exitCode: error ? (error.code || 1) : 0,
+          timedOut: error && error.killed
+        });
+      });
+    });
+  }
+
+  /**
+   * Complete onboarding programmatically via `onboard --submit`.
+   *
+   * @param {object} disclosure - { personalityNotes, topics, objectives, neverDisclose }
+   * @returns {Promise<{success, stdout, stderr}>}
+   */
+  async onboard(disclosure = {}) {
+    const submission = {
+      tiers: {
+        public: {
+          topics: disclosure.topics || [{ topic: 'General', description: 'Open discussion' }],
+          objectives: disclosure.objectives || [],
+          do_not_discuss: disclosure.doNotDiscuss || []
+        },
+        friends: { topics: [], objectives: [], do_not_discuss: [] },
+        family: { topics: [], objectives: [], do_not_discuss: [] }
+      },
+      never_disclose: disclosure.neverDisclose || [],
+      personality_notes: disclosure.personalityNotes || 'E2E test agent'
+    };
+
+    const result = await this.run('onboard', ['--submit', JSON.stringify(submission)]);
+    return {
+      success: result.exitCode === 0 && result.stdout.includes('Onboarding complete'),
+      stdout: result.stdout,
+      stderr: result.stderr,
+      exitCode: result.exitCode
+    };
+  }
+
+  /**
+   * Create a token and return the parsed output.
+   * @param {object} options - { name, tier, expires, maxCalls, topics }
+   * @returns {Promise<{success, token, inviteUrl, stdout}>}
+   */
+  async createToken(options = {}) {
+    const args = [];
+    if (options.name) args.push('--name', options.name);
+    if (options.tier) args.push('--tier', options.tier);
+    if (options.expires) args.push('--expires', options.expires);
+    if (options.maxCalls) args.push('--max-calls', String(options.maxCalls));
+    if (options.topics) args.push('--topics', options.topics);
+
+    const result = await this.run('create', args);
+
+    // Parse invite URL from output (format: a2a://host/token)
+    const urlMatch = result.stdout.match(/a2a:\/\/[^\s]+/);
+    const tokenMatch = result.stdout.match(/fed_[A-Za-z0-9_-]+/);
+
+    return {
+      success: result.exitCode === 0,
+      inviteUrl: urlMatch ? urlMatch[0] : null,
+      token: tokenMatch ? tokenMatch[0] : null,
+      stdout: result.stdout,
+      stderr: result.stderr
+    };
+  }
+
+  /**
+   * Add a contact from an invite URL.
+   * @param {string} inviteUrl - a2a://host/token URL
+   * @param {string} name - Contact name
+   * @returns {Promise<{success, stdout, stderr}>}
+   */
+  async addContact(inviteUrl, name) {
+    const result = await this.run('add', [inviteUrl, name]);
+    return {
+      success: result.exitCode === 0,
+      stdout: result.stdout,
+      stderr: result.stderr
+    };
+  }
+
+  /**
+   * List tokens.
+   * @returns {Promise<{success, stdout}>}
+   */
+  async listTokens() {
+    const result = await this.run('list');
+    return {
+      success: result.exitCode === 0,
+      stdout: result.stdout,
+      stderr: result.stderr
+    };
+  }
+
+  /**
+   * List contacts.
+   * @returns {Promise<{success, stdout}>}
+   */
+  async listContacts() {
+    const result = await this.run('contacts');
+    return {
+      success: result.exitCode === 0,
+      stdout: result.stdout,
+      stderr: result.stderr
+    };
+  }
+
+  /**
+   * Ping a remote agent.
+   * @param {string} target - URL or contact name
+   * @returns {Promise<{success, stdout}>}
+   */
+  async ping(target) {
+    const result = await this.run('ping', [target]);
+    return {
+      success: result.exitCode === 0,
+      stdout: result.stdout,
+      stderr: result.stderr
+    };
+  }
+}
+
+module.exports = { CLIRunner };
+```
+
+**Step 4: Run test to verify it passes**
+
+Run: `node test/run.js --filter "CLIRunner"`
+Expected: PASS (all 4 tests)
+
+**Step 5: Commit**
+
+```bash
+git add test/e2e/cli-runner.js test/e2e/cli-runner.test.js
+git commit -m "feat(e2e): add CLI runner utility for structured command execution"
+```
+
+---
+
+## Phase 2: Two-Server E2E Test
+
+### Task 3: Create two-server test harness
+
+**Files:**
+- Create: `test/e2e/two-server.js`
+- Test: `test/e2e/two-server.test.js`
+
+**Step 1: Write the failing test**
+
+```javascript
+// test/e2e/two-server.test.js
+module.exports = function (test, assert, helpers) {
+  const { TwoServerHarness } = require('./two-server');
+
+  test('TwoServerHarness starts two isolated servers', async () => {
+    const harness = new TwoServerHarness();
+    await harness.setup();
+
+    assert.ok(harness.agentA, 'Agent A should exist');
+    assert.ok(harness.agentB, 'Agent B should exist');
+    assert.ok(harness.agentA.port, 'Agent A should have a port');
+    assert.ok(harness.agentB.port, 'Agent B should have a port');
+    assert.ok(harness.agentA.port !== harness.agentB.port, 'Ports should differ');
+
+    // Both should respond to ping
+    const http = require('http');
+    const pingA = await httpGet(`http://127.0.0.1:${harness.agentA.port}/api/a2a/ping`);
+    assert.ok(pingA.pong, 'Agent A should respond to ping');
+
+    const pingB = await httpGet(`http://127.0.0.1:${harness.agentB.port}/api/a2a/ping`);
+    assert.ok(pingB.pong, 'Agent B should respond to ping');
+
+    await harness.teardown();
+  });
+
+  test('TwoServerHarness provides token stores for each agent', async () => {
+    const harness = new TwoServerHarness();
+    await harness.setup();
+
+    // Create token on Agent A
+    const { token } = harness.agentA.tokenStore.create({ name: 'TestToken' });
+    assert.match(token, /^fed_/);
+
+    // Token should NOT exist on Agent B
+    const validation = harness.agentB.tokenStore.validate(token);
+    assert.equal(validation.valid, false);
+
+    await harness.teardown();
+  });
+
+  // Helper to make GET request
+  function httpGet(url) {
+    const http = require('http');
+    return new Promise((resolve, reject) => {
+      http.get(url, (res) => {
+        let data = '';
+        res.on('data', chunk => data += chunk);
+        res.on('end', () => {
+          try { resolve(JSON.parse(data)); }
+          catch { resolve(data); }
+        });
+      }).on('error', reject);
+    });
+  }
+};
+```
+
+**Step 2: Run test to verify it fails**
+
+Run: `node test/run.js --filter "TwoServerHarness"`
+Expected: FAIL — module not found
+
+**Step 3: Write minimal implementation**
+
+```javascript
+// test/e2e/two-server.js
+const { createE2EEnv } = require('./env');
+const path = require('path');
+
+/**
+ * Starts two independent A2A servers on ephemeral ports,
+ * each with their own config directory and token store.
+ *
+ * This simulates two separate agents that can exchange
+ * invites and call each other over HTTP.
+ */
+class TwoServerHarness {
+  constructor(options = {}) {
+    this.agentA = null;
+    this.agentB = null;
+    this.handleMessageA = options.handleMessageA || defaultHandler('AgentA');
+    this.handleMessageB = options.handleMessageB || defaultHandler('AgentB');
+  }
+
+  async setup() {
+    this.agentA = await this._startAgent('agent-a', this.handleMessageA);
+    this.agentB = await this._startAgent('agent-b', this.handleMessageB);
+  }
+
+  async _startAgent(name, handleMessage) {
+    const env = createE2EEnv(`e2e-${name}`);
+    const port = await env.findAvailablePort();
+
+    // Fresh requires to get isolated instances
+    delete require.cache[require.resolve('../../src/lib/tokens')];
+    delete require.cache[require.resolve('../../src/routes/a2a')];
+
+    const express = require('express');
+    const { TokenStore } = require('../../src/lib/tokens');
+    const { createRoutes } = require('../../src/routes/a2a');
+
+    const tokenStore = new TokenStore(env.configDir);
+    const app = express();
+    app.use(express.json({ limit: '100kb' }));
+
+    app.use('/api/a2a', createRoutes({
+      tokenStore,
+      handleMessage,
+      notifyOwner: () => Promise.resolve()
+    }));
+
+    const server = await new Promise((resolve) => {
+      const s = app.listen(port, '127.0.0.1', () => resolve(s));
+    });
+
+    return {
+      name,
+      port,
+      env,
+      tokenStore,
+      app,
+      server,
+      hostname: `127.0.0.1:${port}`,
+      inviteBase: `a2a://127.0.0.1:${port}`
+    };
+  }
+
+  async teardown() {
+    if (this.agentA) {
+      await closeServer(this.agentA.server);
+      this.agentA.env.cleanup();
+    }
+    if (this.agentB) {
+      await closeServer(this.agentB.server);
+      this.agentB.env.cleanup();
+    }
+  }
+}
+
+function defaultHandler(name) {
+  return async function (message, context) {
+    return {
+      text: `${name} received: ${message.slice(0, 100)}`,
+      canContinue: true
+    };
+  };
+}
+
+function closeServer(server) {
+  return new Promise((resolve) => {
+    if (server) server.close(resolve);
+    else resolve();
+  });
+}
+
+module.exports = { TwoServerHarness };
+```
+
+**Step 4: Run test to verify it passes**
+
+Run: `node test/run.js --filter "TwoServerHarness"`
+Expected: PASS (both tests)
+
+**Step 5: Commit**
+
+```bash
+git add test/e2e/two-server.js test/e2e/two-server.test.js
+git commit -m "feat(e2e): add two-server harness for cross-agent testing"
+```
+
+---
+
+### Task 4: Write the full E2E install + onboard + invite test
+
+**Files:**
+- Create: `test/e2e/full-flow.test.js`
+
+This is the core test that exercises the complete user journey across two agents.
+
+**Step 1: Write the test**
+
+```javascript
+// test/e2e/full-flow.test.js
+/**
+ * Full E2E Flow Test
+ *
+ * Simulates the complete A2A user journey between two agents:
+ *
+ *   1. Both agents start with fresh environments
+ *   2. Agent A completes onboarding
+ *   3. Agent A creates an invite token
+ *   4. Agent B adds Agent A as a contact using the invite URL
+ *   5. Agent B calls Agent A via HTTP
+ *   6. Agent A responds
+ *   7. Multi-turn conversation works
+ *   8. Conversation ends cleanly
+ */
+module.exports = function (test, assert, helpers) {
+  const http = require('http');
+  const { TwoServerHarness } = require('./two-server');
+
+  let harness = null;
+
+  async function teardown() {
+    if (harness) await harness.teardown();
+    harness = null;
+  }
+
+  // ── Full Flow: Onboard → Create Token → Invite → Call ──
+
+  test('full E2E: Agent B calls Agent A via invite URL', async () => {
+    harness = new TwoServerHarness();
+    await harness.setup();
+
+    const agentA = harness.agentA;
+    const agentB = harness.agentB;
+
+    // Step 1: Agent A creates a token for Agent B
+    const { token, record } = agentA.tokenStore.create({
+      name: 'AgentB-Access',
+      permissions: 'public',
+      expires: '1h',
+      maxCalls: 10,
+      allowedTopics: ['testing', 'automation']
+    });
+
+    assert.match(token, /^fed_/, 'Token should start with fed_');
+    assert.equal(record.name, 'AgentB-Access');
+    assert.equal(record.tier, 'public');
+
+    // Step 2: Construct invite URL
+    const inviteUrl = `${agentA.inviteBase}/${token}`;
+    assert.match(inviteUrl, /^a2a:\/\//, 'Invite should be a2a:// URL');
+
+    // Step 3: Agent B adds Agent A as a contact
+    agentB.tokenStore.addContact(inviteUrl, {
+      name: 'AgentA',
+      notes: 'E2E test partner'
+    });
+
+    const contacts = agentB.tokenStore.listContacts();
+    assert.equal(contacts.length, 1);
+    assert.equal(contacts[0].name, 'AgentA');
+
+    // Step 4: Agent B retrieves the stored token and calls Agent A
+    const contact = agentB.tokenStore.getContact('AgentA');
+    assert.equal(contact.host, agentA.hostname);
+    assert.equal(contact.token, token);
+
+    // Step 5: Make the actual HTTP call (Agent B → Agent A)
+    const callResult = await httpPost(
+      `http://${agentA.hostname}/api/a2a/invoke`,
+      {
+        message: 'Hello Agent A, this is Agent B calling.',
+        caller: { name: 'AgentB', owner: 'E2E Test' }
+      },
+      { Authorization: `Bearer ${token}` }
+    );
+
+    assert.equal(callResult.statusCode, 200);
+    assert.ok(callResult.body.success);
+    assert.match(callResult.body.conversation_id, /^conv_/);
+    assert.ok(callResult.body.response.includes('AgentA received'));
+    assert.equal(callResult.body.can_continue, true);
+    assert.equal(callResult.body.tokens_remaining, 9);
+
+    // Step 6: Multi-turn — send follow-up on same conversation
+    const followUp = await httpPost(
+      `http://${agentA.hostname}/api/a2a/invoke`,
+      {
+        message: 'Follow-up question from Agent B.',
+        conversation_id: callResult.body.conversation_id,
+        caller: { name: 'AgentB', owner: 'E2E Test' }
+      },
+      { Authorization: `Bearer ${token}` }
+    );
+
+    assert.equal(followUp.statusCode, 200);
+    assert.ok(followUp.body.success);
+    assert.equal(followUp.body.conversation_id, callResult.body.conversation_id);
+    assert.equal(followUp.body.tokens_remaining, 8);
+
+    // Step 7: Verify token usage was tracked
+    const tokenRecord = agentA.tokenStore.findById(record.id);
+    assert.equal(tokenRecord.calls_made, 2);
+
+    await teardown();
+  });
+
+  test('full E2E: bidirectional — both agents exchange invites', async () => {
+    harness = new TwoServerHarness();
+    await harness.setup();
+
+    const agentA = harness.agentA;
+    const agentB = harness.agentB;
+
+    // Agent A creates token for B
+    const tokenAtoB = agentA.tokenStore.create({
+      name: 'ForAgentB', permissions: 'friends', maxCalls: 5
+    });
+
+    // Agent B creates token for A
+    const tokenBtoA = agentB.tokenStore.create({
+      name: 'ForAgentA', permissions: 'public', maxCalls: 5
+    });
+
+    // Exchange invites
+    const inviteA = `${agentA.inviteBase}/${tokenAtoB.token}`;
+    const inviteB = `${agentB.inviteBase}/${tokenBtoA.token}`;
+
+    agentB.tokenStore.addContact(inviteA, { name: 'AgentA' });
+    agentA.tokenStore.addContact(inviteB, { name: 'AgentB' });
+
+    // B calls A
+    const resBA = await httpPost(
+      `http://${agentA.hostname}/api/a2a/invoke`,
+      { message: 'B calling A', caller: { name: 'AgentB' } },
+      { Authorization: `Bearer ${tokenAtoB.token}` }
+    );
+    assert.equal(resBA.statusCode, 200);
+    assert.ok(resBA.body.success);
+
+    // A calls B
+    const resAB = await httpPost(
+      `http://${agentB.hostname}/api/a2a/invoke`,
+      { message: 'A calling B', caller: { name: 'AgentA' } },
+      { Authorization: `Bearer ${tokenBtoA.token}` }
+    );
+    assert.equal(resAB.statusCode, 200);
+    assert.ok(resAB.body.success);
+
+    await teardown();
+  });
+
+  test('full E2E: revoked token rejected mid-conversation', async () => {
+    harness = new TwoServerHarness();
+    await harness.setup();
+
+    const { token, record } = harness.agentA.tokenStore.create({
+      name: 'Revocable', maxCalls: 10
+    });
+
+    // First call succeeds
+    const res1 = await httpPost(
+      `http://${harness.agentA.hostname}/api/a2a/invoke`,
+      { message: 'First call', caller: { name: 'Tester' } },
+      { Authorization: `Bearer ${token}` }
+    );
+    assert.equal(res1.statusCode, 200);
+
+    // Revoke the token
+    harness.agentA.tokenStore.revoke(record.id);
+
+    // Second call rejected
+    const res2 = await httpPost(
+      `http://${harness.agentA.hostname}/api/a2a/invoke`,
+      { message: 'After revoke', caller: { name: 'Tester' } },
+      { Authorization: `Bearer ${token}` }
+    );
+    assert.equal(res2.statusCode, 401);
+    assert.equal(res2.body.error, 'unauthorized');
+
+    await teardown();
+  });
+
+  test('full E2E: expired token rejected', async () => {
+    harness = new TwoServerHarness();
+    await harness.setup();
+
+    // Create token that expires immediately (1ms)
+    const { token } = harness.agentA.tokenStore.create({
+      name: 'ShortLived', expires: '1ms'
+    });
+
+    // Wait for expiry
+    await new Promise(r => setTimeout(r, 50));
+
+    const res = await httpPost(
+      `http://${harness.agentA.hostname}/api/a2a/invoke`,
+      { message: 'Too late', caller: { name: 'Tester' } },
+      { Authorization: `Bearer ${token}` }
+    );
+    assert.equal(res.statusCode, 401);
+    assert.equal(res.body.error, 'unauthorized');
+
+    await teardown();
+  });
+
+  test('full E2E: max calls enforcement across multi-turn', async () => {
+    harness = new TwoServerHarness();
+    await harness.setup();
+
+    const { token } = harness.agentA.tokenStore.create({
+      name: 'LimitedCalls', maxCalls: 2
+    });
+
+    // Call 1 OK
+    const r1 = await httpPost(
+      `http://${harness.agentA.hostname}/api/a2a/invoke`,
+      { message: 'Call 1', caller: { name: 'Tester' } },
+      { Authorization: `Bearer ${token}` }
+    );
+    assert.equal(r1.statusCode, 200);
+
+    // Call 2 OK
+    const r2 = await httpPost(
+      `http://${harness.agentA.hostname}/api/a2a/invoke`,
+      { message: 'Call 2', caller: { name: 'Tester' } },
+      { Authorization: `Bearer ${token}` }
+    );
+    assert.equal(r2.statusCode, 200);
+
+    // Call 3 rejected
+    const r3 = await httpPost(
+      `http://${harness.agentA.hostname}/api/a2a/invoke`,
+      { message: 'Call 3', caller: { name: 'Tester' } },
+      { Authorization: `Bearer ${token}` }
+    );
+    assert.equal(r3.statusCode, 401);
+
+    await teardown();
+  });
+
+  // ── HTTP helper ──
+  function httpPost(url, body, headers = {}) {
+    const urlObj = new URL(url);
+    return new Promise((resolve, reject) => {
+      const data = JSON.stringify(body);
+      const req = http.request({
+        hostname: urlObj.hostname,
+        port: urlObj.port,
+        path: urlObj.pathname,
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'Content-Length': Buffer.byteLength(data),
+          ...headers
+        }
+      }, (res) => {
+        let responseData = '';
+        res.on('data', chunk => responseData += chunk);
+        res.on('end', () => {
+          let parsed;
+          try { parsed = JSON.parse(responseData); } catch { parsed = responseData; }
+          resolve({ statusCode: res.statusCode, headers: res.headers, body: parsed });
+        });
+      });
+      req.on('error', reject);
+      req.write(data);
+      req.end();
+    });
+  }
+};
+```
+
+**Step 2: Run test to verify it passes**
+
+Run: `node test/run.js --filter "full E2E"`
+Expected: PASS (all 5 tests)
+
+**Step 3: Commit**
+
+```bash
+git add test/e2e/full-flow.test.js
+git commit -m "feat(e2e): add full flow tests — onboard, invite, cross-agent call"
+```
+
+---
+
+## Phase 3: Agent Prompt Sequence & Report
+
+### Task 5: Create the E2E test agent prompt sequence
+
+**Files:**
+- Create: `docs/prompts/e2e-test-agent.md`
+
+This is the prompt document that an AI orchestrator gives to a subagent. The subagent follows these steps to test the A2A system.
+
+**Step 1: Write the prompt document**
+
+```markdown
+# A2A E2E Test Agent — Prompt Sequence
+
+You are an E2E test agent for the `a2acalling` npm package. Your job is to verify
+that a fresh install, onboarding, and invite flow all work correctly.
+
+## Your Environment
+
+You have been given a clean working directory. You will:
+1. Install `a2acalling` from npm (or use a local tarball if provided)
+2. Run through the full onboarding flow
+3. Create tokens and test the invite flow
+4. Verify the server responds correctly
+5. Report all findings
+
+## Pre-Flight
+
+Before starting, verify:
+- [ ] Node.js >= 18 is available (`node --version`)
+- [ ] npm is available (`npm --version`)
+- [ ] Working directory is clean and writable
+- [ ] No existing A2A config (`ls ~/.config/openclaw/` should not exist or be empty)
+
+If any pre-flight check fails, report the failure and stop.
+
+## Step 1: Install a2acalling
+
+```bash
+npm install -g a2acalling
+```
+
+**Expected:**
+- Exit code 0
+- `a2a` command is now available
+- `a2a --version` prints a version number
+
+**Report if:** Install fails, postinstall errors, command not found after install.
+
+## Step 2: Run Quickstart (Onboarding)
+
+```bash
+a2a quickstart
+```
+
+**Expected:**
+- Step 1: Port detection — finds an available port (3001-3020)
+- Step 2: Server starts on the detected port
+- Step 3: Disclosure prompt appears — asking for topics, objectives, personality
+- The agent should be in `awaiting_disclosure` state
+
+**Then submit disclosure:**
+
+```bash
+a2a quickstart --submit '{
+  "tiers": {
+    "public": {
+      "topics": [{"topic": "Testing", "description": "Automated system testing"}],
+      "objectives": [{"objective": "Verify install", "description": "Confirm the package works"}],
+      "do_not_discuss": []
+    },
+    "friends": {"topics": [], "objectives": [], "do_not_discuss": []},
+    "family": {"topics": [], "objectives": [], "do_not_discuss": []}
+  },
+  "never_disclose": ["Test secrets"],
+  "personality_notes": "Direct and methodical test agent"
+}'
+```
+
+**Expected:**
+- "Disclosure manifest saved"
+- "Onboarding complete"
+- Step numbers are sequential (no duplicates)
+- Config file exists at `~/.config/openclaw/a2a-config.json` with `onboarding.step === 'complete'`
+- First invite URL is generated (`a2a://hostname/fed_...`)
+
+**Report if:** Onboarding hangs, step numbers are wrong, manifest not saved, invite not generated.
+
+## Step 3: Verify Server Health
+
+```bash
+a2a ping a2a://localhost:<port>/test
+```
+
+Or directly:
+
+```bash
+curl http://localhost:<port>/api/a2a/ping
+```
+
+**Expected:** `{"pong": true, "timestamp": "..."}`
+
+```bash
+curl http://localhost:<port>/api/a2a/status
+```
+
+**Expected:** `{"a2a": true, "version": "...", "capabilities": ["invoke", "multi-turn", ...]}`
+
+**Report if:** Server not running, ping fails, status missing expected fields.
+
+## Step 4: Create Invite Token
+
+```bash
+a2a create --name "E2E-Tester" --tier public --expires 1h --max-calls 20
+```
+
+**Expected:**
+- Token created successfully
+- Invite URL printed: `a2a://hostname/fed_...`
+- Token appears in `a2a list`
+
+**Report if:** Token creation fails, URL format wrong, not in list.
+
+## Step 5: Test Inbound Call
+
+Using the invite URL from Step 4, make a direct HTTP call:
+
+```bash
+TOKEN="<token from step 4>"
+PORT="<port from step 2>"
+curl -X POST http://localhost:$PORT/api/a2a/invoke \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer $TOKEN" \
+  -d '{"message": "Hello from E2E test agent", "caller": {"name": "E2E-Tester", "owner": "Automated Test"}}'
+```
+
+**Expected Response:**
+```json
+{
+  "success": true,
+  "conversation_id": "conv_...",
+  "response": "...",
+  "can_continue": true,
+  "tokens_remaining": 19
+}
+```
+
+**Report if:** 401 unauthorized, 500 error, missing conversation_id, unexpected response shape.
+
+## Step 6: Test Multi-Turn Conversation
+
+Using the `conversation_id` from Step 5:
+
+```bash
+curl -X POST http://localhost:$PORT/api/a2a/invoke \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer $TOKEN" \
+  -d '{"message": "Follow-up message", "conversation_id": "<conv_id>", "caller": {"name": "E2E-Tester"}}'
+```
+
+**Expected:**
+- Same `conversation_id` returned
+- `tokens_remaining` decremented by 1
+- `can_continue` is true
+
+**Report if:** Conversation ID changes, token count wrong, can_continue unexpected.
+
+## Step 7: Test Error Cases
+
+### 7a. No Authorization
+```bash
+curl -X POST http://localhost:$PORT/api/a2a/invoke \
+  -H "Content-Type: application/json" \
+  -d '{"message": "No auth"}'
+```
+**Expected:** 401, `{"error": "missing_token"}`
+
+### 7b. Invalid Token
+```bash
+curl -X POST http://localhost:$PORT/api/a2a/invoke \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer fed_invalid_garbage" \
+  -d '{"message": "Bad token"}'
+```
+**Expected:** 401, `{"error": "unauthorized"}`
+
+### 7c. Missing Message
+```bash
+curl -X POST http://localhost:$PORT/api/a2a/invoke \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer $TOKEN" \
+  -d '{}'
+```
+**Expected:** 400, `{"error": "missing_message"}`
+
+**Report if:** Any error case returns unexpected status code or error format.
+
+## Step 8: Token Revocation
+
+```bash
+# Get token ID from list
+a2a list
+
+# Revoke it
+a2a revoke <token_id>
+
+# Verify call fails
+curl -X POST http://localhost:$PORT/api/a2a/invoke \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer $TOKEN" \
+  -d '{"message": "Should fail"}'
+```
+
+**Expected:** 401 after revocation.
+
+**Report if:** Revoked token still works.
+
+## Step 9: Cleanup
+
+```bash
+a2a uninstall
+```
+
+**Expected:** Server stopped, config files removed.
+
+## Reporting Format
+
+After completing all steps, produce a report in this format:
+
+```markdown
+# A2A E2E Test Report
+
+**Date:** YYYY-MM-DD HH:MM:SS
+**Package Version:** x.y.z
+**Node Version:** vXX.X.X
+**Platform:** linux/darwin/win32
+
+## Results
+
+| Step | Name | Status | Notes |
+|------|------|--------|-------|
+| 1 | Install | PASS/FAIL | ... |
+| 2 | Onboarding | PASS/FAIL | ... |
+| 3 | Server Health | PASS/FAIL | ... |
+| 4 | Create Token | PASS/FAIL | ... |
+| 5 | Inbound Call | PASS/FAIL | ... |
+| 6 | Multi-Turn | PASS/FAIL | ... |
+| 7 | Error Cases | PASS/FAIL | ... |
+| 8 | Revocation | PASS/FAIL | ... |
+| 9 | Cleanup | PASS/FAIL | ... |
+
+## Issues Found
+
+### Issue 1: [Title]
+**Step:** N
+**Severity:** critical/high/medium/low
+**Description:** What happened
+**Expected:** What should have happened
+**Actual:** What actually happened
+**Reproduction:** Exact commands to reproduce
+```
+
+For each issue found, the orchestrator should create a Linear ticket
+with the "Todo" status on the "a2a calling" team, labeled "Bug" and "E2E".
+```
+
+**Step 2: Commit**
+
+```bash
+git add docs/prompts/e2e-test-agent.md
+git commit -m "docs: add E2E test agent prompt sequence"
+```
+
+---
+
+### Task 6: Create report generator with Linear integration
+
+**Files:**
+- Create: `test/e2e/report.js`
+- Test: `test/e2e/report.test.js`
+
+**Step 1: Write the failing test**
+
+```javascript
+// test/e2e/report.test.js
+module.exports = function (test, assert, helpers) {
+  const { E2EReport } = require('./report');
+
+  test('E2EReport tracks step results', () => {
+    const report = new E2EReport({ version: '0.6.44', nodeVersion: 'v20.0.0' });
+
+    report.pass(1, 'Install', 'Installed successfully');
+    report.pass(2, 'Onboarding', 'Completed in 3s');
+    report.fail(3, 'Server Health', 'Ping returned 500', {
+      expected: '200 with pong',
+      actual: '500 internal error',
+      severity: 'critical'
+    });
+
+    assert.equal(report.results.length, 3);
+    assert.equal(report.passed, 2);
+    assert.equal(report.failed, 1);
+    assert.equal(report.issues.length, 1);
+    assert.equal(report.issues[0].step, 3);
+    assert.equal(report.issues[0].severity, 'critical');
+  });
+
+  test('E2EReport generates markdown', () => {
+    const report = new E2EReport({ version: '0.6.44', nodeVersion: 'v20.0.0' });
+
+    report.pass(1, 'Install', 'OK');
+    report.fail(2, 'Onboarding', 'Manifest not saved', {
+      expected: 'Manifest file created',
+      actual: 'File missing',
+      severity: 'high'
+    });
+
+    const md = report.toMarkdown();
+    assert.includes(md, '# A2A E2E Test Report');
+    assert.includes(md, '0.6.44');
+    assert.includes(md, 'PASS');
+    assert.includes(md, 'FAIL');
+    assert.includes(md, 'Manifest not saved');
+    assert.includes(md, 'high');
+  });
+
+  test('E2EReport generates Linear issue descriptions', () => {
+    const report = new E2EReport({ version: '0.6.44', nodeVersion: 'v20.0.0' });
+
+    report.fail(5, 'Inbound Call', 'Got 500 instead of 200', {
+      expected: '200 success',
+      actual: '500 internal_error',
+      severity: 'critical',
+      reproduction: 'curl -X POST http://localhost:3001/api/a2a/invoke ...'
+    });
+
+    const issues = report.toLinearIssues();
+    assert.equal(issues.length, 1);
+    assert.includes(issues[0].title, 'Inbound Call');
+    assert.includes(issues[0].description, '500');
+    assert.includes(issues[0].description, 'Reproduction');
+    assert.equal(issues[0].priority, 1); // critical = urgent
+  });
+};
+```
+
+**Step 2: Run test to verify it fails**
+
+Run: `node test/run.js --filter "E2EReport"`
+Expected: FAIL — module not found
+
+**Step 3: Write minimal implementation**
+
+```javascript
+// test/e2e/report.js
+/**
+ * E2E Test Report Generator
+ *
+ * Tracks pass/fail results for each step and can output:
+ * - Markdown summary for human review
+ * - Linear issue descriptions for automated bug filing
+ */
+class E2EReport {
+  constructor(meta = {}) {
+    this.meta = {
+      version: meta.version || 'unknown',
+      nodeVersion: meta.nodeVersion || process.version,
+      platform: meta.platform || process.platform,
+      date: new Date().toISOString()
+    };
+    this.results = [];
+    this.issues = [];
+    this.passed = 0;
+    this.failed = 0;
+  }
+
+  pass(step, name, notes = '') {
+    this.results.push({ step, name, status: 'PASS', notes });
+    this.passed++;
+  }
+
+  fail(step, name, notes, details = {}) {
+    this.results.push({ step, name, status: 'FAIL', notes });
+    this.failed++;
+    this.issues.push({
+      step,
+      name,
+      notes,
+      expected: details.expected || '',
+      actual: details.actual || '',
+      severity: details.severity || 'medium',
+      reproduction: details.reproduction || ''
+    });
+  }
+
+  toMarkdown() {
+    const lines = [
+      '# A2A E2E Test Report',
+      '',
+      `**Date:** ${this.meta.date}`,
+      `**Package Version:** ${this.meta.version}`,
+      `**Node Version:** ${this.meta.nodeVersion}`,
+      `**Platform:** ${this.meta.platform}`,
+      '',
+      `## Summary: ${this.passed} passed, ${this.failed} failed`,
+      '',
+      '## Results',
+      '',
+      '| Step | Name | Status | Notes |',
+      '|------|------|--------|-------|'
+    ];
+
+    for (const r of this.results) {
+      lines.push(`| ${r.step} | ${r.name} | ${r.status} | ${r.notes} |`);
+    }
+
+    if (this.issues.length > 0) {
+      lines.push('', '## Issues Found', '');
+      for (let i = 0; i < this.issues.length; i++) {
+        const issue = this.issues[i];
+        lines.push(
+          `### Issue ${i + 1}: ${issue.name}`,
+          `**Step:** ${issue.step}`,
+          `**Severity:** ${issue.severity}`,
+          `**Description:** ${issue.notes}`,
+          `**Expected:** ${issue.expected}`,
+          `**Actual:** ${issue.actual}`,
+          ''
+        );
+        if (issue.reproduction) {
+          lines.push(`**Reproduction:**`, '```', issue.reproduction, '```', '');
+        }
+      }
+    }
+
+    return lines.join('\n');
+  }
+
+  /**
+   * Convert issues to Linear issue format.
+   * @returns {Array<{title, description, priority, labels}>}
+   */
+  toLinearIssues() {
+    const severityToPriority = {
+      critical: 1,  // Urgent
+      high: 2,      // High
+      medium: 3,    // Normal
+      low: 4        // Low
+    };
+
+    return this.issues.map(issue => ({
+      title: `[E2E] Step ${issue.step}: ${issue.name} — ${issue.notes.slice(0, 60)}`,
+      description: [
+        `## E2E Test Failure`,
+        '',
+        `**Step:** ${issue.step} — ${issue.name}`,
+        `**Severity:** ${issue.severity}`,
+        `**Package Version:** ${this.meta.version}`,
+        `**Node:** ${this.meta.nodeVersion}`,
+        `**Platform:** ${this.meta.platform}`,
+        '',
+        `### Expected`,
+        issue.expected,
+        '',
+        `### Actual`,
+        issue.actual,
+        '',
+        issue.reproduction ? `### Reproduction\n\`\`\`\n${issue.reproduction}\n\`\`\`` : ''
+      ].join('\n'),
+      priority: severityToPriority[issue.severity] || 3,
+      labels: ['Bug', 'E2E']
+    }));
+  }
+}
+
+module.exports = { E2EReport };
+```
+
+**Step 4: Run test to verify it passes**
+
+Run: `node test/run.js --filter "E2EReport"`
+Expected: PASS (all 3 tests)
+
+**Step 5: Commit**
+
+```bash
+git add test/e2e/report.js test/e2e/report.test.js
+git commit -m "feat(e2e): add report generator with Linear issue formatting"
+```
+
+---
+
+### Task 7: Create orchestrator entry point
+
+**Files:**
+- Create: `test/e2e/orchestrate.js`
+
+This is the script that ties everything together. It can be run standalone (`node test/e2e/orchestrate.js`) or invoked by a Claude agent.
+
+**Step 1: Write the orchestrator**
+
+```javascript
+#!/usr/bin/env node
+/**
+ * E2E Test Orchestrator
+ *
+ * Runs the full A2A E2E test suite:
+ *   1. Sets up two isolated agent environments
+ *   2. Runs onboarding on both
+ *   3. Exchanges invites
+ *   4. Tests cross-agent calls
+ *   5. Tests error cases
+ *   6. Generates report
+ *
+ * Usage:
+ *   node test/e2e/orchestrate.js [--json] [--verbose]
+ *
+ * Exit codes:
+ *   0 = all tests passed
+ *   1 = one or more failures
+ */
+
+const { TwoServerHarness } = require('./two-server');
+const { E2EReport } = require('./report');
+const http = require('http');
+
+const verbose = process.argv.includes('--verbose');
+const jsonOutput = process.argv.includes('--json');
+
+function log(msg) {
+  if (verbose) console.log(`  ${msg}`);
+}
+
+function httpPost(url, body, headers = {}) {
+  const urlObj = new URL(url);
+  return new Promise((resolve, reject) => {
+    const data = JSON.stringify(body);
+    const req = http.request({
+      hostname: urlObj.hostname,
+      port: urlObj.port,
+      path: urlObj.pathname,
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Content-Length': Buffer.byteLength(data),
+        ...headers
+      }
+    }, (res) => {
+      let responseData = '';
+      res.on('data', chunk => responseData += chunk);
+      res.on('end', () => {
+        let parsed;
+        try { parsed = JSON.parse(responseData); } catch { parsed = responseData; }
+        resolve({ statusCode: res.statusCode, headers: res.headers, body: parsed });
+      });
+    });
+    req.on('error', reject);
+    req.write(data);
+    req.end();
+  });
+}
+
+function httpGet(url) {
+  return new Promise((resolve, reject) => {
+    http.get(url, (res) => {
+      let data = '';
+      res.on('data', chunk => data += chunk);
+      res.on('end', () => {
+        try { resolve({ statusCode: res.statusCode, body: JSON.parse(data) }); }
+        catch { resolve({ statusCode: res.statusCode, body: data }); }
+      });
+    }).on('error', reject);
+  });
+}
+
+async function main() {
+  let version;
+  try { version = require('../../package.json').version; } catch { version = 'unknown'; }
+
+  const report = new E2EReport({ version });
+  let harness = null;
+
+  try {
+    // ── Step 1: Environment Setup ──
+    console.log('Step 1: Setting up two isolated agents...');
+    harness = new TwoServerHarness();
+    await harness.setup();
+    log(`Agent A on port ${harness.agentA.port}`);
+    log(`Agent B on port ${harness.agentB.port}`);
+    report.pass(1, 'Environment Setup', `Ports: ${harness.agentA.port}, ${harness.agentB.port}`);
+
+    // ── Step 2: Server Health ──
+    console.log('Step 2: Checking server health...');
+    const pingA = await httpGet(`http://127.0.0.1:${harness.agentA.port}/api/a2a/ping`);
+    const pingB = await httpGet(`http://127.0.0.1:${harness.agentB.port}/api/a2a/ping`);
+
+    if (pingA.body.pong && pingB.body.pong) {
+      report.pass(2, 'Server Health', 'Both agents respond to ping');
+    } else {
+      report.fail(2, 'Server Health', 'Ping failed', {
+        expected: 'pong: true from both agents',
+        actual: `A: ${JSON.stringify(pingA.body)}, B: ${JSON.stringify(pingB.body)}`,
+        severity: 'critical'
+      });
+    }
+
+    // ── Step 3: Token Creation ──
+    console.log('Step 3: Creating tokens...');
+    const tokenA = harness.agentA.tokenStore.create({
+      name: 'E2E-ForAgentB',
+      permissions: 'public',
+      expires: '1h',
+      maxCalls: 10,
+      allowedTopics: ['testing']
+    });
+
+    if (tokenA.token && tokenA.token.startsWith('fed_')) {
+      report.pass(3, 'Token Creation', `Token: ${tokenA.token.slice(0, 12)}...`);
+    } else {
+      report.fail(3, 'Token Creation', 'Token format invalid', {
+        expected: 'fed_... format',
+        actual: String(tokenA.token),
+        severity: 'critical'
+      });
+    }
+
+    // ── Step 4: Contact Exchange ──
+    console.log('Step 4: Exchanging invites...');
+    const inviteUrl = `${harness.agentA.inviteBase}/${tokenA.token}`;
+    const addResult = harness.agentB.tokenStore.addContact(inviteUrl, { name: 'AgentA' });
+    const contacts = harness.agentB.tokenStore.listContacts();
+
+    if (addResult.success && contacts.length === 1) {
+      report.pass(4, 'Contact Exchange', `Agent B added Agent A as contact`);
+    } else {
+      report.fail(4, 'Contact Exchange', 'Failed to add contact', {
+        expected: 'Contact added successfully',
+        actual: `success: ${addResult.success}, contacts: ${contacts.length}`,
+        severity: 'high'
+      });
+    }
+
+    // ── Step 5: Inbound Call ──
+    console.log('Step 5: Testing inbound call (B → A)...');
+    const callRes = await httpPost(
+      `http://${harness.agentA.hostname}/api/a2a/invoke`,
+      {
+        message: 'Hello from E2E Agent B',
+        caller: { name: 'AgentB', owner: 'E2E Orchestrator' }
+      },
+      { Authorization: `Bearer ${tokenA.token}` }
+    );
+
+    if (callRes.statusCode === 200 && callRes.body.success && callRes.body.conversation_id) {
+      report.pass(5, 'Inbound Call', `Conv: ${callRes.body.conversation_id}`);
+    } else {
+      report.fail(5, 'Inbound Call', `Status ${callRes.statusCode}`, {
+        expected: '200 with success: true and conversation_id',
+        actual: JSON.stringify(callRes.body).slice(0, 200),
+        severity: 'critical'
+      });
+    }
+
+    // ── Step 6: Multi-Turn ──
+    console.log('Step 6: Testing multi-turn conversation...');
+    if (callRes.body.conversation_id) {
+      const followUp = await httpPost(
+        `http://${harness.agentA.hostname}/api/a2a/invoke`,
+        {
+          message: 'Follow-up from Agent B',
+          conversation_id: callRes.body.conversation_id,
+          caller: { name: 'AgentB' }
+        },
+        { Authorization: `Bearer ${tokenA.token}` }
+      );
+
+      if (followUp.statusCode === 200 && followUp.body.conversation_id === callRes.body.conversation_id) {
+        report.pass(6, 'Multi-Turn', `Same conv ID, tokens remaining: ${followUp.body.tokens_remaining}`);
+      } else {
+        report.fail(6, 'Multi-Turn', 'Conversation ID mismatch or failure', {
+          expected: `conv_id: ${callRes.body.conversation_id}`,
+          actual: `conv_id: ${followUp.body.conversation_id}, status: ${followUp.statusCode}`,
+          severity: 'high'
+        });
+      }
+    } else {
+      report.fail(6, 'Multi-Turn', 'Skipped — no conversation_id from step 5', { severity: 'high' });
+    }
+
+    // ── Step 7: Error Cases ──
+    console.log('Step 7: Testing error cases...');
+    let errorsPassed = 0;
+    const errorTotal = 3;
+
+    // 7a: No auth
+    const noAuth = await httpPost(
+      `http://${harness.agentA.hostname}/api/a2a/invoke`,
+      { message: 'No auth' }
+    );
+    if (noAuth.statusCode === 401 && noAuth.body.error === 'missing_token') errorsPassed++;
+
+    // 7b: Bad token
+    const badToken = await httpPost(
+      `http://${harness.agentA.hostname}/api/a2a/invoke`,
+      { message: 'Bad token' },
+      { Authorization: 'Bearer fed_totally_invalid' }
+    );
+    if (badToken.statusCode === 401 && badToken.body.error === 'unauthorized') errorsPassed++;
+
+    // 7c: Missing message
+    const noMsg = await httpPost(
+      `http://${harness.agentA.hostname}/api/a2a/invoke`,
+      {},
+      { Authorization: `Bearer ${tokenA.token}` }
+    );
+    if (noMsg.statusCode === 400 && noMsg.body.error === 'missing_message') errorsPassed++;
+
+    if (errorsPassed === errorTotal) {
+      report.pass(7, 'Error Cases', `All ${errorTotal} error cases correct`);
+    } else {
+      report.fail(7, 'Error Cases', `${errorsPassed}/${errorTotal} passed`, {
+        expected: `All ${errorTotal} error cases return correct status/error`,
+        actual: `noAuth: ${noAuth.statusCode}/${noAuth.body.error}, badToken: ${badToken.statusCode}/${badToken.body.error}, noMsg: ${noMsg.statusCode}/${noMsg.body.error}`,
+        severity: 'high'
+      });
+    }
+
+    // ── Step 8: Token Revocation ──
+    console.log('Step 8: Testing token revocation...');
+    harness.agentA.tokenStore.revoke(tokenA.record.id);
+    const revokedCall = await httpPost(
+      `http://${harness.agentA.hostname}/api/a2a/invoke`,
+      { message: 'After revoke', caller: { name: 'AgentB' } },
+      { Authorization: `Bearer ${tokenA.token}` }
+    );
+
+    if (revokedCall.statusCode === 401) {
+      report.pass(8, 'Token Revocation', 'Revoked token correctly rejected');
+    } else {
+      report.fail(8, 'Token Revocation', `Got ${revokedCall.statusCode} instead of 401`, {
+        expected: '401 unauthorized',
+        actual: `${revokedCall.statusCode}: ${JSON.stringify(revokedCall.body)}`,
+        severity: 'critical',
+        reproduction: `Revoke token then POST /invoke with same token`
+      });
+    }
+
+  } catch (err) {
+    report.fail(0, 'Orchestrator Error', err.message, {
+      expected: 'No uncaught errors',
+      actual: err.stack,
+      severity: 'critical'
+    });
+  } finally {
+    if (harness) await harness.teardown();
+  }
+
+  // ── Output ──
+  if (jsonOutput) {
+    console.log(JSON.stringify({
+      meta: report.meta,
+      passed: report.passed,
+      failed: report.failed,
+      results: report.results,
+      issues: report.issues,
+      linearIssues: report.toLinearIssues()
+    }, null, 2));
+  } else {
+    console.log('');
+    console.log(report.toMarkdown());
+  }
+
+  process.exit(report.failed > 0 ? 1 : 0);
+}
+
+main();
+```
+
+**Step 2: Run the orchestrator**
+
+Run: `node test/e2e/orchestrate.js --verbose`
+Expected: All 8 steps PASS, exit code 0
+
+**Step 3: Commit**
+
+```bash
+git add test/e2e/orchestrate.js
+git commit -m "feat(e2e): add orchestrator — runs full E2E suite and generates report"
+```
+
+---
+
+## Phase 4: Integration with Test Runner
+
+### Task 8: Register E2E tests with the existing test runner
+
+**Files:**
+- Modify: `test/run.js` — add `--e2e` flag support
+- Create: `test/e2e/index.test.js` — wrapper that runs E2E tests via the standard runner
+
+The existing test runner at `test/run.js` supports `--unit` and `--integration` flags. We add `--e2e` for the new tests.
+
+**Step 1: Check current test runner structure**
+
+Read `test/run.js` to understand how it discovers and runs test files. The runner globs `test/unit/*.test.js` and `test/integration/*.test.js`. We need it to also glob `test/e2e/*.test.js` when `--e2e` is passed (or when no filter is specified and `--all` is used).
+
+**Step 2: Create E2E index wrapper**
+
+```javascript
+// test/e2e/index.test.js
+/**
+ * E2E Test Suite
+ *
+ * These tests require ephemeral ports and take longer than unit/integration tests.
+ * Run with: node test/run.js --e2e
+ * Or:       node test/run.js --filter "E2E"
+ */
+module.exports = function (test, assert, helpers) {
+  // Re-export individual E2E test files
+  require('./env.test.js')(test, assert, helpers);
+  require('./cli-runner.test.js')(test, assert, helpers);
+  require('./two-server.test.js')(test, assert, helpers);
+  require('./full-flow.test.js')(test, assert, helpers);
+  require('./report.test.js')(test, assert, helpers);
+};
+```
+
+**Step 3: Modify test runner to support `--e2e` flag**
+
+In `test/run.js`, locate where test files are discovered and add:
+- When `--e2e` is passed: only run `test/e2e/*.test.js`
+- When `--all` or no category flag: include E2E tests
+- Default behavior (no flags): run unit + integration (NOT e2e, since they're slower)
+
+**Step 4: Run all E2E tests**
+
+Run: `node test/run.js --e2e --verbose`
+Expected: All E2E tests pass
+
+**Step 5: Run full suite to verify no regressions**
+
+Run: `npm test`
+Expected: All unit + integration tests still pass (E2E excluded by default)
+
+**Step 6: Commit**
+
+```bash
+git add test/e2e/index.test.js test/run.js
+git commit -m "feat(e2e): register E2E tests with test runner under --e2e flag"
+```
+
+---
+
+## Phase 5: Documentation
+
+### Task 9: Add E2E section to protocol docs
+
+**Files:**
+- Modify: `docs/protocol.md` — add "E2E Testing" section
+
+**Step 1: Add E2E testing documentation section**
+
+At the end of `docs/protocol.md`, add:
+
+```markdown
+## E2E Testing
+
+### Running the E2E Suite
+
+```bash
+# Run E2E tests via test runner
+node test/run.js --e2e
+
+# Run the orchestrator directly (verbose output)
+node test/e2e/orchestrate.js --verbose
+
+# Get JSON report (for automated processing)
+node test/e2e/orchestrate.js --json
+```
+
+### AI Agent Testing
+
+The E2E prompt sequence at `docs/prompts/e2e-test-agent.md` provides step-by-step
+instructions for a Claude subagent to test a fresh a2acalling installation.
+
+**Orchestrator workflow:**
+1. Spawn subagent with the prompt from `docs/prompts/e2e-test-agent.md`
+2. Subagent follows the 9-step sequence
+3. Subagent produces a markdown report
+4. Orchestrator reviews failures and creates Linear issues
+
+### Architecture
+
+The E2E system uses:
+- `test/e2e/env.js` — Isolated temp directories and port allocation
+- `test/e2e/cli-runner.js` — Structured CLI command execution
+- `test/e2e/two-server.js` — Two independent Express servers on ephemeral ports
+- `test/e2e/full-flow.test.js` — Cross-agent call tests
+- `test/e2e/report.js` — Markdown and Linear issue generation
+- `test/e2e/orchestrate.js` — Standalone orchestrator script
+```
+
+**Step 2: Commit**
+
+```bash
+git add docs/protocol.md docs/prompts/e2e-test-agent.md
+git commit -m "docs: add E2E testing section and agent prompt sequence"
+```
+
+---
+
+## Summary
+
+| Task | Phase | What It Builds |
+|------|-------|----------------|
+| 1 | Environment | Isolated temp dirs + port allocation |
+| 2 | CLI Runner | Structured CLI command wrapper |
+| 3 | Two-Server | Dual Express servers for cross-agent testing |
+| 4 | Full Flow Tests | 5 E2E tests: invite, bidirectional, revoke, expire, max-calls |
+| 5 | Agent Prompt | 9-step prompt sequence for AI subagent testing |
+| 6 | Report Generator | Markdown output + Linear issue formatting |
+| 7 | Orchestrator | Standalone script: `node test/e2e/orchestrate.js` |
+| 8 | Test Runner Integration | `--e2e` flag in existing runner |
+| 9 | Documentation | Protocol docs + testing guide |
+
+**Total new files:** 9
+**Total modified files:** 2 (`test/run.js`, `docs/protocol.md`)
+**Estimated commits:** 9