create-harness-vibe-coding 0.8.19 → 0.9.3

package/src/wf-ui-server/__tests__/workflow-claude-materialize.test.mjs

@@ -0,0 +1,209 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import { makeHarnessTempRoot } from '../../../tests/support/temp-root.js';
+import {
+  encodeClaudeProjectDir,
+  extractConversationTurns,
+  buildClaudeTranscript,
+  materializeClaudeTranscript,
+} from '../claude-transcript-materializer.mjs';
+
+// Fixtures mirror the real terminal.jsonl shapes captured from a live claude
+// harness session (RESUME-E2E-EVIDENCE.md PASS 3, session dae0424d): char-by-char
+// stdin, "❯ " prompt echo, spinner/progress stdout, "●answer✻Verb for Xs❯ " reply.
+
+let seq = 0;
+function entry(stream, data) {
+  return { seq: ++seq, ts: new Date().toISOString(), stream, data };
+}
+function typePrompt(text) {
+  const entries = [];
+  for (const ch of text) entries.push(entry('stdin', ch));
+  entries.push(entry('stdin', '\r'));
+  return entries;
+}
+function ansi(text) {
+  return `\x1b[38;2;87;105;247m${text}\x1b[39m`;
+}
+
+const PROMPT_A = 'Reply with exactly one word: plum';
+const REPLY_A = ansi('✢thinking with max effort Thought for 9s ●plum✻Baked for 9s❯ ');
+const PROMPT_B = 'What was the one word I asked you to reply?';
+const ECHO_B = `❯ ${PROMPT_B}`;
+const REPLY_B = ansi('Thought for 5s ●plum✻Worked for 5s❯ ');
+
+function singleTurnEntries() {
+  return [...typePrompt(PROMPT_A), entry('stdout', REPLY_A)];
+}
+
+test('U1 single turn: prompt from stdin chars, answer from ● bullet', () => {
+  const turns = extractConversationTurns(singleTurnEntries());
+  assert.equal(turns.length, 1);
+  assert.deepEqual(turns[0], { user: PROMPT_A, assistant: 'plum' });
+});
+
+test('U2 multi-turn: next prompt echo does not leak into previous answer', () => {
+  const entries = [
+    ...typePrompt(PROMPT_A),
+    entry('stdout', REPLY_A),
+    entry('stdout', ECHO_B), // echo of turn 2 leaks into turn 1 stdout segment
+    ...typePrompt(PROMPT_B),
+    entry('stdout', REPLY_B),
+  ];
+  const turns = extractConversationTurns(entries);
+  assert.equal(turns.length, 2);
+  assert.equal(turns[0].assistant, 'plum');
+  assert.deepEqual(turns[1], { user: PROMPT_B, assistant: 'plum' });
+});
+
+test('U3 slash commands are control input, not conversation turns', () => {
+  const entries = [
+    ...typePrompt('/model'),
+    entry('stdout', 'model picker'),
+    ...singleTurnEntries(),
+  ];
+  const turns = extractConversationTurns(entries);
+  assert.equal(turns.length, 1);
+  assert.equal(turns[0].user, PROMPT_A);
+});
+
+test('U4 boot-only session (no submitted prompt) yields no turns', () => {
+  const turns = extractConversationTurns([
+    entry('stdin', 'R'),
+    entry('stdout', 'Claude Code v2.1.215'),
+    entry('stdin', 'e'),
+  ]);
+  assert.deepEqual(turns, []);
+});
+
+test('U10 promptSubmit shape: one full-prompt stdin entry, no CR in the ring', () => {
+  // The promptSubmit path types char-by-char at the PTY level and sends the enter
+  // as a raw write, so the ring holds ONE stdin entry with the whole prompt and
+  // the turn bracket is the only delimiter (real E2E shape, session d9245593).
+  const entries = [
+    entry('stdin', PROMPT_A),
+    entry('stdout', ansi(`❯ ${PROMPT_A}`)), // composer echo
+    entry('stdout', ansi('✢thinking with max effort')),
+    entry('stdout', ansi('●mango✻Crunched for 5s❯ ')),
+  ];
+  const turns = extractConversationTurns(entries);
+  assert.equal(turns.length, 1);
+  assert.deepEqual(turns[0], { user: PROMPT_A, assistant: 'mango' });
+});
+
+test('U8 answer cleanup: verb tail, spinner glyphs, thinking preview, multi-bullet', () => {
+  const entries = [
+    ...typePrompt(PROMPT_A),
+    entry('stdout', ansi('Thought for 3s\n⎿ thinking preview line\n● item one\n● item two✻Baked for 3s❯ ')),
+  ];
+  const turns = extractConversationTurns(entries);
+  assert.equal(turns.length, 1);
+  // the second ● is a list marker inside the answer — kept as rendered
+  assert.equal(turns[0].assistant, 'item one\n● item two');
+});
+
+test('U5 buildClaudeTranscript: every line valid JSON, schema-faithful type sequence', () => {
+  const sessionId = '11111111-2222-3333-4444-555555555555';
+  const content = buildClaudeTranscript({
+    sessionId,
+    cwd: 'D:\\MyFile\\sample',
+    turns: [{ user: PROMPT_A, assistant: 'plum' }],
+  });
+  const lines = content.trim().split('\n').map((line) => JSON.parse(line));
+  assert.deepEqual(
+    lines.map((line) => line.type),
+    ['last-prompt', 'mode', 'permission-mode', 'user', 'assistant', 'last-prompt', 'mode', 'permission-mode', 'last-prompt'],
+  );
+  for (const line of lines) {
+    if (line.sessionId !== undefined) assert.equal(line.sessionId, sessionId);
+    if (line.session_id !== undefined) assert.equal(line.session_id, sessionId);
+    assert.notEqual(JSON.stringify(line).includes('undefined'), true);
+  }
+  const userLine = lines.find((line) => line.type === 'user');
+  const assistantLine = lines.find((line) => line.type === 'assistant');
+  assert.equal(userLine.message.content, PROMPT_A);
+  assert.equal(assistantLine.message.content[0].text, 'plum');
+  const finalLine = lines[lines.length - 1];
+  assert.equal(finalLine.lastPrompt, PROMPT_A);
+});
+
+test('U6 materializeClaudeTranscript writes into the encoded project dir', () => {
+  const home = makeHarnessTempRoot('claude-mat-');
+  const sessionId = 'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee';
+  try {
+    const result = materializeClaudeTranscript({
+      home,
+      cwd: 'D:\\MyFile\\sample',
+      sessionId,
+      entries: singleTurnEntries(),
+    });
+    assert.ok(result);
+    assert.equal(result.turns, 1);
+    const expectedPath = path.join(home, '.claude', 'projects', 'D--MyFile-sample', `${sessionId}.jsonl`);
+    assert.equal(result.path, expectedPath);
+    assert.equal(result.bytes, fs.statSync(expectedPath).size);
+    // uuids/timestamps are per-build, so compare structure + content, not bytes
+    const onDisk = fs.readFileSync(expectedPath, 'utf8').trim().split('\n').map((line) => JSON.parse(line));
+    assert.deepEqual(
+      onDisk.map((line) => line.type),
+      ['last-prompt', 'mode', 'permission-mode', 'user', 'assistant', 'last-prompt', 'mode', 'permission-mode', 'last-prompt'],
+    );
+    for (const line of onDisk) {
+      if (line.sessionId !== undefined) assert.equal(line.sessionId, sessionId);
+      if (line.session_id !== undefined) assert.equal(line.session_id, sessionId);
+    }
+    assert.equal(onDisk.find((line) => line.type === 'user').message.content, PROMPT_A);
+    assert.equal(onDisk.find((line) => line.type === 'assistant').message.content[0].text, 'plum');
+    assert.equal(onDisk[onDisk.length - 1].lastPrompt, PROMPT_A);
+  } finally {
+    fs.rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test('U7 no turns: materialize returns null and writes nothing', () => {
+  const home = makeHarnessTempRoot('claude-mat-');
+  try {
+    const result = materializeClaudeTranscript({
+      home,
+      cwd: 'D:\\MyFile\\sample',
+      sessionId: 'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee',
+      entries: [entry('stdin', 'R'), entry('stdout', 'boot banner')],
+    });
+    assert.equal(result, null);
+    assert.equal(fs.existsSync(path.join(home, '.claude')), false);
+  } finally {
+    fs.rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test('U12 a "❯" inside the answer (quoted shell prompt) is preserved, not a turn-over', () => {
+  const entries = [
+    ...typePrompt(PROMPT_A),
+    entry('stdout', ansi('●Try: ❯ npm run dev, or check the docs✻Baked for 4s❯ ')),
+  ];
+  const turns = extractConversationTurns(entries);
+  assert.equal(turns.length, 1);
+  assert.equal(turns[0].assistant, 'Try: ❯ npm run dev, or check the docs');
+});
+
+test('U13 ready marker without verb tail: next prompt input closes the turn', () => {
+  const entries = [
+    ...typePrompt(PROMPT_A),
+    entry('stdout', ansi('●done❯ ')), // ready "❯" but no "✻Verb for Xs" tail
+    ...typePrompt(PROMPT_B),
+    entry('stdout', REPLY_B),
+  ];
+  const turns = extractConversationTurns(entries);
+  assert.equal(turns.length, 2);
+  assert.deepEqual(turns[0], { user: PROMPT_A, assistant: 'done' });
+  assert.deepEqual(turns[1], { user: PROMPT_B, assistant: 'plum' });
+});
+
+test('U9 encodeClaudeProjectDir matches the real claude encoding', () => {
+  assert.equal(
+    encodeClaudeProjectDir('D:\\MyFile\\sample\\synchronous-github\\zingspark\\create-harness-vibe-coding'),
+    'D--MyFile-sample-synchronous-github-zingspark-create-harness-vibe-coding',
+  );
+});

package/src/wf-ui-server/__tests__/workflow-cli-registry-manuals.test.mjs

@@ -0,0 +1,173 @@
+// CLI shared-action-registry + manuals tests (wf-ui-control.mjs).
+//
+// Proves two CLI surface additions:
+//  1. `help --json` merges the shared action registry
+//     (Harness/a2a/action-registry.json) into its machine-readable output as
+//     an `actions` array, and sets `actionsFallback: true` (no `actions` key)
+//     when the registry file is absent from the project.
+//  2. `manuals <nodeType>` prints the node manual JSON plus generated
+//     `id — summary` command lines derived from the registry, and
+//     `manuals --list` enumerates the valid manual types.
+// T6 asserts the template mirror of the CLI stays byte-identical.
+import { describe, it, before, after } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { makeHarnessTempRoot } from '../../../tests/support/temp-root.js';
+
+const REPO_ROOT = process.cwd();
+
+// Spawn a real `node Harness/scripts/wf-ui-control.mjs <command>` process.
+// Resolves with { status, stdout, stderr }; stdout is the parsed JSON object
+// when the CLI printed JSON, otherwise the raw string.
+function runWfUi(args, { cwd, env = {}, timeout = 15000 } = {}) {
+  return new Promise((resolve, reject) => {
+    const script = path.join(cwd, 'Harness', 'scripts', 'wf-ui-control.mjs');
+    const child = spawn(process.execPath, [script, ...args], {
+      cwd,
+      env: { ...process.env, ...env },
+      windowsHide: true,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    let stdout = '';
+    let stderr = '';
+    const timer = setTimeout(() => {
+      child.kill();
+      reject(new Error(`wf-ui-control timeout: ${args.join(' ')}`));
+    }, timeout);
+    child.stdout.on('data', (chunk) => { stdout += chunk; });
+    child.stderr.on('data', (chunk) => { stderr += chunk; });
+    child.on('error', reject);
+    child.on('close', (status) => {
+      clearTimeout(timer);
+      let parsed = stdout.trim();
+      try {
+        parsed = JSON.parse(parsed);
+      } catch {
+        // Non-JSON output (e.g. help text) is left as the raw string.
+      }
+      resolve({ status, stdout: parsed, stderr });
+    });
+  });
+}
+
+// ── Fixtures ────────────────────────────────────────────────────────────────
+
+let tempRoot;
+
+// Temp project without a Harness/a2a/action-registry.json (used by T2 to
+// prove the actionsFallback marker).
+before(() => {
+  tempRoot = makeHarnessTempRoot('wf-cli-registry-manuals-');
+});
+
+after(() => {
+  if (!tempRoot) return;
+  const resolved = path.resolve(tempRoot);
+  const tempRootDir = path.resolve('Harness', '.temp') + path.sep;
+  assert.ok(resolved.startsWith(tempRootDir), `refusing to remove non-temp root: ${resolved}`);
+  try {
+    fs.rmSync(resolved, { recursive: true, force: true, maxRetries: 25, retryDelay: 200 });
+  } catch (e) {
+    // Windows may briefly hold session files after server close; tolerate.
+    if (process.platform === 'win32' && ['EPERM', 'EBUSY', 'ENOTEMPTY'].includes(e?.code)) return;
+    throw e;
+  }
+});
+
+// ── T1: help --json merges the shared action registry ───────────────────────
+
+describe('help --json merges the shared action registry', () => {
+  it('T1: includes the actions array with agent.sendMessage mapped to its CLI command', async () => {
+    const result = await runWfUi(['help', '--json'], { cwd: REPO_ROOT });
+    assert.equal(result.status, 0, `help --json failed: ${result.stderr}`);
+    assert.ok(result.stdout && typeof result.stdout === 'object', `non-JSON stdout: ${result.stdout}`);
+    assert.ok(Array.isArray(result.stdout.commands), 'must return a commands array');
+    assert.ok(Array.isArray(result.stdout.actions), 'must return an actions array from the shared registry');
+    assert.ok(!('actionsFallback' in result.stdout), 'must not set actionsFallback when the registry is present');
+
+    const sendMessage = result.stdout.actions.find(action => action.id === 'agent.sendMessage');
+    assert.ok(sendMessage, `actions must include agent.sendMessage: ${result.stdout.actions.map(a => a.id).join(', ')}`);
+    assert.equal(sendMessage.command, 'send-agent-message');
+    assert.ok(typeof sendMessage.summary === 'string' && sendMessage.summary.length > 0, 'entry must carry a summary');
+    assert.ok(Array.isArray(sendMessage.flags), 'entry must carry a flags array');
+  });
+});
+
+// ── T2: help --json without a registry file ─────────────────────────────────
+
+describe('help --json without a registry file', () => {
+  it('T2: marks actionsFallback and omits the actions key', async () => {
+    const result = await runWfUi(['help', '--json', '--project', tempRoot], { cwd: REPO_ROOT });
+    assert.equal(result.status, 0, `help --json --project failed: ${result.stderr}`);
+    assert.equal(result.stdout.actionsFallback, true, 'must set actionsFallback when the registry is missing');
+    assert.ok(!('actions' in result.stdout), 'must omit the actions key when the registry is missing');
+    assert.ok(Array.isArray(result.stdout.commands), 'commands must still be present');
+  });
+});
+
+// ── T3/T4/T5: manuals command ───────────────────────────────────────────────
+
+describe('manuals command', () => {
+  it('T3: prints the timer manual and generated command lines', async () => {
+    const result = await runWfUi(['manuals', 'timer'], { cwd: REPO_ROOT });
+    assert.equal(result.status, 0, `manuals timer failed: ${result.stderr}`);
+    assert.ok(result.stdout && typeof result.stdout === 'object', `non-JSON stdout: ${result.stdout}`);
+    assert.equal(result.stdout.type, 'timer');
+    assert.ok(result.stdout.manual && typeof result.stdout.manual === 'object', 'must carry the full manual');
+    assert.match(String(result.stdout.manual.description || ''), /Timer nodes/i, 'must carry the timer manual description');
+    assert.ok(Array.isArray(result.stdout.commands), 'must carry a generated commands array');
+    assert.ok(
+      result.stdout.commands.some(line => line.startsWith('timer.read —')),
+      'commands must include a timer.read line',
+    );
+    assert.ok(
+      result.stdout.commands.some(line => line.startsWith('timer.configure —')),
+      'commands must include a timer.configure line',
+    );
+  });
+
+  it('T3b: excalidraw resolves to the diagram manual with excalidraw action lines', async () => {
+    const result = await runWfUi(['manuals', 'excalidraw'], { cwd: REPO_ROOT });
+    assert.equal(result.status, 0, `manuals excalidraw failed: ${result.stderr}`);
+    assert.equal(result.stdout.type, 'diagram', 'excalidraw must resolve to the diagram manual type');
+    assert.match(String(result.stdout.manual.description || ''), /Diagram nodes/i, 'must carry the diagram manual description');
+    assert.ok(
+      result.stdout.commands.some(line => line.startsWith('excalidraw.readScene —')),
+      'commands must include excalidraw action lines for the alias',
+    );
+  });
+
+  it('T4: --list enumerates all manual types including the diagram alias', async () => {
+    const result = await runWfUi(['manuals', '--list'], { cwd: REPO_ROOT });
+    assert.equal(result.status, 0, `manuals --list failed: ${result.stderr}`);
+    assert.ok(Array.isArray(result.stdout.types), 'must return a types array');
+    for (const type of ['agent', 'markdown', 'excalidraw', 'file', 'timer', 'goal', 'skill-group', 'mcp-connector', 'github-trigger', 'diagram']) {
+      assert.ok(result.stdout.types.includes(type), `types must include ${type}`);
+    }
+    assert.deepEqual(result.stdout.alias, { excalidraw: 'diagram' });
+  });
+
+  it('T5: unknown type fails with a valid-types list and non-zero exit', async () => {
+    const result = await runWfUi(['manuals', 'unknown-type'], { cwd: REPO_ROOT });
+    assert.notEqual(result.status, 0, 'must exit non-zero for an unknown type');
+    assert.match(
+      result.stderr,
+      /Valid types: agent\|markdown\|excalidraw\|file\|display\|timer\|goal\|skill-group\|mcp-connector\|github-trigger\|diagram/,
+    );
+  });
+});
+
+// ── T6: template mirror parity ──────────────────────────────────────────────
+
+describe('template mirror parity', () => {
+  it('T6: the CLI file and its template mirror are byte-identical', () => {
+    const cli = fs.readFileSync(path.join(REPO_ROOT, 'Harness', 'scripts', 'wf-ui-control.mjs'));
+    const mirror = fs.readFileSync(path.join(REPO_ROOT, 'templates', 'common', 'Harness', 'scripts', 'wf-ui-control.mjs'));
+    assert.ok(
+      cli.equals(mirror),
+      'Harness/scripts/wf-ui-control.mjs and templates/common/Harness/scripts/wf-ui-control.mjs must be byte-identical',
+    );
+  });
+});

package/src/wf-ui-server/__tests__/workflow-cli-surface.test.mjs

@@ -0,0 +1,176 @@
+// Workflow CLI surface tests (wf-ui-control.mjs).
+//
+// Proves the machine-readable command registry (`help --json`) and the
+// send-key keystroke primitive. Each test spawns a genuine
+// `node Harness/scripts/wf-ui-control.mjs <command>` subprocess against a
+// copied CLI script, so it exercises exactly what an Agent node would run.
+// Help/registry tests need no backend; send-key posts to a local recording
+// HTTP server that captures the request bodies.
+import { describe, it, before, after } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import http from 'node:http';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { makeHarnessTempRoot } from '../../../tests/support/temp-root.js';
+
+// ── CLI runner ──────────────────────────────────────────────────────────────
+
+// Spawn a real `node Harness/scripts/wf-ui-control.mjs <command>` process.
+// Resolves with { status, stdout, stderr }; stdout is the parsed JSON object
+// when the CLI printed JSON, otherwise the raw string (e.g. help text).
+function runWfUi(args, { cwd, env = {}, timeout = 15000 } = {}) {
+  return new Promise((resolve, reject) => {
+    const script = path.join(cwd, 'Harness', 'scripts', 'wf-ui-control.mjs');
+    const child = spawn(process.execPath, [script, ...args], {
+      cwd,
+      env: { ...process.env, ...env },
+      windowsHide: true,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    let stdout = '';
+    let stderr = '';
+    const timer = setTimeout(() => {
+      child.kill();
+      reject(new Error(`wf-ui-control timeout: ${args.join(' ')}`));
+    }, timeout);
+    child.stdout.on('data', (chunk) => { stdout += chunk; });
+    child.stderr.on('data', (chunk) => { stderr += chunk; });
+    child.on('error', reject);
+    child.on('close', (status) => {
+      clearTimeout(timer);
+      let parsed = stdout.trim();
+      try {
+        parsed = JSON.parse(parsed);
+      } catch {
+        // Non-JSON output (e.g. help text) is left as the raw string.
+      }
+      resolve({ status, stdout: parsed, stderr });
+    });
+  });
+}
+
+// ── Fixtures ────────────────────────────────────────────────────────────────
+
+let tempRoot;
+
+// Identity environment every spawned Agent CLI runs with: the actor is a
+// Main Agent node, so the CLI main-agent gates (assertMainAgent) pass.
+const AGENT_ENV = { HARNESS_AGENT_KIND: 'main' };
+
+before(() => {
+  tempRoot = makeHarnessTempRoot('wf-cli-surface-');
+  const dest = path.join(tempRoot, 'Harness', 'scripts', 'wf-ui-control.mjs');
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  fs.copyFileSync(path.join(process.cwd(), 'Harness', 'scripts', 'wf-ui-control.mjs'), dest);
+});
+
+after(() => {
+  if (!tempRoot) return;
+  const resolved = path.resolve(tempRoot);
+  const tempRootDir = path.resolve('Harness', '.temp') + path.sep;
+  assert.ok(resolved.startsWith(tempRootDir), `refusing to remove non-temp root: ${resolved}`);
+  try {
+    fs.rmSync(resolved, { recursive: true, force: true, maxRetries: 25, retryDelay: 200 });
+  } catch (e) {
+    // Windows may briefly hold session files after server close; tolerate.
+    if (process.platform === 'win32' && ['EPERM', 'EBUSY', 'ENOTEMPTY'].includes(e?.code)) return;
+    throw e;
+  }
+});
+
+// ── T1: help --json dumps the full machine-readable registry ───────────────
+
+describe('help --json registry', () => {
+  it('prints a valid JSON registry with the core commands and their flags', async () => {
+    const result = await runWfUi(['help', '--json'], { cwd: tempRoot });
+    assert.equal(result.status, 0, `help --json failed: ${result.stderr}`);
+    assert.ok(result.stdout && typeof result.stdout === 'object', `non-JSON stdout: ${result.stdout}`);
+    assert.ok(Array.isArray(result.stdout.commands), 'must return a commands array');
+
+    const byName = new Map(result.stdout.commands.map(entry => [entry.name, entry]));
+    for (const required of ['create-agent', 'send-input', 'send-agent-message', 'send-key']) {
+      const entry = byName.get(required);
+      assert.ok(entry, `commands must include ${required}: ${result.stdout.commands.map(c => c.name).join(', ')}`);
+      assert.ok(typeof entry.summary === 'string' && entry.summary.length > 0, `${required} must carry a summary`);
+      assert.ok(Array.isArray(entry.aliases), `${required} must carry an aliases array`);
+      assert.ok(Array.isArray(entry.flags), `${required} must carry a flags array`);
+    }
+
+    const createAgent = byName.get('create-agent');
+    assert.ok(
+      createAgent.flags.some(flag => flag.flag === 'initial-prompt'),
+      'create-agent must list the initial-prompt flag',
+    );
+  });
+});
+
+// ── T2: help <command> --json prints one command entry ─────────────────────
+
+describe('help <command> --json', () => {
+  it('prints a single command entry with flags', async () => {
+    const result = await runWfUi(['help', 'send-input', '--json'], { cwd: tempRoot });
+    assert.equal(result.status, 0, `help send-input --json failed: ${result.stderr}`);
+    assert.equal(result.stdout.name, 'send-input');
+    assert.ok(typeof result.stdout.summary === 'string' && result.stdout.summary.length > 0, 'entry must carry a summary');
+    assert.ok(Array.isArray(result.stdout.flags), 'entry must carry flags');
+    assert.ok(result.stdout.flags.some(flag => flag.flag === 'session'), 'send-input must list the session flag');
+    assert.ok(result.stdout.flags.some(flag => flag.flag === 'text'), 'send-input must list the text flag');
+  });
+});
+
+// ── T3: plain-text help parity (no regression) ──────────────────────────────
+
+describe('plain help parity', () => {
+  it('create-agent --help still lists --initial-prompt', async () => {
+    const result = await runWfUi(['create-agent', '--help'], { cwd: tempRoot });
+    assert.equal(result.status, 0, `create-agent --help failed: ${result.stderr}`);
+    const text = String(result.stdout);
+    assert.match(text, /Usage: wf-ui-control\.mjs create-agent \[flags\]/);
+    assert.match(text, /--initial-prompt/, 'create-agent help must still show --initial-prompt');
+  });
+});
+
+// ── T4: send-key keystroke primitive ───────────────────────────────────────
+
+describe('send-key keystroke primitive', () => {
+  it('maps named keys to raw bytes posted to the session input endpoint', async () => {
+    const requests = [];
+    const server = http.createServer((req, res) => {
+      let raw = '';
+      req.on('data', (chunk) => { raw += chunk; });
+      req.on('end', () => {
+        let body = null;
+        try { body = raw ? JSON.parse(raw) : null; } catch { /* record raw */ }
+        requests.push({ method: req.method, url: req.url, body });
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end('{"ok":true}');
+      });
+    });
+    await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
+    const baseUrl = `http://127.0.0.1:${server.address().port}`;
+    const expectMap = {
+      up: '\x1b[A',
+      down: '\x1b[B',
+      enter: '\r',
+      esc: '\x1b',
+      backspace: '\x7f',
+    };
+    try {
+      for (const [key, expected] of Object.entries(expectMap)) {
+        const result = await runWfUi(
+          ['send-key', key, '--session', 'sess-live-1', '--url', baseUrl],
+          { cwd: tempRoot, env: AGENT_ENV },
+        );
+        assert.equal(result.status, 0, `send-key ${key} failed: ${result.stderr}`);
+        const last = requests[requests.length - 1];
+        assert.equal(last.method, 'POST', `${key}: must POST to the input endpoint`);
+        assert.equal(last.url, '/api/sessions/sess-live-1/input', `${key}: must target the session input endpoint`);
+        assert.equal(last.body.data, expected, `${key}: raw data bytes must match the terminal mapping`);
+        assert.equal(last.body.raw, true, `${key}: raw flag must be true`);
+      }
+    } finally {
+      await new Promise((resolve) => server.close(resolve));
+    }
+  });
+});