yaml-flow 8.5.3 → 8.6.2

package/examples/board/test/server-http-test.js

@@ -34,6 +34,8 @@ const cliPort = portArg !== -1 ? parseInt(cliArgs[portArg + 1], 10) : NaN;
 const skipT1 = cliArgs.includes('--skip-t1');
 const skipT2 = cliArgs.includes('--skip-t2');
 const skipT3 = cliArgs.includes('--skip-t3');
+const skipT4 = cliArgs.includes('--skip-t4');
+const skipT5 = cliArgs.includes('--skip-t5');
 function isCopilotAvailable() {
   try {
     const r = spawnSync('copilot', ['--version'], { timeout: 5_000, stdio: 'ignore', windowsHide: true });
@@ -94,6 +96,7 @@ const NS = {
   statusGeneration: 0,
   computedValues: {},
   chatEvents: [],
+  boardEvents: [],
 };
 
 function applyFrame(payload) {
@@ -126,6 +129,9 @@ function applyFrame(payload) {
       if (n && n.kind === 'computed_values' && n.cardId) {
         NS.computedValues[n.cardId] = n.values;
       }
+      if (n && (n.kind === 'card_removed' || n.kind === 'card_refreshed') && n.cardId) {
+        NS.boardEvents.push({ kind: n.kind, cardId: n.cardId, at: Date.now() });
+      }
     }
   }
 }
@@ -200,6 +206,10 @@ function assert(condition, message) {
   }
 }
 
+function randomTurnId() {
+  return String(Math.floor(100000 + Math.random() * 900000));
+}
+
 function waitUntil(predicate, timeoutMs, label) {
   return new Promise((resolve, reject) => {
     const deadline = Date.now() + timeoutMs;
@@ -219,6 +229,43 @@ function waitUntil(predicate, timeoutMs, label) {
   });
 }
 
+function wait(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function stopChildProcess(proc, label) {
+  if (!proc) return;
+  if (proc.exitCode !== null) return;
+
+  const exitPromise = new Promise((resolve) => {
+    proc.once('exit', (code, signal) => resolve({ code, signal }));
+  });
+
+  try {
+    proc.kill();
+  } catch {
+    return;
+  }
+
+  const gracefulExit = await Promise.race([
+    exitPromise,
+    wait(5_000).then(() => null),
+  ]);
+  if (gracefulExit) return;
+
+  if (proc.exitCode === null) {
+    try { proc.kill('SIGKILL'); } catch { /* ignore */ }
+  }
+
+  const forcedExit = await Promise.race([
+    exitPromise,
+    wait(5_000).then(() => null),
+  ]);
+  if (!forcedExit && proc.exitCode === null) {
+    throw new Error(`${label} did not exit after kill()`);
+  }
+}
+
 const waitForInitialPayload = (ms = 15_000) =>
   waitUntil(() => NS.initialPayload || false, ms, 'initial SSE payload');
 
@@ -330,6 +377,45 @@ function httpJson(method, url, payload) {
   });
 }
 
+function httpMcp(tool, args) {
+  return httpJson('POST', `${BASE}/mcp`, { tool, args });
+}
+
+function httpMcpControlplane(tool, args) {
+  return httpJson('POST', `${BASE}/mcp-controlplane`, { tool, args });
+}
+
+function httpMcpRaw(tool, args) {
+  return new Promise((resolve, reject) => {
+    const u = new URL(`${BASE}/mcp-raw`);
+    const data = JSON.stringify({ tool, args });
+    const opts = {
+      hostname: u.hostname,
+      port: u.port,
+      path: u.pathname,
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Content-Length': Buffer.byteLength(data),
+      },
+    };
+    const req = http.request(opts, (res) => {
+      const chunks = [];
+      res.on('data', c => { chunks.push(Buffer.isBuffer(c) ? c : Buffer.from(c)); });
+      res.on('end', () => {
+        resolve({
+          status: res.statusCode,
+          body: Buffer.concat(chunks),
+          headers: res.headers,
+        });
+      });
+    });
+    req.on('error', reject);
+    req.write(data);
+    req.end();
+  });
+}
+
 function httpUploadChatFile(url, fileName, content, contentType = 'text/plain; charset=utf-8') {
   return new Promise((resolve, reject) => {
     const u = new URL(url);
@@ -359,6 +445,16 @@ function httpUploadChatFile(url, fileName, content, contentType = 'text/plain; c
   });
 }
 
+function deepCloneJson(value) {
+  return JSON.parse(JSON.stringify(value));
+}
+
+function expectMcpSuccess(httpResult, label) {
+  assert(httpResult.status === 200, `${label} returned ${httpResult.status}`);
+  assert(httpResult.data?.status === 'success', `${label} expected status=success, got ${JSON.stringify(httpResult.data)}`);
+  return httpResult.data.data;
+}
+
 function startServer(port) {
   return new Promise((resolve, reject) => {
     const proc = spawn(process.execPath, [SERVER_SCRIPT], {
@@ -370,6 +466,7 @@ function startServer(port) {
         DEMO_SETUP_DIR: SETUP_DIR,
         DEMO_BOARD_SETUP_ROOT: BOARD_SETUP_ROOT,
         DEMO_CARDS_PATTERN: CARD_PATTERN,
+        BOARD_SERVER_ENABLE_TEST_REQ: '1',
       },
     });
     let ready = false;
@@ -388,9 +485,10 @@ function startServer(port) {
       if (!ready) reject(new Error(`Server exited early: code ${code}`));
     });
 
-    setTimeout(() => {
+    const startupTimer = setTimeout(() => {
       if (!ready) reject(new Error('Server startup timeout (15s)'));
     }, 15_000);
+    startupTimer.unref?.();
   });
 }
 
@@ -449,6 +547,16 @@ try {
   assert(statusRes.status === 200, `board-status returned ${statusRes.status}`);
   const httpSummary = statusRes.data?.statusSnapshot?.summary;
   assert(httpSummary, 'statusSnapshot.summary missing from board-status');
+  const statusMcpRes = await httpMcp('inspect.board-runtime-status', {});
+  assert(statusMcpRes.status === 200, `inspect.board-runtime-status returned ${statusMcpRes.status}`);
+  assert(statusMcpRes.data?.status === 'success', `inspect.board-runtime-status failed: ${JSON.stringify(statusMcpRes.data)}`);
+  const mcpSummary = statusMcpRes.data?.data?.summary;
+  assert(mcpSummary, 'summary missing from inspect.board-runtime-status');
+  const comparableStatusKeys = ['card_count', 'completed', 'eligible', 'pending', 'blocked', 'in_progress', 'failed', 'unresolved'];
+  const httpComparableSummary = Object.fromEntries(comparableStatusKeys.map((key) => [key, httpSummary[key]]));
+  const mcpComparableSummary = Object.fromEntries(comparableStatusKeys.map((key) => [key, mcpSummary[key]]));
+  assert(JSON.stringify(httpComparableSummary) === JSON.stringify(mcpComparableSummary),
+    `HTTP board-status summary mismatch vs MCP summary: http=${JSON.stringify(httpComparableSummary)} mcp=${JSON.stringify(mcpComparableSummary)}`);
   assert(httpSummary.completed === httpSummary.card_count, `not all complete: ${JSON.stringify(httpSummary)}`);
   console.log(`[T0.4] board-status: ${JSON.stringify(httpSummary)}`);
 
@@ -461,12 +569,14 @@ try {
   if (skipT1) {
     console.log('\n=== T1: skipped (--skip-t1) ===');
   } else {
-    console.log('\n=== T1: patch holdings (+1 row) ===');
-
-  // Read current holdings from card store
-  const portfolioCardRes = await httpGet(`${BASE}/cards/card-portfolio`);
-  assert(portfolioCardRes.status === 200, `GET card-portfolio returned ${portfolioCardRes.status}`);
-  const existingHoldings = portfolioCardRes.data?.card_data?.holdings;
+    console.log('\n=== T1: local mutation + manage.upsert-card (+1 row) ===');
+
+  // Read the live card document via inspect.card-definition-and-runtime before preparing the upsert payload.
+  const portfolioCardRes = await httpMcp('inspect.card-definition-and-runtime', { card_id: 'card-portfolio' });
+  assert(portfolioCardRes.status === 200, `inspect.card-definition-and-runtime returned ${portfolioCardRes.status}`);
+  assert(portfolioCardRes.data?.status === 'success', `inspect.card-definition-and-runtime failed: ${JSON.stringify(portfolioCardRes.data)}`);
+  const existingCard = portfolioCardRes.data?.data?.card_definition_and_static_data ?? null;
+  const existingHoldings = existingCard?.card_data?.holdings;
   assert(Array.isArray(existingHoldings), 'card-portfolio.card_data.holdings missing');
   const t0HoldingsCount = existingHoldings.length;
   const t0PositionsCount = t0Positions.length;
@@ -480,19 +590,31 @@ try {
   const newTicker = available[0];
 
   const newHoldings = [...existingHoldings, { ticker: newTicker, quantity: 1, cost_basis: 100 }];
-  const patchRes = await httpJson('PATCH', `${BASE}/cards/card-portfolio`, { card_data: { holdings: newHoldings } });
-  assert(patchRes.status === 200, `PATCH card-portfolio returned ${patchRes.status}`);
+  const nextCard = {
+    ...existingCard,
+    card_data: {
+      ...(existingCard?.card_data || {}),
+      holdings: newHoldings,
+    },
+  };
+  const upsertRes = await httpMcp('manage.upsert-card', {
+    card_id: 'card-portfolio',
+    candidate_card_content: nextCard,
+  });
+  assert(upsertRes.status === 200, `manage.upsert-card returned ${upsertRes.status}`);
+  assert(upsertRes.data?.status === 'success', `manage.upsert-card failed: ${JSON.stringify(upsertRes.data)}`);
 
-  // Wait for re-completion after the patch triggers a new cycle
+  // Wait for re-completion after the upsert triggers a new cycle
   NS.statusSummary = null;
   await new Promise(r => setTimeout(r, 4000));
-  const t1Summary = await waitForAllCompleted(30_000, 'T1 holdings patch');
+  const t1Summary = await waitForAllCompleted(30_000, 'T1 holdings upsert');
   assert(t1Summary.failed === 0, `T1 failed=${t1Summary.failed}`);
 
-  // Verify holdings +1 from card store
-  const t1PortfolioRes = await httpGet(`${BASE}/cards/card-portfolio`);
-  assert(t1PortfolioRes.status === 200, `GET card-portfolio after patch returned ${t1PortfolioRes.status}`);
-  const afterHoldings = t1PortfolioRes.data?.card_data?.holdings;
+  // Verify holdings +1 from the live card document after upsert.
+  const t1PortfolioRes = await httpMcp('inspect.card-definition-and-runtime', { card_id: 'card-portfolio' });
+  assert(t1PortfolioRes.status === 200, `inspect.card-definition-and-runtime after upsert returned ${t1PortfolioRes.status}`);
+  assert(t1PortfolioRes.data?.status === 'success', `inspect.card-definition-and-runtime after upsert failed: ${JSON.stringify(t1PortfolioRes.data)}`);
+  const afterHoldings = t1PortfolioRes.data?.data?.card_definition_and_static_data?.card_data?.holdings;
   const afterHoldingsCount = Array.isArray(afterHoldings) ? afterHoldings.length : 0;
 
   // Verify positions +1 from computed_values captured via SSE
@@ -548,6 +670,48 @@ try {
     const t2DownloadedText = t2DownloadRes.body.toString('utf-8');
     assert(t2DownloadedText === t2UploadText, 'T2 downloaded content mismatch');
     console.log('[T2] ok: card_data.files updated and file download endpoint returned exact bytes');
+
+    console.log('\n=== T2a: MCP controlplane file upload -> MCP raw file download ===');
+    const t2aCardBefore = await httpMcp('manage.read-card', { card_id: T2_FILE_CARD_ID });
+    assert(t2aCardBefore.status === 200, `T2a pre card read returned ${t2aCardBefore.status}`);
+    assert(t2aCardBefore.data?.status === 'success', `T2a pre card read failed: ${JSON.stringify(t2aCardBefore.data)}`);
+    const t2aCardBeforeObj = Array.isArray(t2aCardBefore.data?.data) ? t2aCardBefore.data.data[0] : null;
+    const t2aFilesBefore = Array.isArray(t2aCardBeforeObj?.card_data?.files) ? t2aCardBeforeObj.card_data.files : [];
+    const t2aBeforeCount = t2aFilesBefore.length;
+
+    const t2aUploadText = `mcp-file-upload-${Date.now()}`;
+    const t2aUploadName = 't2a-upload.txt';
+    const t2aUploadRes = await httpMcpControlplane('manage.upload-card-file', {
+      board_id: BOARD_ID,
+      card_id: T2_FILE_CARD_ID,
+      file_name: t2aUploadName,
+      content_type: 'text/plain; charset=utf-8',
+      text: t2aUploadText,
+    });
+    assert(t2aUploadRes.status === 200, `T2a file upload returned ${t2aUploadRes.status}`);
+    assert(t2aUploadRes.data?.status === 'success', `T2a file upload failed: ${JSON.stringify(t2aUploadRes.data)}`);
+    const t2aUploadedFile = t2aUploadRes.data?.data?.file;
+    assert(t2aUploadedFile && typeof t2aUploadedFile === 'object', 'T2a upload response missing file metadata');
+    assert(String(t2aUploadedFile?.name || '') === t2aUploadName, 'T2a uploaded file name mismatch');
+
+    const t2aCardAfter = await httpMcp('manage.read-card', { card_id: T2_FILE_CARD_ID });
+    assert(t2aCardAfter.status === 200, `T2a post card read returned ${t2aCardAfter.status}`);
+    assert(t2aCardAfter.data?.status === 'success', `T2a post card read failed: ${JSON.stringify(t2aCardAfter.data)}`);
+    const t2aCardAfterObj = Array.isArray(t2aCardAfter.data?.data) ? t2aCardAfter.data.data[0] : null;
+    const t2aFilesAfter = Array.isArray(t2aCardAfterObj?.card_data?.files) ? t2aCardAfterObj.card_data.files : [];
+    assert(t2aFilesAfter.length === t2aBeforeCount + 1, `T2a expected files +1 (before=${t2aBeforeCount}, after=${t2aFilesAfter.length})`);
+
+    const t2aFileIndex = t2aFilesAfter.findIndex((f) => String(f?.stored_name || '') === String(t2aUploadedFile?.stored_name || ''));
+    assert(t2aFileIndex >= 0, 'T2a uploaded file metadata not found in card_data.files');
+
+    const t2aDownloadRes = await httpMcpRaw('inspect.file-contents', {
+      card_id: T2_FILE_CARD_ID,
+      file_idx: t2aFileIndex,
+    });
+    assert(t2aDownloadRes.status === 200, `T2a file download returned ${t2aDownloadRes.status}`);
+    const t2aDownloadedText = t2aDownloadRes.body.toString('utf-8');
+    assert(t2aDownloadedText === t2aUploadText, 'T2a downloaded content mismatch');
+    console.log('[T2a] ok: mcp-controlplane upload and mcp-raw download returned exact bytes');
   }
 
   // ── T3*: chat protocol over API + SSE ──
@@ -555,55 +719,90 @@ try {
     if (skipT3) {
       console.log('\n=== T3: skipped (--skip-t3) ===');
     } else {
-    console.log(`\n[${new Date().toISOString()}] === T3: probe chat protocol (SSE lifecycle) ===`);
-  chatSseClientId = `chat-proto-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
-  chatSseClient = startSseClient(`${BASE}/sse?clientId=${encodeURIComponent(chatSseClientId)}`, (payload) => {
-    captureChatEvents(payload, CHAT_CARD_ID);
-  });
-  await new Promise((r) => setTimeout(r, 400));
-
-  const subRes = await httpJson('POST', `${BASE}/cards/${CHAT_CARD_ID}/chats/subscribe-sse`, { clientId: chatSseClientId });
-  assert(subRes.status === 200, `chat subscribe returned ${subRes.status}`);
-
-  const t2Before = await httpGet(`${BASE}/cards/${CHAT_CARD_ID}/chats?all-turns=true`);
-  assert(t2Before.status === 200, `T3 pre chats returned ${t2Before.status}`);
-  const t2BeforeMessages = Array.isArray(t2Before.data?.messages) ? t2Before.data.messages : [];
-  const t2BeforeCount = t2BeforeMessages.length;
-  const t2EventStart = NS.chatEvents.length;
-  const t2ProbePrompt = `Probe protocol validation ${Date.now()}`;
-
-  const t2SendRes = await httpJson('POST', `${BASE}/cards/${CHAT_CARD_ID}/actions`, {
-    actionType: 'chat-send',
-    payload: {
-      text: `${ECHO_PROBE_MARKER}${t2ProbePrompt}${ECHO_PROBE_MARKER}`,
-    },
-  });
-  assert(t2SendRes.status === 200, `T3 chat-send returned ${t2SendRes.status}`);
-
-  const t2Lifecycle = await waitForChatPredicate((events) => {
-    return matchOrderedProbeLifecycle(events.slice(t2EventStart), {
-      beforeCount: t2BeforeCount,
-      beforeProcessing: false,
-      prompt: t2ProbePrompt,
-      inProgressText: PROBE_IN_PROGRESS_TEXT,
-    });
-  }, 45_000, 'T3 ordered lifecycle');
-  assert(!!t2Lifecycle, 'T3 ordered lifecycle not observed');
-
-  const t2After = await httpGet(`${BASE}/cards/${CHAT_CARD_ID}/chats?all-turns=true`);
-  assert(t2After.status === 200, `T3 post chats returned ${t2After.status}`);
-  const t2AfterMessages = Array.isArray(t2After.data?.messages) ? t2After.data.messages : [];
-  const t2NewMessages = t2AfterMessages.slice(t2BeforeCount);
-  assert(t2NewMessages.length >= 3, `T3 expected at least 3 new chat messages, got ${t2NewMessages.length}`);
-  const t2User = t2NewMessages.find((m) => m?.role === 'user');
-  const t2InProgress = t2NewMessages.find((m) => m?.role === 'system' && String(m?.text || '').trim().toLowerCase() === PROBE_IN_PROGRESS_TEXT);
-  const t2AssistantMsg = t2NewMessages.find((m) => m?.role === 'assistant');
-  assert(!!t2User && typeof t2User.id === 'string', 'T3 user chat message missing id');
-  assert(String(t2User?.text || '').includes(t2ProbePrompt), 'T3 user file text mismatch');
-  assert(!!t2InProgress && typeof t2InProgress.id === 'string', 'T3 in-progress system message missing id');
-  assert(!!t2AssistantMsg && typeof t2AssistantMsg.id === 'string', 'T3 assistant chat message missing id');
-  assert(String(t2AssistantMsg?.text || '').includes(`Echo: ${t2ProbePrompt}`), 'T3 assistant echo file content mismatch');
-  console.log(`[${new Date().toISOString()}] [T3] ok: ordered probe lifecycle observed (user+processing, in-progress, assistant+processing clear)`);
+      console.log(`\n[${new Date().toISOString()}] === T3: probe chat protocol (SSE lifecycle) ===`);
+      const t3Dbg = (msg) => console.log(`[T3.DBG ${new Date().toISOString()}] ${msg}`);
+      t3Dbg('step 1: creating chat SSE client');
+      chatSseClientId = `chat-proto-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+      chatSseClient = startSseClient(`${BASE}/sse?clientId=${encodeURIComponent(chatSseClientId)}`, (payload) => {
+        captureChatEvents(payload, CHAT_CARD_ID);
+      });
+      await new Promise((r) => setTimeout(r, 400));
+      t3Dbg(`step 1: chat SSE client ready (clientId=${chatSseClientId})`);
+
+      t3Dbg('step 2: subscribing chat SSE client');
+      const subRes = await httpJson('POST', `${BASE}/cards/${CHAT_CARD_ID}/chats/subscribe-sse`, { clientId: chatSseClientId });
+      t3Dbg(`step 2: subscribe returned status=${subRes.status}`);
+      assert(subRes.status === 200, `chat subscribe returned ${subRes.status}`);
+
+      t3Dbg('step 3: fetching pre-chat transcript');
+      const t2Before = await httpGet(`${BASE}/cards/${CHAT_CARD_ID}/chats?all-turns=true`);
+      t3Dbg(`step 3: pre-chat fetch returned status=${t2Before.status}`);
+      assert(t2Before.status === 200, `T3 pre chats returned ${t2Before.status}`);
+      const t2BeforeMessages = Array.isArray(t2Before.data?.messages) ? t2Before.data.messages : [];
+      const t2BeforeCount = t2BeforeMessages.length;
+      const t2EventStart = NS.chatEvents.length;
+      const t2ProbePrompt = `Probe protocol validation ${Date.now()}`;
+      t3Dbg(`step 3: beforeCount=${t2BeforeCount}, eventStart=${t2EventStart}`);
+
+      const t3TurnId = randomTurnId();
+      t3Dbg(`step 4: posting probe chat-send (turn-id=${t3TurnId})`);
+      const t2SendRes = await httpJson('POST', `${BASE}/cards/${CHAT_CARD_ID}/actions`, {
+        actionType: 'chat-send',
+        payload: {
+          text: `${ECHO_PROBE_MARKER}${t2ProbePrompt}${ECHO_PROBE_MARKER}`,
+          'turn-id': t3TurnId,
+        },
+      });
+      t3Dbg(`step 4: chat-send returned status=${t2SendRes.status}`);
+      assert(t2SendRes.status === 200, `T3 chat-send returned ${t2SendRes.status}`);
+
+      t3Dbg('step 5: waiting for ordered probe lifecycle on chat SSE');
+      const t2Lifecycle = await waitForChatPredicate((events) => {
+        return matchOrderedProbeLifecycle(events.slice(t2EventStart), {
+          beforeCount: t2BeforeCount,
+          beforeProcessing: false,
+          prompt: t2ProbePrompt,
+          inProgressText: PROBE_IN_PROGRESS_TEXT,
+        });
+      }, 45_000, 'T3 ordered lifecycle');
+      t3Dbg('step 5: ordered lifecycle observed');
+      assert(!!t2Lifecycle, 'T3 ordered lifecycle not observed');
+
+      t3Dbg('step 6: fetching post-chat transcript');
+      const t2After = await httpGet(`${BASE}/cards/${CHAT_CARD_ID}/chats?all-turns=true`);
+      t3Dbg(`step 6: post-chat fetch returned status=${t2After.status}`);
+      assert(t2After.status === 200, `T3 post chats returned ${t2After.status}`);
+      const t2AfterMessages = Array.isArray(t2After.data?.messages) ? t2After.data.messages : [];
+      const t2NewMessages = t2AfterMessages.slice(t2BeforeCount);
+      t3Dbg(`step 6: validating ${t2NewMessages.length} new messages`);
+      assert(t2NewMessages.length >= 3, `T3 expected at least 3 new chat messages, got ${t2NewMessages.length}`);
+      const t3McpAfter = await httpMcp('inspect.chat-messages-on-cards', { card_id: CHAT_CARD_ID, turn_id: t3TurnId });
+      const t3McpAfterData = expectMcpSuccess(t3McpAfter, 'T3 MCP post chats');
+      const t3TurnMessages = Array.isArray(t3McpAfterData?.messages) ? t3McpAfterData.messages : [];
+      t3Dbg(`step 6: MCP turn messages count=${t3TurnMessages.length}`);
+      assert(t3TurnMessages.length >= 3, `T3 expected at least 3 MCP messages for turn ${t3TurnId}, got ${t3TurnMessages.length}`);
+      for (const msg of t3TurnMessages) {
+        assert(String(msg?.turn || '') === t3TurnId, 'T3 MCP turn id mismatch');
+      }
+      const toComparableTurnMessage = (msg) => ({
+        id: String(msg?.id || ''),
+        role: String(msg?.role || ''),
+        text: String(msg?.text || ''),
+      });
+      const t3HttpComparable = t2NewMessages.map(toComparableTurnMessage);
+      const t3McpComparable = t3TurnMessages.map(toComparableTurnMessage);
+      assert(JSON.stringify(t3HttpComparable) === JSON.stringify(t3McpComparable),
+        `T3 HTTP /chats messages mismatch vs inspect.chat-messages-on-cards: http=${JSON.stringify(t3HttpComparable)} mcp=${JSON.stringify(t3McpComparable)}`);
+      const t2User = t2NewMessages.find((m) => m?.role === 'user');
+      const t2InProgress = t2NewMessages.find((m) => m?.role === 'system' && String(m?.text || '').trim().toLowerCase() === PROBE_IN_PROGRESS_TEXT);
+      const t2AssistantMsg = t2NewMessages.find((m) => m?.role === 'assistant');
+      assert(!!t2User && typeof t2User.id === 'string', 'T3 user chat message missing id');
+      assert(String(t2User?.text || '').includes(t2ProbePrompt), 'T3 user file text mismatch');
+      assert(!!t2InProgress && typeof t2InProgress.id === 'string', 'T3 in-progress system message missing id');
+      assert(!!t2AssistantMsg && typeof t2AssistantMsg.id === 'string', 'T3 assistant chat message missing id');
+      assert(String(t2AssistantMsg?.text || '').includes(`Echo: ${t2ProbePrompt}`), 'T3 assistant echo file content mismatch');
+      t3Dbg('step 6: all assertions passed');
+      console.log(`[${new Date().toISOString()}] [T3] ok: ordered probe lifecycle observed (user+processing, in-progress, assistant+processing clear)`);
     }
 
   // ── T3a: non-probe chat protocol over API + SSE ──
@@ -613,12 +812,18 @@ try {
     console.log('\n=== T3a: skipped (--skip-t3a) ===');
   } else {
     console.log('\n=== T3a: non-probe chat protocol (expect paris) ===');
+    const t3aDbg = (msg) => console.log(`[T3a.DBG ${new Date().toISOString()}] ${msg}`);
+    t3aDbg('step 1: fetching pre-chat transcript');
     const t2aBefore = await httpGet(`${BASE}/cards/${CHAT_CARD_ID}/chats?all-turns=true`);
+    t3aDbg(`step 1: pre-chat fetch returned status=${t2aBefore.status}`);
     assert(t2aBefore.status === 200, `T3a pre chats returned ${t2aBefore.status}`);
     const t2aBeforeMessages = Array.isArray(t2aBefore.data?.messages) ? t2aBefore.data.messages : [];
     const t2aBeforeCount = t2aBeforeMessages.length;
     const t2aPrompt = 'Just answer what is the capital of France. No Fluff. No COmmentary.  No Markup Respond in lower case in one word.';
+    t3aDbg(`step 1: beforeCount=${t2aBeforeCount}`);
 
+    const t3aTurnId = randomTurnId();
+    t3aDbg(`step 2: posting non-probe chat-send (turn-id=${t3aTurnId})`);
     const t2aSendRes = await httpJson('POST', `${BASE}/cards/${CHAT_CARD_ID}/actions`, {
       actionType: 'chat-send',
       payload: {
@@ -626,10 +831,13 @@ try {
           prompt: t2aPrompt,
           chatTimeoutMs: 180000,
         }),
+        'turn-id': t3aTurnId,
       },
     });
+    t3aDbg(`step 2: chat-send returned status=${t2aSendRes.status}`);
     assert(t2aSendRes.status === 200, `T3a chat-send returned ${t2aSendRes.status}`);
 
+    t3aDbg('step 3: waiting for assistant message containing paris on chat SSE');
     const t2aAssistant = await waitForChatPredicate((events) => {
       for (let i = events.length - 1; i >= 0; i -= 1) {
         const e = events[i];
@@ -639,16 +847,23 @@ try {
       }
       return false;
     }, 240_000, 'T3a assistant response with paris');
+    t3aDbg('step 3: assistant SSE event observed');
     assert(!!t2aAssistant, 'T3a assistant response with paris not observed on SSE');
+    const t2aSseLast = t2aAssistant.messages[t2aAssistant.messages.length - 1];
+    t3aDbg(`step 3: assistant SSE text=${JSON.stringify(String(t2aSseLast?.text || '').slice(0, 400))}`);
 
+    t3aDbg('step 4: fetching post-chat transcript');
     const t2aAfter = await httpGet(`${BASE}/cards/${CHAT_CARD_ID}/chats?all-turns=true`);
+    t3aDbg(`step 4: post-chat fetch returned status=${t2aAfter.status}`);
     assert(t2aAfter.status === 200, `T3a post chats returned ${t2aAfter.status}`);
     const t2aAfterMessages = Array.isArray(t2aAfter.data?.messages) ? t2aAfter.data.messages : [];
     const t2aNewMessages = t2aAfterMessages.slice(t2aBeforeCount);
+    t3aDbg(`step 4: validating ${t2aNewMessages.length} new messages`);
     assert(t2aNewMessages.length >= 2, `T3a expected at least 2 new chat messages, got ${t2aNewMessages.length}`);
     const t2aAssistantMsg = [...t2aNewMessages].reverse().find((m) => m?.role === 'assistant');
     assert(!!t2aAssistantMsg && typeof t2aAssistantMsg.id === 'string', 'T3a assistant chat message missing id');
     assert(/paris/i.test(String(t2aAssistantMsg?.text || '')), 'T3a assistant file content missing paris');
+    t3aDbg('step 4: all assertions passed');
     console.log('[T3a] ok: non-probe response contains paris');
   }
 
@@ -662,8 +877,9 @@ try {
     const t2bBeforeMessages = Array.isArray(t2bBefore.data?.messages) ? t2bBefore.data.messages : [];
     const t2bBeforeCount = t2bBeforeMessages.length;
 
+    const t3bTurnId = randomTurnId();
     const t2bUploadRes = await httpUploadChatFile(
-      `${BASE}/cards/${CHAT_CARD_ID}/files?inChat=true`,
+      `${BASE}/cards/${CHAT_CARD_ID}/files?inChat=true&turn-id=${encodeURIComponent(t3bTurnId)}`,
       'q1.txt',
       'tokyo',
     );
@@ -702,6 +918,7 @@ try {
       payload: {
         text: `${ECHO_PROBE_MARKER}${t2bPrompt}${ECHO_PROBE_MARKER}`,
         files: [uploadedFile],
+        'turn-id': t3bTurnId,
       },
     });
     assert(t2bSendRes.status === 200, `T3b chat-send returned ${t2bSendRes.status}`);
@@ -734,6 +951,601 @@ try {
     assert(String(t2bAssistantMsg?.text || '').trim() === 'tokyo', 'T3b assistant attachment content mismatch');
     console.log('[T3b] ok: upload protocol and ordered probe lifecycle observed with attachment-derived assistant reply');
   }
+
+  if (skipT4) {
+    console.log('\n=== T4: skipped (--skip-t4) ===');
+  } else {
+    console.log('\n=== T4: preflight MCP smoke checks ===');
+
+    const discoverSourceKindsData = expectMcpSuccess(
+      await httpMcp('discover.source-kinds', {}),
+      'T4 discover.source-kinds',
+    );
+    assert(discoverSourceKindsData && typeof discoverSourceKindsData === 'object', 'T4 discover.source-kinds missing payload');
+    assert(discoverSourceKindsData.sourceKinds && typeof discoverSourceKindsData.sourceKinds === 'object', 'T4 discover.source-kinds missing sourceKinds');
+    const discoveredSourceKinds = Object.keys(discoverSourceKindsData.sourceKinds).sort();
+    assert(
+      JSON.stringify(discoveredSourceKinds) === JSON.stringify(['mock', 'sqlite', 'urls']),
+      `T4 discover.source-kinds mismatch: ${JSON.stringify(discoveredSourceKinds)}`,
+    );
+    console.log('[T4.discover] ok: source kinds match demo task executor');
+
+    const getCardDefinition = (fileName) => {
+      const filePath = path.join(BOARD_DIR, 'cards', fileName);
+      const raw = fs.readFileSync(filePath, 'utf-8');
+      return JSON.parse(raw);
+    };
+
+    const expectPreflightSuccess = (res, label) => {
+      assert(res.status === 200, `${label} returned ${res.status}`);
+      assert(res.data?.status === 'success', `${label} expected status=success, got ${JSON.stringify(res.data)}`);
+      assert(res.data?.data && typeof res.data.data === 'object', `${label} missing success data`);
+      return res.data.data;
+    };
+
+    const portfolioCard = getCardDefinition('cardT-portfolio.json');
+    const marketCard = getCardDefinition('cardT-market-prices.json');
+    const portfolioValueCard = getCardDefinition('cardT-portfolio-value.json');
+    const baseHoldings = Array.isArray(portfolioCard?.card_data?.holdings) ? deepCloneJson(portfolioCard.card_data.holdings) : [];
+
+    const mockQuotes = {
+      quoteResponse: {
+        result: [
+          { symbol: 'AAPL', shortName: 'Apple Inc.', regularMarketPrice: 198.15, regularMarketChange: 2.15, regularMarketChangePercent: 1.10 },
+          { symbol: 'MSFT', shortName: 'Microsoft Corp.', regularMarketPrice: 415.32, regularMarketChange: -1.23, regularMarketChangePercent: -0.30 },
+          { symbol: 'GOOGL', shortName: 'Alphabet Inc.', regularMarketPrice: 174.89, regularMarketChange: 0.89, regularMarketChangePercent: 0.51 },
+          { symbol: 'TSLA', shortName: 'Tesla Inc.', regularMarketPrice: 247.12, regularMarketChange: 5.43, regularMarketChangePercent: 2.25 },
+        ],
+        error: null,
+      },
+    };
+
+    const makePortfolioVariant = (id, extraHolding) => {
+      const card = deepCloneJson(portfolioCard);
+      card.id = id;
+      card.card_data.holdings = [...baseHoldings, extraHolding];
+      return card;
+    };
+
+    const makeMockSourceCard = ({ id, bindTo = 'quotes', secondBindTo = null, includeProjection = false, projectionExpr = '"ok"', missingMock = false }) => {
+      const card = deepCloneJson(marketCard);
+      card.id = id;
+      card.requires = [];
+      card.source_defs = [
+        { bindTo, mock: missingMock ? 'missing-mock-key' : 'quotes' },
+        ...(secondBindTo ? [{ bindTo: secondBindTo, mock: 'quotes' }] : []),
+      ];
+      if (includeProjection) {
+        card.source_defs[0].projections = { passthrough: projectionExpr };
+      } else {
+        delete card.source_defs[0].projections;
+      }
+      delete card.source_defs[0].urls;
+      if (card.source_defs[1]) delete card.source_defs[1].urls;
+      return card;
+    };
+
+    const portfolioVariantA = makePortfolioVariant('card-portfolio-preflight-a', { ticker: 'NVDA', quantity: 7, cost_basis: 121 });
+    const portfolioVariantB = makePortfolioVariant('card-portfolio-preflight-b', { ticker: 'AMD', quantity: 9, cost_basis: 143 });
+    const marketMockSourceCardA = makeMockSourceCard({ id: 'card-market-prices-preflight-source-a' });
+    const marketMockSourceCardB = makeMockSourceCard({ id: 'card-market-prices-preflight-source-b', includeProjection: true });
+    const marketMockSourceCardC = makeMockSourceCard({ id: 'card-market-prices-preflight-source-c', secondBindTo: 'quotesBackup' });
+    const marketMockSourceCardD = makeMockSourceCard({ id: 'card-market-prices-preflight-source-d', bindTo: 'quotesPrimary' });
+    const marketMockSourceCardE = makeMockSourceCard({ id: 'card-market-prices-preflight-source-e', bindTo: 'quotesEcho' });
+    const marketMissingMockCard = makeMockSourceCard({ id: 'card-market-prices-preflight-missing', missingMock: true });
+    const invalidCard = {
+      ...deepCloneJson(marketCard),
+      id: '',
+      source_defs: [{ bindTo: '', mock: 'quotes' }],
+      view: { layout: { kind: 'stack' }, elements: [{ id: 'broken' }] },
+    };
+
+    const validateSuccessCases = [
+      { name: 'portfolio live', card: portfolioCard, expectCardId: 'card-portfolio' },
+      { name: 'market live', card: marketCard, expectCardId: 'card-market-prices' },
+      { name: 'portfolio-value live', card: portfolioValueCard, expectCardId: 'card-portfolio-value' },
+      { name: 'portfolio variant', card: portfolioVariantA, expectCardId: 'card-portfolio-preflight-a' },
+      { name: 'portfolio variant B', card: portfolioVariantB, expectCardId: 'card-portfolio-preflight-b' },
+    ];
+    for (const tc of validateSuccessCases) {
+      const body = expectPreflightSuccess(await httpMcp('preflight.validate-candidate-card-definition', {
+        candidate_card_content: tc.card,
+      }), `T4 validate success (${tc.name})`);
+      assert(body.cardId === tc.expectCardId, `T4 validate ${tc.name} cardId mismatch`);
+      assert(body.isValid === true, `T4 validate ${tc.name} expected isValid=true`);
+      assert(Array.isArray(body.issues) && body.issues.length === 0, `T4 validate ${tc.name} expected no issues`);
+      console.log(`[T4.validate] ok: ${tc.name}`);
+    }
+
+    const validateFailureBody = expectPreflightSuccess(await httpMcp('preflight.validate-candidate-card-definition', {
+      candidate_card_content: invalidCard,
+    }), 'T4 validate failure (invalid card)');
+    assert(validateFailureBody.isValid === false, 'T4 validate invalid card should be invalid');
+    assert(Array.isArray(validateFailureBody.issues) && validateFailureBody.issues.length > 0, 'T4 validate invalid card should report issues');
+    console.log('[T4.validate] ok: invalid card reports validation issues');
+
+    const materializeSuccessCases = [
+      {
+        name: 'portfolio live empty mocks',
+        card: portfolioCard,
+        mockRequires: {},
+        mockFetchedSources: {},
+        verify: (body) => {
+          assert(Array.isArray(body.provides_outputs?.holdings), 'T4 materialize portfolio holdings missing');
+          assert(body.provides_outputs.holdings.length === baseHoldings.length, 'T4 materialize portfolio holdings length mismatch');
+          assert(body.rendered_view?.elements?.[0]?.kind === 'editable-table', 'T4 materialize portfolio rendered_view mismatch');
+        },
+      },
+      {
+        name: 'portfolio variant with extra holding',
+        card: portfolioVariantA,
+        mockRequires: {},
+        mockFetchedSources: {},
+        verify: (body) => {
+          assert(Array.isArray(body.provides_outputs?.holdings), 'T4 materialize portfolio variant holdings missing');
+          assert(body.provides_outputs.holdings.length === baseHoldings.length + 1, 'T4 materialize portfolio variant holdings length mismatch');
+        },
+      },
+      {
+        name: 'portfolio variant B with extra holding',
+        card: portfolioVariantB,
+        mockRequires: {},
+        mockFetchedSources: {},
+        verify: (body) => {
+          assert(Array.isArray(body.provides_outputs?.holdings), 'T4 materialize portfolio variant B holdings missing');
+          assert(body.provides_outputs.holdings.length === baseHoldings.length + 1, 'T4 materialize portfolio variant B holdings length mismatch');
+        },
+      },
+      {
+        name: 'portfolio-value live with mock requires',
+        card: portfolioValueCard,
+        mockRequires: { holdings: baseHoldings, quotes: mockQuotes },
+        mockFetchedSources: {},
+        verify: (body) => {
+          assert(Array.isArray(body.computed_values?.positions) && body.computed_values.positions.length > 0, 'T4 materialize portfolio-value positions missing');
+          assert(Array.isArray(body.provides_outputs?.positions) && body.provides_outputs.positions.length > 0, 'T4 materialize portfolio-value provides missing');
+          assert(body.rendered_view?.elements?.length === 3, 'T4 materialize portfolio-value rendered_view length mismatch');
+        },
+      },
+      {
+        name: 'portfolio-value subset requires',
+        card: portfolioValueCard,
+        mockRequires: {
+          holdings: baseHoldings.slice(0, 2),
+          quotes: { quoteResponse: { result: mockQuotes.quoteResponse.result.slice(0, 2), error: null } },
+        },
+        mockFetchedSources: {},
+        verify: (body) => {
+          assert(Array.isArray(body.computed_values?.positions) && body.computed_values.positions.length === 2, 'T4 materialize portfolio-value subset positions mismatch');
+          assert(Array.isArray(body.provides_outputs?.positions) && body.provides_outputs.positions.length === 2, 'T4 materialize portfolio-value subset provides mismatch');
+        },
+      },
+    ];
+    for (const tc of materializeSuccessCases) {
+      const body = expectPreflightSuccess(await httpMcp('preflight.materialize-candidate-card', {
+        candidate_card_content: tc.card,
+        mock_requires: tc.mockRequires,
+        mock_fetched_sources: tc.mockFetchedSources,
+      }), `T4 materialize success (${tc.name})`);
+      assert(body.ok === true, `T4 materialize ${tc.name} expected ok=true`);
+      assert(Array.isArray(body.errors) && body.errors.length === 0, `T4 materialize ${tc.name} expected no errors`);
+      tc.verify(body);
+      console.log(`[T4.materialize] ok: ${tc.name}`);
+    }
+
+    const materializeFailureRes = await httpMcp('preflight.materialize-candidate-card', {
+      candidate_card_content: portfolioCard,
+    });
+    assert(materializeFailureRes.status === 400, `T4 materialize missing args expected 400, got ${materializeFailureRes.status}`);
+    assert(materializeFailureRes.data?.error === 'MCP tool requires mock_requires', 'T4 materialize missing args error mismatch');
+    console.log('[T4.materialize] ok: missing required mocks is rejected');
+
+    const probeSuccessCases = [
+      { name: 'single mock source base', card: marketMockSourceCardA, sourceIdx: 0, bindTo: 'quotes', mockProjections: {} },
+      { name: 'two mock sources first entry', card: marketMockSourceCardC, sourceIdx: 0, bindTo: 'quotes', mockProjections: {} },
+      { name: 'two mock sources second entry', card: marketMockSourceCardC, sourceIdx: 1, bindTo: 'quotesBackup', mockProjections: {} },
+      { name: 'single mock source alternate bindTo', card: marketMockSourceCardD, sourceIdx: 0, bindTo: 'quotesPrimary', mockProjections: {} },
+    ];
+    for (const tc of probeSuccessCases) {
+      const body = expectPreflightSuccess(await httpMcp('preflight.probe-single-source-in-candidate-card', {
+        candidate_card_content: tc.card,
+        source_idx: tc.sourceIdx,
+        mock_projections: tc.mockProjections,
+      }), `T4 probe success (${tc.name})`);
+      assert(body.bindTo === tc.bindTo, `T4 probe ${tc.name} bindTo mismatch`);
+      assert(body.reachable === true, `T4 probe ${tc.name} expected reachable=true`);
+      assert(typeof body.latencyMs === 'number', `T4 probe ${tc.name} expected numeric latencyMs`);
+      console.log(`[T4.probe] ok: ${tc.name}`);
+    }
+
+    const probeFailureRes = await httpMcp('preflight.probe-single-source-in-candidate-card', {
+      candidate_card_content: marketMissingMockCard,
+      source_idx: 0,
+      mock_projections: {},
+    });
+    assert(probeFailureRes.status === 400, `T4 probe failure expected 400, got ${probeFailureRes.status}`);
+    assert(typeof probeFailureRes.data?.error === 'string' && probeFailureRes.data.error.length > 0, 'T4 probe failure expected error text');
+    console.log('[T4.probe] ok: missing mock source returns HTTP error');
+
+    const runSourceSuccessCases = [
+      { name: 'single mock source base', card: marketMockSourceCardA, sourceIdx: 0, bindTo: 'quotes' },
+      { name: 'two mock sources first entry', card: marketMockSourceCardC, sourceIdx: 0, bindTo: 'quotes' },
+      { name: 'two mock sources second entry', card: marketMockSourceCardC, sourceIdx: 1, bindTo: 'quotesBackup' },
+      { name: 'single mock source alternate bindTo', card: marketMockSourceCardE, sourceIdx: 0, bindTo: 'quotesEcho' },
+    ];
+    for (const tc of runSourceSuccessCases) {
+      const body = expectPreflightSuccess(await httpMcp('preflight.run-single-source-in-candidate-card', {
+        candidate_card_content: tc.card,
+        source_idx: tc.sourceIdx,
+        mock_projections: {},
+      }), `T4 run-source success (${tc.name})`);
+      assert(body.bindTo === tc.bindTo, `T4 run-source ${tc.name} bindTo mismatch`);
+      assert(body.ok === true, `T4 run-source ${tc.name} expected ok=true`);
+      assert(Array.isArray(body.issues) && body.issues.length === 0, `T4 run-source ${tc.name} expected no issues`);
+      assert(Array.isArray(body.result?.quoteResponse?.result) && body.result.quoteResponse.result.length > 0, `T4 run-source ${tc.name} result shape mismatch`);
+      console.log(`[T4.run-source] ok: ${tc.name}`);
+    }
+
+    const runSourceFailureBody = expectPreflightSuccess(await httpMcp('preflight.run-single-source-in-candidate-card', {
+      candidate_card_content: marketMissingMockCard,
+      source_idx: 0,
+      mock_projections: {},
+    }), 'T4 run-source failure (missing mock source)');
+    assert(runSourceFailureBody.ok === false, 'T4 run-source missing mock should set ok=false');
+    assert(Array.isArray(runSourceFailureBody.issues) && runSourceFailureBody.issues.length > 0, 'T4 run-source missing mock should report issues');
+    console.log('[T4.run-source] ok: missing mock source returns ok=false with issues');
+
+    const liveRunCardId = String(marketCard?.id || 'card-market-prices');
+
+    const liveRunSourceBody = expectPreflightSuccess(await httpMcp('preflight.run-single-source-in-live-card', {
+      card_id: liveRunCardId,
+      source_idx: 0,
+      mock_requires: { holdings: baseHoldings },
+    }), 'T4 run-source live card success');
+    assert(liveRunSourceBody.bindTo === 'quotes', 'T4 run-source live card bindTo mismatch');
+    assert(liveRunSourceBody.ok === true, 'T4 run-source live card expected ok=true');
+    assert(Array.isArray(liveRunSourceBody.issues) && liveRunSourceBody.issues.length === 0, 'T4 run-source live card expected no issues');
+    assert(Array.isArray(liveRunSourceBody.result) && liveRunSourceBody.result.length === baseHoldings.length, 'T4 run-source live card result shape mismatch');
+    console.log('[T4.run-source-live] ok: live card source run returns candidate-compatible shape');
+
+    const liveRunRequiresBody = expectPreflightSuccess(await httpMcp('preflight.run-single-source-in-live-card', {
+      card_id: liveRunCardId,
+      source_idx: 0,
+      mock_requires: { holdings: baseHoldings },
+    }), 'T4 run-source live card uses mock_requires in projections');
+    assert(liveRunRequiresBody.bindTo === 'quotes', 'T4 run-source live card requires bindTo mismatch');
+    assert(liveRunRequiresBody.ok === true, 'T4 run-source live card requires expected ok=true');
+    assert(Array.isArray(liveRunRequiresBody.issues) && liveRunRequiresBody.issues.length === 0, 'T4 run-source live card requires expected no issues');
+    assert(Array.isArray(liveRunRequiresBody.result) && liveRunRequiresBody.result.length === baseHoldings.length, 'T4 run-source live card requires result shape mismatch');
+    console.log('[T4.run-source-live] ok: non-empty mock_requires is consumed via source projections');
+
+    const liveRunOutOfRangeRes = await httpMcp('preflight.run-single-source-in-live-card', {
+      card_id: liveRunCardId,
+      source_idx: 9,
+      mock_requires: {},
+    });
+    assert(liveRunOutOfRangeRes.status === 400, `T4 run-source live card out-of-range expected 400, got ${liveRunOutOfRangeRes.status}`);
+    assert(typeof liveRunOutOfRangeRes.data?.error === 'string' && liveRunOutOfRangeRes.data.error.length > 0, 'T4 run-source live card out-of-range expected error text');
+    console.log('[T4.run-source-live] ok: out-of-range source_idx is rejected with HTTP error');
+
+    const liveRunMissingMockRequiresRes = await httpMcp('preflight.run-single-source-in-live-card', {
+      card_id: liveRunCardId,
+      source_idx: 0,
+    });
+    assert(liveRunMissingMockRequiresRes.status === 400, `T4 run-source live card missing mock_requires expected 400, got ${liveRunMissingMockRequiresRes.status}`);
+    assert(liveRunMissingMockRequiresRes.data?.error === 'MCP tool requires mock_requires', 'T4 run-source live card missing mock_requires error mismatch');
+    console.log('[T4.run-source-live] ok: missing mock_requires is rejected');
+
+    const runCycleSuccessCases = [
+      {
+        name: 'portfolio live',
+        card: portfolioCard,
+        mockRequires: {},
+        verify: (body) => {
+          assert(Array.isArray(body.provides_outputs?.holdings) && body.provides_outputs.holdings.length === baseHoldings.length, 'T4 run-cycle portfolio provides mismatch');
+          assert(body.rendered_view?.elements?.[0]?.kind === 'editable-table', 'T4 run-cycle portfolio rendered_view mismatch');
+        },
+      },
+      {
+        name: 'portfolio variant',
+        card: portfolioVariantB,
+        mockRequires: {},
+        verify: (body) => {
+          assert(Array.isArray(body.provides_outputs?.holdings) && body.provides_outputs.holdings.length === baseHoldings.length + 1, 'T4 run-cycle portfolio variant provides mismatch');
+        },
+      },
+      {
+        name: 'portfolio variant B',
+        card: portfolioVariantB,
+        mockRequires: {},
+        verify: (body) => {
+          assert(Array.isArray(body.provides_outputs?.holdings) && body.provides_outputs.holdings.length === baseHoldings.length + 1, 'T4 run-cycle portfolio variant B provides mismatch');
+          assert(body.rendered_view?.elements?.[0]?.kind === 'editable-table', 'T4 run-cycle portfolio variant B rendered_view mismatch');
+        },
+      },
+      {
+        name: 'portfolio-value with full requires',
+        card: portfolioValueCard,
+        mockRequires: { holdings: baseHoldings, quotes: mockQuotes },
+        verify: (body) => {
+          assert(Array.isArray(body.provides_outputs?.positions) && body.provides_outputs.positions.length > 0, 'T4 run-cycle portfolio-value provides mismatch');
+          assert(body.rendered_view?.elements?.length === 3, 'T4 run-cycle portfolio-value rendered_view mismatch');
+        },
+      },
+      {
+        name: 'portfolio-value subset requires',
+        card: portfolioValueCard,
+        mockRequires: {
+          holdings: baseHoldings.slice(0, 2),
+          quotes: { quoteResponse: { result: mockQuotes.quoteResponse.result.slice(0, 2), error: null } },
+        },
+        verify: (body) => {
+          assert(Array.isArray(body.provides_outputs?.positions) && body.provides_outputs.positions.length === 2, 'T4 run-cycle portfolio-value subset length mismatch');
+        },
+      },
+      {
+        name: 'market-prices with live source simulation',
+        card: marketCard,
+        mockRequires: { holdings: baseHoldings.slice(0, 3) },
+        verify: (body) => {
+          const quoteRows = body.provides_outputs?.quotes?.quoteResponse?.result;
+          assert(Array.isArray(quoteRows) && quoteRows.length === 3, 'T4 run-cycle market-prices provides result length mismatch');
+          assert(typeof quoteRows[0]?.symbol === 'string' && quoteRows[0].symbol.length > 0, 'T4 run-cycle market-prices provides symbol missing');
+
+          const resolvedRows = body.rendered_view?.elements?.[0]?.resolved;
+          assert(Array.isArray(resolvedRows) && resolvedRows.length === 3, 'T4 run-cycle market-prices rendered resolved length mismatch');
+          assert(typeof resolvedRows[0]?.ticker === 'string' && resolvedRows[0].ticker.length > 0, 'T4 run-cycle market-prices rendered ticker missing');
+          assert(typeof resolvedRows[0]?.price === 'number', 'T4 run-cycle market-prices rendered price missing');
+        },
+      },
+    ];
+    for (const tc of runCycleSuccessCases) {
+      const body = expectPreflightSuccess(await httpMcp('preflight.run-one-cycle-with-candidate-card', {
+        candidate_card_content: tc.card,
+        mock_requires: tc.mockRequires,
+      }), `T4 run-cycle success (${tc.name})`);
+      assert(body.ok === true, `T4 run-cycle ${tc.name} expected ok=true`);
+      assert(Array.isArray(body.issues) && body.issues.length === 0, `T4 run-cycle ${tc.name} expected no issues`);
+      tc.verify(body);
+      console.log(`[T4.run-cycle] ok: ${tc.name}`);
+    }
+
+    console.log('\n[T4.remove-card] testing manage.remove-card lifecycle');
+
+    const T4_REMOVE_CARD_ID = 'card-t4-remove-test';
+    const T4_REMOVE_CARD_V1 = {
+      id: T4_REMOVE_CARD_ID,
+      card_data: { label: 'v1', color: 'blue' },
+    };
+    const T4_REMOVE_CARD_V2 = {
+      id: T4_REMOVE_CARD_ID,
+      card_data: { label: 'v2', color: 'red' },
+    };
+
+    const t4UpsertV1Res = await httpMcp('manage.upsert-card', {
+      card_id: T4_REMOVE_CARD_ID,
+      candidate_card_content: T4_REMOVE_CARD_V1,
+    });
+    assert(t4UpsertV1Res.status === 200, `T4.remove-card v1 upsert returned ${t4UpsertV1Res.status}`);
+    const t4UpsertV1Data = expectMcpSuccess(t4UpsertV1Res, 'T4.remove-card v1 upsert');
+    assert(t4UpsertV1Data?.board_result?.status === 'success', 'T4.remove-card v1 upsert board_result expected success');
+    console.log('[T4.remove-card] ok: v1 card upserted');
+
+    let t4StatusBeforeRemove = null;
+    for (let attempt = 0; attempt < 3; attempt += 1) {
+      t4StatusBeforeRemove = expectMcpSuccess(
+        await httpMcp('inspect.board-runtime-status', {}),
+        'T4.remove-card board-runtime-status before remove',
+      );
+      const cards = Array.isArray(t4StatusBeforeRemove?.cards) ? t4StatusBeforeRemove.cards : [];
+      if (cards.some(c => c['card-id'] === T4_REMOVE_CARD_ID)) break;
+      if (attempt < 2) {
+        await new Promise((resolve) => setTimeout(resolve, 1_000));
+      }
+    }
+    const t4CardsBefore = Array.isArray(t4StatusBeforeRemove?.cards) ? t4StatusBeforeRemove.cards : [];
+    assert(t4CardsBefore.some(c => c['card-id'] === T4_REMOVE_CARD_ID), 'T4.remove-card: card not found in board-runtime-status before remove');
+    const t4CardCountBefore = t4StatusBeforeRemove?.summary?.card_count ?? 0;
+    console.log(`[T4.remove-card] ok: board-runtime-status has ${t4CardCountBefore} cards before remove (includes ${T4_REMOVE_CARD_ID})`);
+
+    const t4BoardEventsBefore = NS.boardEvents.length;
+    const t4RemoveRes = await httpMcp('manage.remove-card', { card_id: T4_REMOVE_CARD_ID });
+    assert(t4RemoveRes.status === 200, `T4.remove-card remove returned ${t4RemoveRes.status}`);
+    const t4RemoveData = expectMcpSuccess(t4RemoveRes, 'T4.remove-card remove');
+    assert(t4RemoveData?.board_result?.status === 'success', 'T4.remove-card board_result expected success');
+    assert(t4RemoveData?.store_result?.status === 'success', 'T4.remove-card store_result expected success');
+    console.log('[T4.remove-card] ok: manage.remove-card returned success for both board and store');
+
+    await new Promise((resolve) => setTimeout(resolve, 2_000));
+
+    const t4CardRemovedEvent = await waitUntil(
+      () => NS.boardEvents.slice(t4BoardEventsBefore).find(e => e.kind === 'card_removed' && e.cardId === T4_REMOVE_CARD_ID) || false,
+      10_000,
+      `card_removed SSE notification for ${T4_REMOVE_CARD_ID}`,
+    );
+    assert(t4CardRemovedEvent && t4CardRemovedEvent.kind === 'card_removed', 'T4.remove-card: card_removed SSE event not received');
+    assert(t4CardRemovedEvent.cardId === T4_REMOVE_CARD_ID, 'T4.remove-card: card_removed SSE cardId mismatch');
+    console.log(`[T4.remove-card] ok: card_removed SSE notification received for ${T4_REMOVE_CARD_ID}`);
+
+    const t4StatusAfterRemove = expectMcpSuccess(
+      await httpMcp('inspect.board-runtime-status', {}),
+      'T4.remove-card board-runtime-status after remove',
+    );
+    const t4CardsAfter = Array.isArray(t4StatusAfterRemove?.cards) ? t4StatusAfterRemove.cards : [];
+    assert(!t4CardsAfter.some(c => c['card-id'] === T4_REMOVE_CARD_ID), 'T4.remove-card: card still present in board-runtime-status after remove');
+    const t4CardCountAfter = t4StatusAfterRemove?.summary?.card_count ?? 0;
+    assert(t4CardCountAfter === t4CardCountBefore - 1, `T4.remove-card: card_count expected ${t4CardCountBefore - 1}, got ${t4CardCountAfter}`);
+    console.log(`[T4.remove-card] ok: card absent from board-runtime-status after remove (count: ${t4CardCountBefore} → ${t4CardCountAfter})`);
+
+    const t4BoardEventsBeforeV2 = NS.boardEvents.length;
+    const t4UpsertV2Res = await httpMcp('manage.upsert-card', {
+      card_id: T4_REMOVE_CARD_ID,
+      candidate_card_content: T4_REMOVE_CARD_V2,
+    });
+    assert(t4UpsertV2Res.status === 200, `T4.remove-card v2 upsert returned ${t4UpsertV2Res.status}`);
+    const t4UpsertV2Data = expectMcpSuccess(t4UpsertV2Res, 'T4.remove-card v2 upsert');
+    assert(t4UpsertV2Data?.board_result?.status === 'success', 'T4.remove-card v2 upsert board_result expected success');
+    console.log('[T4.remove-card] ok: v2 card upserted under same id');
+
+    const t4CardRefreshedEvent = await waitUntil(
+      () => NS.boardEvents.slice(t4BoardEventsBeforeV2).find(e => e.kind === 'card_refreshed' && e.cardId === T4_REMOVE_CARD_ID) || false,
+      10_000,
+      `card_refreshed SSE notification for ${T4_REMOVE_CARD_ID} after v2 upsert`,
+    );
+    assert(t4CardRefreshedEvent && t4CardRefreshedEvent.kind === 'card_refreshed', 'T4.remove-card: card_refreshed SSE event not received after v2 upsert');
+    console.log(`[T4.remove-card] ok: card_refreshed SSE notification received for v2 of ${T4_REMOVE_CARD_ID}`);
+
+    await waitForAllCompleted(30_000, 'T4 remove-card re-upsert completion');
+
+    const t4StatusAfterV2 = expectMcpSuccess(
+      await httpMcp('inspect.board-runtime-status', {}),
+      'T4.remove-card board-runtime-status after v2 upsert',
+    );
+
+    const t4CardsAfterV2 = Array.isArray(t4StatusAfterV2?.cards) ? t4StatusAfterV2.cards : [];
+    assert(t4CardsAfterV2.some(c => c['card-id'] === T4_REMOVE_CARD_ID), 'T4.remove-card: v2 card missing from board-runtime-status');
+    const t4CardCountAfterV2 = t4StatusAfterV2?.summary?.card_count ?? 0;
+    assert(t4CardCountAfterV2 === t4CardCountBefore, `T4.remove-card: card_count after v2 upsert expected ${t4CardCountBefore}, got ${t4CardCountAfterV2}`);
+    console.log('[T4.remove-card] ok: v2 card present in board-runtime-status');
+
+    const t4InspectV2Data = expectMcpSuccess(
+      await httpMcp('inspect.card-definition-and-runtime', { card_id: T4_REMOVE_CARD_ID }),
+      'T4.remove-card inspect v2',
+    );
+    assert(t4InspectV2Data?.cardId === T4_REMOVE_CARD_ID, 'T4.remove-card inspect v2 cardId mismatch');
+    const t4V2CardData = t4InspectV2Data?.card_definition_and_static_data?.card_data ?? null;
+    assert(t4V2CardData?.label === 'v2', `T4.remove-card inspect v2 label expected "v2", got "${t4V2CardData?.label}"`);
+    assert(t4V2CardData?.color === 'red', `T4.remove-card inspect v2 color expected "red", got "${t4V2CardData?.color}"`);
+    console.log('[T4.remove-card] ok: inspect.card-definition-and-runtime reflects v2 card_data after re-upsert');
+
+    await httpMcp('manage.remove-card', { card_id: T4_REMOVE_CARD_ID });
+    console.log('[T4.remove-card] cleanup done');
+
+  }
+
+  if (skipT5) {
+    console.log('\n=== T5: skipped (--skip-t5) ===');
+  } else {
+    console.log('\n=== T5: mcp-controlplane setstate/getstate ===');
+    const T5_CARD_ID = CHAT_CARD_ID;
+
+    const t5IsProcInit = expectMcpSuccess(
+      await httpMcpControlplane('getstate.is-chat-processing', { board_id: BOARD_ID, card_id: T5_CARD_ID }),
+      'T5 getstate.is-chat-processing initial',
+    );
+    assert(t5IsProcInit?.active === false, `T5 expected initial chat-processing=false, got ${JSON.stringify(t5IsProcInit)}`);
+
+    expectMcpSuccess(
+      await httpMcpControlplane('setstate.chat-processing-started', { board_id: BOARD_ID, card_id: T5_CARD_ID }),
+      'T5 setstate.chat-processing-started',
+    );
+    const t5IsProcStarted = expectMcpSuccess(
+      await httpMcpControlplane('getstate.is-chat-processing', { board_id: BOARD_ID, card_id: T5_CARD_ID }),
+      'T5 getstate.is-chat-processing after start',
+    );
+    assert(t5IsProcStarted?.active === true, 'T5 expected chat-processing=true after setstate.chat-processing-started');
+
+    expectMcpSuccess(
+      await httpMcpControlplane('setstate.chat-processing-done', { board_id: BOARD_ID, card_id: T5_CARD_ID }),
+      'T5 setstate.chat-processing-done',
+    );
+    const t5IsProcDone = expectMcpSuccess(
+      await httpMcpControlplane('getstate.is-chat-processing', { board_id: BOARD_ID, card_id: T5_CARD_ID }),
+      'T5 getstate.is-chat-processing after done',
+    );
+    assert(t5IsProcDone?.active === false, 'T5 expected chat-processing=false after setstate.chat-processing-done');
+    console.log('[T5] ok: setstate/getstate chat-processing round-trip');
+
+    const t5ThreadId = `thread-t5-${Date.now()}`;
+    expectMcpSuccess(
+      await httpMcpControlplane('setstate.card-meta', { board_id: BOARD_ID, card_id: T5_CARD_ID, key: 'chat.foundry_thread_id', value: t5ThreadId }),
+      'T5 setstate.card-meta',
+    );
+    const t5GetMeta = expectMcpSuccess(
+      await httpMcpControlplane('getstate.card-meta', { board_id: BOARD_ID, card_id: T5_CARD_ID, key: 'chat.foundry_thread_id' }),
+      'T5 getstate.card-meta',
+    );
+    assert(t5GetMeta?.exists === true && t5GetMeta?.value === t5ThreadId, `T5 getstate.card-meta mismatch: ${JSON.stringify(t5GetMeta)}`);
+
+    const t5ReadCards = expectMcpSuccess(
+      await httpMcp('manage.read-card', { card_id: T5_CARD_ID }),
+      'T5 manage.read-card meta-redaction',
+    );
+    const t5ReadCard = Array.isArray(t5ReadCards) ? t5ReadCards[0] : null;
+    assert(t5ReadCard && t5ReadCard.meta === undefined, 'T5 expected manage.read-card to redact top-level meta');
+
+    const t5Inspect = expectMcpSuccess(
+      await httpMcp('inspect.card-definition-and-runtime', { card_id: T5_CARD_ID }),
+      'T5 inspect.card-definition-and-runtime meta-redaction',
+    );
+    assert(t5Inspect?.card_definition_and_static_data?.meta === undefined, 'T5 expected inspect to redact card_definition_and_static_data.meta');
+    console.log('[T5] ok: regular /mcp surfaces redact card meta');
+
+    // ── T5: admin-only card round-trip ──────────────────────────────────────
+    // 1. Read the existing card definition via the normal read-card path.
+    const t5AdminCardId = T5_CARD_ID;
+    const t5NormalRead = expectMcpSuccess(
+      await httpMcp('manage.read-card', { card_id: t5AdminCardId }),
+      'T5 admin setup: manage.read-card before marking admin',
+    );
+    const t5OriginalCard = Array.isArray(t5NormalRead) ? t5NormalRead[0] : null;
+    assert(t5OriginalCard, 'T5 expected card definition before marking as admin-only');
+
+    // 2. Upsert it as an admin-only card via the controlplane tool.
+    const t5AdminUpsert = expectMcpSuccess(
+      await httpMcpControlplane('manage.admin-upsert-card', {
+        board_id: BOARD_ID,
+        card_id: t5AdminCardId,
+        candidate_card_content: t5OriginalCard,
+      }),
+      'T5 manage.admin-upsert-card',
+    );
+    assert(t5AdminUpsert?.board_result, 'T5 expected board_result from admin upsert');
+    console.log('[T5] ok: manage.admin-upsert-card succeeded');
+
+    // 3. Verify the card is now invisible on the regular /mcp surface.
+    // Server throws with statusCode:404 for admin cards, so httpResult.status will be 404 (not 200).
+    const t5HiddenRead = await httpMcp('manage.read-card', { card_id: t5AdminCardId });
+    assert(t5HiddenRead?.status !== 200 || t5HiddenRead?.data?.status === 'fail',
+      `T5 expected manage.read-card to be blocked after admin upsert, got: ${JSON.stringify(t5HiddenRead)}`);
+    console.log('[T5] ok: manage.read-card blocked for admin-only card');
+
+    // 4. Verify the card IS visible via the controlplane admin-read-card tool.
+    const t5AdminRead = expectMcpSuccess(
+      await httpMcpControlplane('manage.admin-read-card', { board_id: BOARD_ID, card_id: t5AdminCardId }),
+      'T5 manage.admin-read-card',
+    );
+    const t5AdminCards = Array.isArray(t5AdminRead?.cards) ? t5AdminRead.cards : [];
+    assert(t5AdminCards.length > 0, 'T5 expected admin-read-card to return the card');
+    assert(t5AdminCards[0]?.meta?.__visible_controlplane_only === true, `T5 expected meta.__visible_controlplane_only=true, got: ${JSON.stringify(t5AdminCards[0]?.meta)}`);
+    console.log('[T5] ok: manage.admin-read-card returns card with __visible_controlplane_only=true');
+
+    // 5. Guard: setstate.card-meta must block changing the flag to a different value.
+    // key = 'chat.__visible_controlplane_only' passes the chat.* format check but contains
+    // the reserved segment, so it reaches the guard.
+    const t5MetaGuard = await httpMcpControlplane('setstate.card-meta', {
+      board_id: BOARD_ID,
+      card_id: t5AdminCardId,
+      key: 'chat.__visible_controlplane_only',
+      value: false,  // differs from current flag value (true) → must be rejected
+    });
+    assert(t5MetaGuard?.status !== 200,
+      `T5 expected setstate.card-meta to reject changing __visible_controlplane_only, got: ${JSON.stringify(t5MetaGuard)}`);
+    console.log('[T5] ok: setstate.card-meta blocked flag mutation (false != true)');
+
+    // 6. Guard: same key with value matching the current flag (true) must pass (idempotent).
+    const t5MetaIdempotent = expectMcpSuccess(
+      await httpMcpControlplane('setstate.card-meta', {
+        board_id: BOARD_ID,
+        card_id: t5AdminCardId,
+        key: 'chat.__visible_controlplane_only',
+        value: true,  // matches current flag value → idempotent, allowed
+      }),
+      'T5 setstate.card-meta idempotent same-value',
+    );
+    assert(t5MetaIdempotent, 'T5 expected setstate.card-meta to succeed with matching flag value');
+    console.log('[T5] ok: setstate.card-meta idempotent same-value allowed');
+  }
   }
 
   console.log('\n=== All smoke checks passed ===\n');
@@ -744,8 +1556,7 @@ try {
     } catch { /* ignore */ }
   }
   if (chatSseClient) chatSseClient.close();
-  serverProc.kill();
-  await new Promise((r) => serverProc.on('exit', r));
+  await stopChildProcess(serverProc, 'demo board server');
   if (sseWorker) await sseWorker.terminate();
 
   // Clean up the test setup directory