@chemx/starter-kit 26.9.25-789 → 26.9.26-253

package/cli/team/team-format.js

@@ -179,3 +179,91 @@ export const formatTaskDetailCard = (task, events = []) => {
   lines.push(`\x1b[90m${'─'.repeat(58)}\x1b[0m\n`);
   return lines.join('\n');
 };
+
+export const formatTeamHelpCard = () => {
+  const lines = [
+    '',
+    '\x1b[1m\x1b[36m⚡ [Chemical X] Multi-Agent Swarm Orchestration (team)\x1b[0m',
+    `\x1b[90m${'─'.repeat(58)}\x1b[0m`,
+    '  \x1b[1mUsage:\x1b[0m chemx team <command> [options]',
+    '',
+    '  \x1b[1mCommands:\x1b[0m',
+    '    \x1b[32mstatus\x1b[0m                   Display swarm agent, task, and lock status card',
+    '    \x1b[32mtask\x1b[0m [action]            Manage agent tasks (list, show, add, claim, done, update)',
+    '    \x1b[32mlock\x1b[0m [acquire|release]   Acquire or release a mutual exclusion file lock',
+    '    \x1b[32munlock\x1b[0m <file>            Release a file lock held by an agent',
+    '    \x1b[32mfeed\x1b[0m                     View swarm feed event timeline',
+    '    \x1b[32mpost\x1b[0m <message>           Post broadcast message to swarm feed',
+    '    \x1b[32minbox\x1b[0m [@agent]           View agent mailbox and notifications',
+    '    \x1b[32mdm\x1b[0m <@agent> <msg>        Send direct message to another agent',
+    '    \x1b[32mtokens\x1b[0m                   Inspect token consumption and telemetry breakdown',
+    '    \x1b[32mtriage\x1b[0m                   Generate tasks automatically from AST audit hazards',
+    '    \x1b[32mbenchmark\x1b[0m                Run memory and token reduction ablation benchmark',
+    '    \x1b[32mtrain\x1b[0m                    Train/evaluate vector and pattern indices',
+    '',
+    '  \x1b[1mGlobal Options:\x1b[0m',
+    '    \x1b[33m--as\x1b[0m <@agent>            Execute action as specified agent handle',
+    '    \x1b[33m--json\x1b[0m                   Output machine-readable JSON format',
+    '    \x1b[33m--help, -h\x1b[0m               Show help for team or specific subcommands',
+    `\x1b[90m${'─'.repeat(58)}\x1b[0m\n`
+  ];
+  return lines.join('\n');
+};
+
+export const formatTaskHelpCard = () => {
+  const lines = [
+    '',
+    '\x1b[1m\x1b[36m⚡ [Chemical X] Task Coordination Commands (team task)\x1b[0m',
+    `\x1b[90m${'─'.repeat(58)}\x1b[0m`,
+    '  \x1b[1mUsage:\x1b[0m chemx team task <action> [arguments] [options]',
+    '',
+    '  \x1b[1mActions:\x1b[0m',
+    '    \x1b[32mlist\x1b[0m                         List swarm tasks (default action)',
+    '    \x1b[32mshow\x1b[0m <taskId>                Display full details and activity stream for a task',
+    '    \x1b[32madd\x1b[0m "<title>"                Create a new task in the queue',
+    '    \x1b[32mclaim\x1b[0m <taskId>              Claim an unassigned task for an agent',
+    '    \x1b[32mdone\x1b[0m <taskId>               Complete a task with automatic verification audit',
+    '    \x1b[32mupdate\x1b[0m <taskId> [status]    Update task status (in_progress, blocked, done)',
+    '    \x1b[32mcomment\x1b[0m <taskId> <msg>       Post a comment or status update to a task',
+    '    \x1b[32mtriage\x1b[0m                    Generate tasks from AST architectural hazards',
+    '    \x1b[32mreconcile\x1b[0m                 Auto-resolve tasks whose hazards have been fixed',
+    '    \x1b[32mset-target\x1b[0m <id> <path>     Assign target file path to a task',
+    '    \x1b[32mvds-slot\x1b[0m <id> <moscow> <p> Set MoSCoW slot and priority on a task',
+    '    \x1b[32mtrace\x1b[0m <id> <url>            Attach provenance trace URL to a task',
+    '',
+    '  \x1b[1mOptions:\x1b[0m',
+    '    \x1b[33m--as\x1b[0m <@agent>            Agent handle (e.g. @agent-1)',
+    '    \x1b[33m--status\x1b[0m <status>        Filter by status (todo, in_progress, blocked, done)',
+    '    \x1b[33m--agent\x1b[0m <@agent>         Filter tasks assigned to agent',
+    '    \x1b[33m--prio\x1b[0m <1-5>             Task priority filter or setting',
+    '    \x1b[33m--force, -f\x1b[0m              Force complete task even with remaining hazards',
+    '    \x1b[33m--json\x1b[0m                   Output machine-readable JSON format',
+    '    \x1b[33m--help, -h\x1b[0m               Show this help message',
+    `\x1b[90m${'─'.repeat(58)}\x1b[0m\n`
+  ];
+  return lines.join('\n');
+};
+
+export const formatLockHelpCard = () => {
+  const lines = [
+    '',
+    '\x1b[1m\x1b[36m⚡ [Chemical X] Mutual Exclusion File Locking (team lock)\x1b[0m',
+    `\x1b[90m${'─'.repeat(58)}\x1b[0m`,
+    '  \x1b[1mUsage:\x1b[0m chemx team lock [acquire|release] <filePath> [options]',
+    '         chemx team unlock <filePath> [options]',
+    '',
+    '  \x1b[1mActions:\x1b[0m',
+    '    \x1b[32macquire\x1b[0m <path>              Acquire mutual exclusion lock (or enqueue in FIFO)',
+    '    \x1b[32mrelease\x1b[0m <path>              Release lock and promote next FIFO waiter',
+    '',
+    '  \x1b[1mOptions:\x1b[0m',
+    '    \x1b[33m--as\x1b[0m <@agent>            Agent handle acquiring/releasing lock (default: @agent)',
+    '    \x1b[33m--purpose\x1b[0m "<reason>"      Reason or intent for acquiring lock',
+    '    \x1b[33m--priority\x1b[0m <1-5>         Priority in FIFO wait queue (1 = highest, default: 2)',
+    '    \x1b[33m--pid\x1b[0m <pid>              Optional process PID for crash-recovery lease reclamation',
+    '    \x1b[33m--json\x1b[0m                   Output machine-readable JSON format',
+    '    \x1b[33m--help, -h\x1b[0m               Show this help message',
+    `\x1b[90m${'─'.repeat(58)}\x1b[0m\n`
+  ];
+  return lines.join('\n');
+};

package/cli/team/team-memory.js

@@ -17,7 +17,10 @@ export const recordMemoryInjection = (db, entry = {}) => {
 };
 
 export const recordMemoryUtilization = (db, { taskId, utilizedProvenance = [], causedRetry = false } = {}) => {
-  if (!db || !taskId) return;
+  const hasDb = Boolean(db);
+  const hasTaskId = Boolean(taskId);
+  const canRecord = hasDb && hasTaskId;
+  if (!canRecord) return;
   if (causedRetry) db.prepare('UPDATE agent_memory_log SET caused_retry = 1 WHERE task_id = ?').run(taskId);
   for (const prov of utilizedProvenance) {
     db.prepare('UPDATE agent_memory_log SET was_utilized = 1 WHERE task_id = ? AND (provenance_path = ? OR provenance_path LIKE ?)').run(taskId, prov, `%${prov}%`);
@@ -51,14 +54,79 @@ export const calculateMemoryMetrics = (db) => {
 
 export const runAblationComparison = (db) => {
   const m = calculateMemoryMetrics(db);
-  const turns = Math.max(10, m.totalCount || 10);
-  const baseTokens = turns * 2500, memTokens = Math.max(turns * 70, m.totalInjectedTokens || 700);
-  const tokensSaved = baseTokens - memTokens;
+  const row = db ? db.prepare(`
+    SELECT
+      COUNT(*) as totalTasks,
+      COALESCE(SUM(prompt_tokens), 0) as totalPromptTokens,
+      COALESCE(SUM(completion_tokens), 0) as totalCompletionTokens,
+      COALESCE(SUM(cached_tokens), 0) as totalCachedTokens,
+      COALESCE(SUM(cost_usd), 0) as totalCost
+    FROM agent_tasks
+  `).get() : null;
+
+  const taskStats = {
+    totalTasks: Number(row?.totalTasks || 0),
+    totalPromptTokens: Number(row?.totalPromptTokens || 0),
+    totalCompletionTokens: Number(row?.totalCompletionTokens || 0),
+    totalCachedTokens: Number(row?.totalCachedTokens || 0),
+    totalCost: Number(row?.totalCost || 0)
+  };
+
+  const hasTasks = taskStats.totalTasks > 0;
+  const hasMemories = m.totalCount > 0;
+  const hasRealData = Boolean(hasTasks || hasMemories);
+
+  if (!hasRealData) {
+    const turns = 10;
+    const baseTokens = turns * 2500;
+    const memTokens = 700;
+    const tokensSaved = baseTokens - memTokens;
+    const precisionGain = (100 / 12.0).toFixed(1) + 'x';
+    return {
+      hasRealData: false,
+      hasMeasuredTokens: false,
+      isSimulated: true,
+      workloadTurns: turns,
+      memoryEnabled: { mode: 'SQLite AST & Event Memory', tokensUsed: memTokens, staleRetryRatePct: 0.0, retrievalPrecisionPct: 100, astQualityScore: 100 },
+      memoryDisabled: { mode: 'Stateless Monolithic File Re-read', tokensUsed: baseTokens, staleRetryRatePct: 18.5, retrievalPrecisionPct: 12.0, astQualityScore: 84 },
+      delta: {
+        tokenReductionPct: Math.round((tokensSaved / baseTokens) * 100),
+        tokenReductionBasis: 'estimated_typical_usage',
+        isEstimated: true,
+        costAvoidedUsd: Number(((tokensSaved / 1000000) * 10.0).toFixed(4)),
+        retrievalPrecisionGainRatio: precisionGain,
+        staleRetriesEliminated: Math.round(turns * 0.185)
+      }
+    };
+  }
+
+  const turns = taskStats.totalTasks + m.totalCount;
+  const liveTokens = taskStats.totalPromptTokens + taskStats.totalCompletionTokens;
+  const hasMeasuredTokens = liveTokens > 0;
+  const memTokens = hasMeasuredTokens ? liveTokens : Math.max(turns * 70, m.totalInjectedTokens || 70);
+  const baseTokens = turns * 2500 + Math.round(memTokens * 0.5);
+  const tokensSaved = Math.max(0, baseTokens - memTokens);
+  const tokenReductionPct = baseTokens > 0 ? Math.round((tokensSaved / baseTokens) * 100) : 0;
+  const costAvoidedUsd = Number(((tokensSaved / 1000000) * 10.0).toFixed(4));
+  const precisionGainRatio = (m.precisionPct / 12.0).toFixed(1) + 'x';
+  const retryRatePct = m.totalCount > 0 ? Number(((m.staleRetries / m.totalCount) * 100).toFixed(1)) : 0.0;
+  const staleRetriesEliminated = Math.max(0, Math.round(turns * 0.185) - m.staleRetries);
+
   return {
+    hasRealData: true,
+    hasMeasuredTokens,
+    isSimulated: false,
     workloadTurns: turns,
-    memoryEnabled: { mode: 'SQLite AST & Event Memory', tokensUsed: memTokens, staleRetryRatePct: 0.0, retrievalPrecisionPct: m.precisionPct, astQualityScore: 100 },
+    memoryEnabled: { mode: 'SQLite AST & Event Memory', tokensUsed: memTokens, staleRetryRatePct: retryRatePct, retrievalPrecisionPct: m.precisionPct, astQualityScore: 100 },
     memoryDisabled: { mode: 'Stateless Monolithic File Re-read', tokensUsed: baseTokens, staleRetryRatePct: 18.5, retrievalPrecisionPct: 12.0, astQualityScore: 84 },
-    delta: { tokenReductionPct: Math.round((tokensSaved / baseTokens) * 100), costAvoidedUsd: Number(((tokensSaved / 1000000) * 10.0).toFixed(4)), retrievalPrecisionGainRatio: '7.8x', staleRetriesEliminated: Math.round(turns * 0.185) }
+    delta: {
+      tokenReductionPct,
+      tokenReductionBasis: hasMeasuredTokens ? 'measured' : 'estimated_typical_usage',
+      isEstimated: !hasMeasuredTokens,
+      costAvoidedUsd,
+      retrievalPrecisionGainRatio: precisionGainRatio,
+      staleRetriesEliminated
+    }
   };
 };
 
@@ -66,19 +134,37 @@ export const formatAblationCard = (a) => {
   const m = a.memoryEnabled;
   const d = a.memoryDisabled;
   const delta = a.delta;
+  const headerSuffix = a.hasRealData ? '[Live Project Telemetry]' : '[Reference Projection - Zero Local Tasks]';
   const lines = [
     '',
-    '\x1b[1m\x1b[36m⚡ [Chemical X] Persistent Memory Ablation Benchmark\x1b[0m',
-    `\x1b[90m${'─'.repeat(58)}\x1b[0m`,
+    `\x1b[1m\x1b[36m⚡ [Chemical X] Persistent Memory Ablation Benchmark ${headerSuffix}\x1b[0m`,
+    `\x1b[90m${'─'.repeat(58)}\x1b[0m`
+  ];
+
+  if (!a.hasRealData) {
+    lines.push(
+      '  \x1b[33mℹ Notice: Zero local task history recorded. Displaying reference projection.\x1b[0m',
+      '  \x1b[33m  Run team tasks and memory operations to generate live project benchmarks.\x1b[0m',
+      `\x1b[90m${'─'.repeat(58)}\x1b[0m`
+    );
+  }
+
+  const tokenReductionLabel = a.hasMeasuredTokens
+    ? `${delta.tokenReductionPct}% fewer tokens consumed (measured vs modeled baseline)`
+    : `${delta.tokenReductionPct}% fewer tokens consumed (estimated based on typical usage)`;
+  const costAvoidedSuffix = a.hasMeasuredTokens ? '' : ' (projected)';
+  const memoryTokensSuffix = a.hasMeasuredTokens ? '' : ' (est.)';
+
+  lines.push(
     `  \x1b[1mWorkload:\x1b[0m              ${a.workloadTurns} agent turns / tasks`,
-    `  \x1b[1mMemory Mode (SQLite):\x1b[0m  ${m.tokensUsed.toLocaleString()} tokens │ Precision: ${m.retrievalPrecisionPct}% │ Retry: ${m.staleRetryRatePct}%`,
-    `  \x1b[1mBaseline (Stateless):\x1b[0m  ${d.tokensUsed.toLocaleString()} tokens │ Precision: ${d.retrievalPrecisionPct}% │ Retry: ${d.staleRetryRatePct}%`,
+    `  \x1b[1mMemory Mode (SQLite):\x1b[0m  ${m.tokensUsed.toLocaleString()} tokens${memoryTokensSuffix} │ Precision: ${m.retrievalPrecisionPct}% │ Retry: ${m.staleRetryRatePct}%`,
+    `  \x1b[1mBaseline (Stateless):\x1b[0m  ${d.tokensUsed.toLocaleString()} tokens (modeled) │ Precision: ${d.retrievalPrecisionPct}% │ Retry: ${d.staleRetryRatePct}%`,
     `\x1b[90m${'─'.repeat(58)}\x1b[0m`,
-    `  \x1b[32m✔ Token Reduction:\x1b[0m     ${delta.tokenReductionPct}% fewer tokens consumed`,
-    `  \x1b[32m✔ Cost Avoided:\x1b[0m        $${delta.costAvoidedUsd.toFixed(4)} USD`,
+    `  \x1b[32m✔ Token Reduction:\x1b[0m     ${tokenReductionLabel}`,
+    `  \x1b[32m✔ Cost Avoided:\x1b[0m        ${delta.costAvoidedUsd.toFixed(4)} USD${costAvoidedSuffix}`,
     `  \x1b[32m✔ Precision Gain:\x1b[0m      ${delta.retrievalPrecisionGainRatio} higher retrieval precision per dollar`,
     `  \x1b[32m✔ Stale Retries:\x1b[0m       ${delta.staleRetriesEliminated} retries eliminated`,
     `\x1b[90m${'─'.repeat(58)}\x1b[0m\n`
-  ];
+  );
   return lines.join('\n');
 };

package/cli/team/team-memory.spec.js

@@ -68,7 +68,56 @@ test("runAblationComparison and formatAblationCard generate metrics card without
   assert.strictEqual(ablation.memoryEnabled.astQualityScore, 100);
   assert.strictEqual(ablation.memoryDisabled.astQualityScore, 84);
   assert.ok(ablation.delta.tokenReductionPct >= 90);
+  assert.strictEqual(ablation.hasRealData, false);
+  assert.strictEqual(ablation.isSimulated, true);
   const card = formatAblationCard(ablation);
   assert.ok(card.includes("Persistent Memory Ablation Benchmark"));
+  assert.ok(card.includes("Reference Projection"));
   assert.strictEqual(card.includes("—"), false);
 }));
+
+test("runAblationComparison computes dynamic metrics from live task and memory records", () => withTmpCwd((db) => {
+  db.prepare(`
+    INSERT INTO agent_tasks (title, status, prompt_tokens, completion_tokens, cost_usd, created_at, updated_at)
+    VALUES ('Refactor parser', 'done', 1500, 300, 0.05, 1000, 1000)
+  `).run();
+
+  recordMemoryInjection(db, { taskId: 1, provenance: "src/parser.ts", tokens: 200 });
+  recordMemoryUtilization(db, { taskId: 1, utilizedProvenance: ["src/parser.ts"], causedRetry: false });
+
+  const ablation = runAblationComparison(db);
+  assert.strictEqual(ablation.hasRealData, true);
+  assert.strictEqual(ablation.isSimulated, false);
+  assert.strictEqual(ablation.workloadTurns, 2);
+  assert.strictEqual(ablation.memoryEnabled.tokensUsed, 1800);
+  assert.ok(ablation.delta.tokenReductionPct > 0);
+  assert.ok(ablation.delta.retrievalPrecisionGainRatio.endsWith('x'));
+
+  const card = formatAblationCard(ablation);
+  assert.ok(card.includes("Live Project Telemetry"));
+  assert.ok(card.includes("measured vs modeled baseline"));
+  assert.strictEqual(ablation.hasMeasuredTokens, true);
+  assert.strictEqual(ablation.delta.isEstimated, false);
+  assert.strictEqual(ablation.delta.tokenReductionBasis, "measured");
+  assert.strictEqual(card.includes("—"), false);
+}));
+
+test("runAblationComparison marks token reduction as estimated when live tasks lack token counts", () => withTmpCwd((db) => {
+  db.prepare(`
+    INSERT INTO agent_tasks (title, status, created_at, updated_at)
+    VALUES ('Task without token telemetry', 'done', 1000, 1000)
+  `).run();
+
+  const ablation = runAblationComparison(db);
+  assert.strictEqual(ablation.hasRealData, true);
+  assert.strictEqual(ablation.hasMeasuredTokens, false);
+  assert.strictEqual(ablation.delta.isEstimated, true);
+  assert.strictEqual(ablation.delta.tokenReductionBasis, "estimated_typical_usage");
+  assert.strictEqual(ablation.delta.tokenReductionPct, 97);
+
+  const card = formatAblationCard(ablation);
+  assert.ok(card.includes("estimated based on typical usage"));
+  assert.ok(card.includes("(projected)"));
+  assert.strictEqual(card.includes("—"), false);
+}));
+

package/cli/team/team-multiprocess-concurrency.spec.js

@@ -129,7 +129,7 @@ test('swarm multi-process: lock automatically releases when holding worker proce
     import { openIndexDb } from '${path.resolve('cli/search-schema.js')}';
     import { requestFileLock } from '${path.resolve('cli/team/team-db-locks.js')}';
     const db = openIndexDb('${tmpDir}');
-    requestFileLock(db, '${testFile}', '@crashing-worker', { ttlMs: 3600000 });
+    requestFileLock(db, '${testFile}', '@crashing-worker', { ttlMs: 3600000, pid: process.pid });
     process.exit(1);
   `;
 

package/cli/tesseract.spec.js

@@ -27,7 +27,7 @@ test('tesseract: cli command execution succeeds with exit code 0', () => {
   const cliPath = path.resolve('cli/index.js');
   const res = spawnSync(process.execPath, [cliPath, 'tesseract'], {
     encoding: 'utf8',
-    timeout: 5000
+    timeout: 15000
   });
 
   assert.strictEqual(res.status, 0, 'CLI tesseract should exit with 0');
@@ -40,7 +40,7 @@ test('tesseract: cli aliases cube and matrix work identically', () => {
   for (const alias of ['cube', 'matrix']) {
     const res = spawnSync(process.execPath, [cliPath, alias], {
       encoding: 'utf8',
-      timeout: 5000
+      timeout: 15000
     });
     assert.strictEqual(res.status, 0, `CLI ${alias} should exit with 0`);
     assert.ok(res.stdout.includes('TESSERACT'), `CLI ${alias} should render Tesseract`);

package/cli/theme.js

@@ -34,6 +34,7 @@ export const ANSI = Object.freeze({
   LIME: '\x1b[38;2;163;230;53m',
   GREEN: '\x1b[32m',
   GOLD: '\x1b[38;2;251;191;36m',
+  YELLOW: '\x1b[38;2;251;191;36m',
   RED: '\x1b[38;2;239;68;68m',
   BOLD: '\x1b[1m',
   DIM: '\x1b[2m',

package/cli/trace.spec.js

@@ -0,0 +1,92 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  extractCalleesFromCode,
+  calculateCallTrace,
+  calculateBacktrace
+} from './search-queries-graph.js';
+import {
+  handleCallTraceCommand,
+  handleBacktraceCommand
+} from './search-commands-graph.js';
+import { openIndexDb, upsertFileIndex } from './search-db.js';
+
+describe('Call Trace & Backtrace Engine', () => {
+  it('extracts call expressions from code snippet', () => {
+    const code = `
+      const handleAction = async () => {
+        if (!canProceed.value) return;
+        state.value = { status: 'loading' };
+        await api.postOrder(items.value);
+        emit('success');
+      };
+    `;
+    const callees = extractCalleesFromCode(code);
+    assert.ok(callees.includes('api.postOrder'), 'Should extract api.postOrder');
+    assert.ok(callees.includes('emit'), 'Should extract emit');
+  });
+
+  it('calculates forward call trace gracefully on unknown or empty target', () => {
+    const db = openIndexDb();
+    const trace = calculateCallTrace(db, 'nonExistentSymbol', { maxDepth: 2 });
+    assert.equal(trace.target, 'nonExistentSymbol');
+    assert.equal(trace.totalCallees, 0);
+    assert.deepEqual(trace.callees, []);
+  });
+
+  it('calculates reverse backtrace using recursive imports CTE', () => {
+    const db = openIndexDb();
+
+    upsertFileIndex(db, {
+      path: 'src/controllers/trace-cart.ts',
+      mtime: Date.now(),
+      size: 400,
+      tier: 'hook',
+      lines: 40,
+      chars: 400,
+      symbols: [{ name: 'useTraceCartController', kind: 'const', isExport: true, startLine: 1, endLine: 40 }],
+      imports: []
+    });
+
+    upsertFileIndex(db, {
+      path: 'src/organisms/trace-cart.vue',
+      mtime: Date.now(),
+      size: 800,
+      tier: 'organism',
+      lines: 80,
+      chars: 800,
+      symbols: [{ name: 'TraceCartOrganism', kind: 'const', isExport: true, startLine: 1, endLine: 80 }],
+      imports: [
+        { importedSymbol: 'useTraceCartController', sourceModule: '@/controllers/trace-cart.ts', resolvedPath: 'src/controllers/trace-cart.ts', line: 3 }
+      ]
+    });
+
+    upsertFileIndex(db, {
+      path: 'src/views/trace-checkout.vue',
+      mtime: Date.now(),
+      size: 500,
+      tier: 'view',
+      lines: 50,
+      chars: 500,
+      symbols: [{ name: 'TraceCheckoutView', kind: 'const', isExport: true, startLine: 1, endLine: 50 }],
+      imports: [
+        { importedSymbol: 'TraceCartOrganism', sourceModule: '@/organisms/trace-cart.vue', resolvedPath: 'src/organisms/trace-cart.vue', line: 5 }
+      ]
+    });
+
+    const backtrace = calculateBacktrace(db, 'useTraceCartController', { maxDepth: 5 });
+    assert.equal(backtrace.target, 'useTraceCartController');
+    assert.ok(backtrace.totalCallers >= 2, `Expected at least 2 callers, got ${backtrace.totalCallers}`);
+    assert.ok(backtrace.chains.some((c) => c.includes('trace-checkout.vue')), 'Causal chain should reach root view');
+    assert.ok(backtrace.rootCallers.some((r) => r.tier === 'view'), 'Root callers should include view tier');
+  });
+
+  it('formats call trace and backtrace as JSON payloads', () => {
+    const db = openIndexDb();
+    const traceRes = handleCallTraceCommand(db, 'foo', { isJson: true, isCli: false });
+    assert.equal(traceRes.target, 'foo');
+
+    const backtraceRes = handleBacktraceCommand(db, 'foo', { isJson: true, isCli: false });
+    assert.equal(backtraceRes.target, 'foo');
+  });
+});

package/cli/verify-helpers.js

@@ -30,16 +30,59 @@ export const detectTypecheckCommand = (customCmd, cwd = process.cwd()) => {
   return `${pm} run typecheck`;
 };
 
-export const detectTestCommand = (customCmd, cwd = process.cwd()) => {
-  if (customCmd && customCmd.trim().length > 0) return customCmd.trim();
+export const detectTestCommand = (customCmd, cwd = process.cwd(), options = {}) => {
+  const target = options.target ? String(options.target).trim() : null;
+  const filter = options.filter ? String(options.filter).trim() : null;
+
+  if (customCmd && customCmd.trim().length > 0) {
+    let cmd = customCmd.trim();
+    if (target && !cmd.includes(target)) cmd += ` ${target}`;
+    if (filter && !cmd.includes(filter)) cmd += ` -t "${filter}"`;
+    return cmd;
+  }
+
   const pkg = loadLocalPackageJson(cwd);
   const scripts = (pkg && pkg.scripts) || {};
+  const deps = { ...(pkg?.dependencies || {}), ...(pkg?.devDependencies || {}) };
   const pm = resolvePackageManager(cwd);
 
+  const hasVitest = Boolean(
+    deps.vitest ||
+    (scripts.test && scripts.test.includes('vitest')) ||
+    fs.existsSync(path.join(cwd, 'vitest.config.ts')) ||
+    fs.existsSync(path.join(cwd, 'vitest.config.js'))
+  );
+
+  const hasNodeTest = Boolean(
+    scripts.test && (scripts.test.includes('node --test') || scripts.test.includes('node:test'))
+  );
+
+  if (target || filter) {
+    if (hasVitest) {
+      let vitestCmd = 'npx vitest run';
+      if (target) vitestCmd += ` ${target}`;
+      if (filter) vitestCmd += ` -t "${filter}"`;
+      return vitestCmd;
+    }
+
+    if (hasNodeTest || target?.endsWith('.spec.js') || target?.endsWith('.test.js')) {
+      let nodeCmd = 'node --test';
+      if (target) nodeCmd += ` ${target}`;
+      if (filter) nodeCmd += ` --test-name-pattern="${filter}"`;
+      return nodeCmd;
+    }
+
+    const baseTest = pm === 'yarn' ? 'yarn test' : `${pm} test`;
+    let args = '';
+    if (target) args += ` ${target}`;
+    if (filter) args += ` -t "${filter}"`;
+    return `${baseTest} --${args}`;
+  }
+
   const isLegitTest = scripts.test && !scripts.test.includes('no test specified');
   if (isLegitTest) return pm === 'yarn' ? 'yarn test' : `${pm} run test`;
 
-  if (fs.existsSync(path.join(cwd, 'vitest.config.ts')) || fs.existsSync(path.join(cwd, 'vitest.config.js'))) {
+  if (hasVitest) {
     return 'npx vitest run';
   }
 
@@ -91,37 +134,56 @@ export const parseTestOutput = (stdout = '', stderr = '', exitCode = 0) => {
   let skipped = 0;
   let checkmarkPasses = 0;
   let crossmarkFails = 0;
+  let hasRunnerSummary = false;
 
   for (const line of lines) {
     const clean = stripAnsi(line).trim();
     if (!clean) continue;
 
-    if (clean.startsWith('✔')) checkmarkPasses++;
+    if (clean.startsWith('✔') || clean.startsWith('✓')) checkmarkPasses++;
     if (clean.startsWith('✖') || clean.startsWith('FAIL ')) crossmarkFails++;
 
-    const nodeTests = clean.match(/(?:ℹ\s*)?tests\s+(\d+)/);
-    if (nodeTests) totalTests = parseInt(nodeTests[1], 10);
+    const isRunnerSummary = /^Tests:?\s+/i.test(clean);
+    if (isRunnerSummary) {
+      const passM = clean.match(/(\d+)\s+passed/i);
+      const failM = clean.match(/(\d+)\s+failed/i);
+      const skipM = clean.match(/(\d+)\s+(?:skipped|todo|pending)/i);
+      const totalParenM = clean.match(/\((\d+)\)/);
+      const totalWordM = clean.match(/(\d+)\s+total/i);
+
+      if (passM) passed = parseInt(passM[1], 10);
+      if (failM) failed = parseInt(failM[1], 10);
+      if (skipM) skipped = parseInt(skipM[1], 10);
+
+      if (totalParenM) totalTests = parseInt(totalParenM[1], 10);
+      else if (totalWordM) totalTests = parseInt(totalWordM[1], 10);
+      else totalTests = passed + failed + skipped;
+
+      hasRunnerSummary = true;
+      continue;
+    }
 
-    const nodePass = clean.match(/(?:ℹ\s*)?pass\s+(\d+)/);
-    if (nodePass) passed = parseInt(nodePass[1], 10);
+    if (!hasRunnerSummary) {
+      const nodeTests = clean.match(/^(?:[ℹ#]\s+)?tests\s+(\d+)$/i);
+      if (nodeTests) totalTests = parseInt(nodeTests[1], 10);
 
-    const nodeFail = clean.match(/(?:ℹ\s*)?fail\s+(\d+)/);
-    if (nodeFail) failed = parseInt(nodeFail[1], 10);
+      const nodePass = clean.match(/^(?:[ℹ#]\s+)?pass\s+(\d+)$/i);
+      if (nodePass) passed = parseInt(nodePass[1], 10);
 
-    const nodeSkip = clean.match(/(?:ℹ\s*)?(?:skipped|todo)\s+(\d+)/);
-    if (nodeSkip) skipped += parseInt(nodeSkip[1], 10);
+      const nodeFail = clean.match(/^(?:[ℹ#]\s+)?fail\s+(\d+)$/i);
+      if (nodeFail) failed = parseInt(nodeFail[1], 10);
 
-    const vitestMatch = clean.match(/Tests\s+(?:(\d+)\s+failed)?(?:,\s*)?(?:(\d+)\s+passed)?\s*\((\d+)\)/);
-    if (vitestMatch) {
-      if (vitestMatch[1]) failed = parseInt(vitestMatch[1], 10);
-      if (vitestMatch[2]) passed = parseInt(vitestMatch[2], 10);
-      if (vitestMatch[3]) totalTests = parseInt(vitestMatch[3], 10);
+      const nodeSkip = clean.match(/^(?:[ℹ#]\s+)?(?:skipped|todo)\s+(\d+)$/i);
+      if (nodeSkip) skipped += parseInt(nodeSkip[1], 10);
     }
   }
 
   if (passed === 0 && checkmarkPasses > 0) passed = checkmarkPasses;
   if (failed === 0 && crossmarkFails > 0) failed = crossmarkFails;
-  if (totalTests === 0) totalTests = passed + failed;
+  if (totalTests === 0) totalTests = passed + failed + skipped;
+  const isCleanExit = exitCode === 0 && failed === 0;
+  const isTestCountUnderflow = isCleanExit && totalTests < passed;
+  if (isTestCountUnderflow) totalTests = passed;
 
   const failures = [];
   if (exitCode !== 0 || failed > 0) {