impulso 0.23.0 → 0.25.0

package/harnesses/claude/hooks/task-exit.cjs

@@ -36,6 +36,105 @@ const IMPLEMENTER_ROLES = new Set(['implementer', 'implementer-frontend', 'imple
 
 const STATUS_BLOCK_LIMIT = 15;
 
+// --- Test command resolution ---
+//
+// Resolution ladder (consistent with hub ResolveTestCommand):
+//   local .impulso/config.json > IMPULSO_HOME/projects/<sha256>/config.json >
+//   IMPULSO_HOME/.impulso/ > HOME/.impulso/ >
+//   project heuristics (package.json scripts.test, Makefile test target,
+//   go.mod, Cargo.toml, pyproject.toml)
+//
+// Returns ("", "") when no test command can be resolved.
+// Never writes config/state files.
+
+const crypto = require('node:crypto');
+
+function userImpulsoDir() {
+  const home = process.env.IMPULSO_HOME || process.env.HOME;
+  if (!home) return null;
+  return path.join(home, '.impulso');
+}
+
+function projectConfigDir(projectDir) {
+  const userDir = userImpulsoDir();
+  if (!userDir) return null;
+  const abs = path.resolve(projectDir);
+  const hash = crypto.createHash('sha256').update(abs).digest('hex');
+  return path.join(userDir, 'projects', hash);
+}
+
+function readImpulsoConfig(dir) {
+  if (!dir) return null;
+  try {
+    const raw = fs.readFileSync(path.join(dir, 'config.json'), 'utf8');
+    const cfg = JSON.parse(raw);
+    return cfg && typeof cfg === 'object' && !Array.isArray(cfg) ? cfg : null;
+  } catch (_e) {
+    return null;
+  }
+}
+
+function detectTestCommand(projectDir) {
+  // 1. package.json with scripts.test
+  try {
+    const raw = fs.readFileSync(path.join(projectDir, 'package.json'), 'utf8');
+    const pkg = JSON.parse(raw);
+    if (pkg && pkg.scripts && typeof pkg.scripts.test === 'string') {
+      return 'npm test';
+    }
+  } catch (_e) {
+    /* continue */
+  }
+
+  // 2. Makefile with test: target
+  try {
+    const raw = fs.readFileSync(path.join(projectDir, 'Makefile'), 'utf8');
+    if (/^test:/m.test(raw)) return 'make test';
+  } catch (_e) {
+    /* continue */
+  }
+
+  // 3. go.mod
+  if (fs.existsSync(path.join(projectDir, 'go.mod'))) return 'go test ./...';
+
+  // 4. Cargo.toml
+  if (fs.existsSync(path.join(projectDir, 'Cargo.toml'))) return 'cargo test';
+
+  // 5. pyproject.toml
+  if (fs.existsSync(path.join(projectDir, 'pyproject.toml'))) return 'pytest';
+
+  return '';
+}
+
+function resolveTestCommand(projectDir) {
+  // 1. Local config (.impulso/config.json)
+  const localCfg = readImpulsoConfig(path.join(projectDir, '.impulso'));
+  if (localCfg && typeof localCfg.test_cmd === 'string' && localCfg.test_cmd) {
+    return localCfg.test_cmd;
+  }
+
+  // 2. Project-specific external config (~/.impulso/projects/<hash>/config.json)
+  const projCfgDir = projectConfigDir(projectDir);
+  if (projCfgDir) {
+    const projCfg = readImpulsoConfig(projCfgDir);
+    if (projCfg && typeof projCfg.test_cmd === 'string' && projCfg.test_cmd) {
+      return projCfg.test_cmd;
+    }
+  }
+
+  // 3. User config (IMPULSO_HOME or HOME .impulso/config.json)
+  const userDir = userImpulsoDir();
+  if (userDir) {
+    const userCfg = readImpulsoConfig(userDir);
+    if (userCfg && typeof userCfg.test_cmd === 'string' && userCfg.test_cmd) {
+      return userCfg.test_cmd;
+    }
+  }
+
+  // 4. Project heuristics
+  return detectTestCommand(projectDir);
+}
+
 function reportLineCount(reportText) {
   if (!reportText || typeof reportText !== 'string') return 0;
   const lines = reportText.split('\n');
@@ -116,6 +215,12 @@ function main() {
         return;
       }
 
+      // Resolve test command — skip TDD gate if none is resolvable
+      if (!resolveTestCommand(cwd)) {
+        process.exit(0);
+        return;
+      }
+
       // Read state non-mutatively
       let slug;
       try {
@@ -186,4 +291,4 @@ function main() {
 
 if (require.main === module) main();
 
-module.exports = { reportLineCount, violatesLimit };
+module.exports = { reportLineCount, violatesLimit, resolveTestCommand, detectTestCommand };

package/harnesses/claude/hooks/tdd-observer.cjs

@@ -19,10 +19,64 @@
 
 const fs = require('node:fs');
 const path = require('node:path');
+const crypto = require('node:crypto');
 const { spawnSync } = require('node:child_process');
 
 const GATE_REL = path.resolve(__dirname, '..', '..', '..', 'scripts', 'impulso-hub.cjs');
 
+function userImpulsoDir() {
+  const home = process.env.IMPULSO_HOME || process.env.HOME;
+  if (!home) return null;
+  return path.join(home, '.impulso');
+}
+
+function projectConfigDir(projectDir) {
+  const userDir = userImpulsoDir();
+  if (!userDir) return null;
+  const abs = path.resolve(projectDir);
+  const hash = crypto.createHash('sha256').update(abs).digest('hex');
+  return path.join(userDir, 'projects', hash);
+}
+
+function readImpulsoConfig(dir) {
+  if (!dir) return null;
+  try {
+    const raw = fs.readFileSync(path.join(dir, 'config.json'), 'utf8');
+    const cfg = JSON.parse(raw);
+    return cfg && typeof cfg === 'object' && !Array.isArray(cfg) ? cfg : null;
+  } catch (_e) {
+    return null;
+  }
+}
+
+function resolveTestCommand(projectDir) {
+  // 1. Local config (.impulso/config.json)
+  const localCfg = readImpulsoConfig(path.join(projectDir, '.impulso'));
+  if (localCfg && typeof localCfg.test_cmd === 'string' && localCfg.test_cmd) {
+    return localCfg.test_cmd;
+  }
+
+  // 2. Project-specific external config
+  const projCfgDir = projectConfigDir(projectDir);
+  if (projCfgDir) {
+    const projCfg = readImpulsoConfig(projCfgDir);
+    if (projCfg && typeof projCfg.test_cmd === 'string' && projCfg.test_cmd) {
+      return projCfg.test_cmd;
+    }
+  }
+
+  // 3. User config
+  const userDir = userImpulsoDir();
+  if (userDir) {
+    const userCfg = readImpulsoConfig(userDir);
+    if (userCfg && typeof userCfg.test_cmd === 'string' && userCfg.test_cmd) {
+      return userCfg.test_cmd;
+    }
+  }
+
+  return null;
+}
+
 function main() {
   let done = false;
   const chunks = [];
@@ -50,17 +104,8 @@ function main() {
         return;
       }
 
-      // Read config to get test_cmd
-      const configPath = path.join(cwd, '.impulso', 'config.json');
-      let config;
-      try {
-        config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
-      } catch (_e) {
-        process.exit(0);
-        return;
-      }
-
-      const testCmd = config.test_cmd;
+      // Resolve test_cmd from config ladder
+      const testCmd = resolveTestCommand(cwd);
       if (!testCmd || !command.includes(testCmd)) {
         process.exit(0);
         return;

package/harnesses/opencode/telematics/plugin.js

@@ -29,10 +29,15 @@ function defaultCreateTelematics(ctx) {
   // Record the raw sessionId before sanitization for sessionIdSource
   const rawSessionId = ctx.sessionID || null;
 
+  // Use process.pid as stable fallback when ctx.sessionID is absent.
+  // Prevents per-init UUID generation that creates a new log directory
+  // every time the plugin initializes without a native session ID.
+  const stableSessionId = ctx.sessionID || String(process.pid);
+
   return {
     telematics: createTelematics({
       harness: 'opencode',
-      sessionId: ctx.sessionID || null,
+      sessionId: stableSessionId,
       processId: process.pid,
       cwd: ctx.directory || process.cwd(),
       home,
@@ -130,10 +135,18 @@ export async function ImpulsoTelematicsPlugin(ctx, _createTelematics) {
       status = output.metadata.exitCode === 0 ? 'success' : 'error';
     }
 
+    const outputSummary = output
+      ? {
+          title: output.title,
+          responseSize: typeof output.output === 'string' ? output.output.length : undefined,
+          preview: typeof output.output === 'string' ? output.output.slice(0, 200) : undefined,
+        }
+      : null;
+
     t.emit('tool.completed', {
       toolName: input.tool,
       toolUseId: input.callID,
-      output,
+      output: outputSummary,
       durationMs,
       status,
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "impulso",
-  "version": "0.23.0",
+  "version": "0.25.0",
   "description": "Impulso — plugin bundle for opencode and Claude Code: Plannotator skills + Impulso-DirectSpeech (rethemed ex-Caveman). Harness-neutral repo; per-harness glue under harnesses/.",
   "type": "module",
   "main": "harnesses/opencode/plugin.js",
@@ -65,7 +65,8 @@
     "package.json",
     "README.md",
     "harnesses/opencode/telematics/",
-    "shared/telematics.cjs"
+    "shared/telematics.cjs",
+    "shared/scout-dispatch.cjs"
   ],
   "dependencies": {
     "@opencode-ai/plugin": "^1.17.14"

package/scripts/install-hub.js

@@ -72,13 +72,54 @@ export async function installHub({
   return { target, updated: true, destination, version: packageVersion };
 }
 
+/**
+ * Installs the scout dispatch bridge (shared/scout-dispatch.cjs) as an
+ * executable on PATH at ~/.local/bin/impulso-scout-dispatch. Uses the same
+ * atomic-temp-rename pattern as installHub. Idempotent: skips if the
+ * existing file is identical (checked by size + mtime heuristic).
+ */
+export async function installScoutDispatch({
+  packageRoot = PACKAGE_ROOT,
+  destination = path.join(os.homedir(), '.local', 'bin', 'impulso-scout-dispatch'),
+} = {}) {
+  const source = path.join(packageRoot, 'shared', 'scout-dispatch.cjs');
+  await stat(source);
+
+  // Simple idempotency check: if destination exists and has same size as source, skip
+  try {
+    const srcStat = await stat(source);
+    const dstStat = await stat(destination);
+    if (dstStat.size === srcStat.size) {
+      return { updated: false, destination };
+    }
+  } catch (_e) {
+    // destination absent — fall through to copy
+  }
+
+  await mkdir(path.dirname(destination), { recursive: true });
+  const tempDir = await mkdtemp(path.join(path.dirname(destination), '.impulso-scout-'));
+  const temporary = path.join(tempDir, 'impulso-scout-dispatch');
+  try {
+    await copyFile(source, temporary);
+    await chmod(temporary, 0o755);
+    await rename(temporary, destination);
+  } finally {
+    await rm(tempDir, { recursive: true, force: true });
+  }
+  return { updated: true, destination };
+}
+
 if (process.argv[1] === fileURLToPath(import.meta.url)) {
   try {
-    const result = await installHub();
-    const action = result.updated ? 'Installed' : 'Already installed';
+    const hubResult = await installHub();
+    const hubAction = hubResult.updated ? 'Installed' : 'Already installed';
     console.log(
-      `    ${action} impulso-hub ${result.version} (${result.target}) -> ${result.destination}`,
+      `    ${hubAction} impulso-hub ${hubResult.version} (${hubResult.target}) -> ${hubResult.destination}`,
     );
+
+    const scoutResult = await installScoutDispatch();
+    const scoutAction = scoutResult.updated ? 'Installed' : 'Already installed';
+    console.log(`    ${scoutAction} impulso-scout-dispatch -> ${scoutResult.destination}`);
   } catch (error) {
     console.error(`ERROR: ${error.message}`);
     process.exitCode = 1;

package/shared/scout-dispatch.cjs

@@ -0,0 +1,499 @@
+#!/usr/bin/env node
+/**
+ * impulso-scout-dispatch — harness-owned synchronous read-only scout bridge.
+ *
+ * Launched by impulso-hub init when static test detection fails. Uses the
+ * installed harness (opencode or claude) to dispatch the scout subagent
+ * synchronously, producing a validated ScoutReport.
+ *
+ * Usage:
+ *   impulso-scout-dispatch --slug <slug> --workspace <abs-path> --timeout-ms <n>
+ *   stdin: {"schemaVersion":1,"slug":"...","workspace":"..."}
+ *   stdout: ScoutReport JSON
+ *   exit 0 on success, nonzero on failure
+ *
+ * Report path: <workspace>/reports/scout.json
+ */
+
+const { spawnSync } = require('node:child_process');
+const { existsSync, mkdirSync, readFileSync, writeFileSync } = require('node:fs');
+const { resolve, join, dirname } = require('node:path');
+
+// --- CLI argument parsing ---
+
+function usage() {
+  process.stderr.write(
+    'Usage: impulso-scout-dispatch --slug <slug> --workspace <abs-path> [--timeout-ms <n>]\n',
+  );
+  process.exit(2);
+}
+
+let slug = '';
+let workspace = '';
+let timeoutMs = 180_000; // default 3 min
+
+// Manual arg parsing (node:util parseArgs needs node 18.3+)
+const args = process.argv.slice(2);
+for (let i = 0; i < args.length; i++) {
+  switch (args[i]) {
+    case '--slug':
+      slug = args[++i] || '';
+      break;
+    case '--workspace':
+      workspace = args[++i] || '';
+      break;
+    case '--timeout-ms':
+      timeoutMs = parseInt(args[++i] || '180000', 10);
+      break;
+    case '-h':
+    case '--help':
+      usage();
+      break;
+    default:
+      process.stderr.write(`Unknown flag: ${args[i]}\n`);
+      usage();
+  }
+}
+
+if (!slug || !workspace) {
+  usage();
+}
+
+const absWorkspace = resolve(workspace);
+const reportPath = join(absWorkspace, 'reports', 'scout.json');
+
+// --- Stdin payload (optional validation) ---
+
+let stdinPayload = null;
+try {
+  // Read synchronously from stdin if data is available
+  // For piped input, readFileSync('/dev/stdin') works on Linux
+  const stdinData = readFileSync('/dev/stdin', 'utf8').trim();
+  if (stdinData) {
+    stdinPayload = JSON.parse(stdinData);
+  }
+} catch {
+  // stdin may not be available — that's OK
+}
+void stdinPayload; // may be used in future for payload validation
+
+// --- Detect harness ---
+
+function detectHarness() {
+  // Prefer opencode (primary harness), fall back to claude
+  const opencodeCheck = spawnSync('which', ['opencode'], {
+    stdio: 'pipe',
+    timeout: 5000,
+  });
+  if (opencodeCheck.status === 0 && opencodeCheck.stdout.toString().trim()) {
+    return 'opencode';
+  }
+  const claudeCheck = spawnSync('which', ['claude'], {
+    stdio: 'pipe',
+    timeout: 5000,
+  });
+  if (claudeCheck.status === 0 && claudeCheck.stdout.toString().trim()) {
+    return 'claude';
+  }
+  return null;
+}
+
+// --- Dispatch via opencode ---
+
+function dispatchOpenCode() {
+  // Ensure reports dir exists
+  mkdirSync(dirname(reportPath), { recursive: true });
+
+  // Write the initial context file that scout will read
+  const contextPath = join(absWorkspace, 'context.md');
+  const contextContent = [
+    `# Scout reconnaissance context`,
+    `slug: ${slug}`,
+    `workspace: ${absWorkspace}`,
+    `task: Determine the test framework used in this project. Look for test files, test configuration (package.json scripts.test, Makefile test target, go.mod, Cargo.toml, pyproject.toml, etc.). Report each finding with path:line refs.`,
+    ``,
+  ].join('\n');
+  writeFileSync(contextPath, contextContent, 'utf8');
+
+  // Build scout prompt
+  const prompt = [
+    'You are the scout subagent (read-only).',
+    'Explore the project at the current directory.',
+    'Inspect manifests (package.json, Makefile, go.mod, Cargo.toml, pyproject.toml),',
+    'package scripts, .github/workflows, test configs, targeted source/test directories,',
+    'and monorepo boundaries.',
+    'Determine what test command to use (or conclude no tests are present).',
+    'Write a JSON scout report to ' + reportPath + ' with this exact v2 schema:',
+    '{ "schemaVersion": 2, "slug": "' +
+      slug +
+      '", "reportPath": "' +
+      reportPath +
+      '", "command": "the test command", "noTest": false, "noTestJustification": "", "workingDirectory": "relative/path", "confidence": "high|medium|low", "evidence": [ { "ref": "path/to/file:lineNumber", "finding": "description" } ], "concerns": [], "findings": [ { "ref": "path/to/file:lineNumber", "finding": "description" } ] }',
+    '- "command": exact test command string (e.g. "npm test", "go test ./..."). Empty ONLY if noTest is true.',
+    '- "noTest": true ONLY when no test framework can be detected. When true, "command" must be empty.',
+    '- "noTestJustification": required when noTest is true. Explain why no tests were found.',
+    '- "workingDirectory": relative path from project root where the command should run (e.g. "packages/web/", "."). Must be relative, no ".." traversal.',
+    '- "confidence": high, medium, or low.',
+    '- "evidence": array of path:line refs pointing to manifests/configs that support your conclusion.',
+    '- "concerns": array of strings noting any caveats or limitations.',
+    '- "findings": general path:line observations about the project structure.',
+    'The "ref" field MUST use path:line format (e.g. main.go:42).',
+    'Do NOT modify any source files. Only read and write the report.',
+  ].join('\n');
+
+  const result = spawnSync(
+    'opencode',
+    ['run', '--agent', 'scout', '--format', 'json', '--dir', dirname(absWorkspace), prompt],
+    {
+      stdio: ['pipe', 'pipe', 'pipe'],
+      timeout: timeoutMs,
+      env: { ...process.env },
+      maxBuffer: 10 * 1024 * 1024, // 10MB
+    },
+  );
+
+  return {
+    exitCode: result.status ?? 1,
+    stderr: result.stderr?.toString() || '',
+    error: result.error,
+  };
+}
+
+// --- Dispatch via claude ---
+
+function dispatchClaude() {
+  mkdirSync(dirname(reportPath), { recursive: true });
+
+  const contextPath = join(absWorkspace, 'context.md');
+  const contextContent = [
+    `# Scout reconnaissance context`,
+    `slug: ${slug}`,
+    `workspace: ${absWorkspace}`,
+    `task: Determine the test framework used in this project. Look for test files, test configuration. Report each finding with path:line refs.`,
+    ``,
+  ].join('\n');
+  writeFileSync(contextPath, contextContent, 'utf8');
+
+  const prompt = [
+    'You are the scout subagent (read-only).',
+    'Explore the project at the current directory.',
+    'Inspect manifests (package.json, Makefile, go.mod, Cargo.toml, pyproject.toml),',
+    'package scripts, .github/workflows, test configs, targeted source/test directories,',
+    'and monorepo boundaries.',
+    'Determine what test command to use (or conclude no tests are present).',
+    'Write a JSON scout report to ' + reportPath + ' with this exact v2 schema:',
+    '{ "schemaVersion": 2, "slug": "' +
+      slug +
+      '", "reportPath": "' +
+      reportPath +
+      '", "command": "the test command", "noTest": false, "noTestJustification": "", "workingDirectory": "relative/path", "confidence": "high|medium|low", "evidence": [ { "ref": "path/to/file:lineNumber", "finding": "description" } ], "concerns": [], "findings": [ { "ref": "path/to/file:lineNumber", "finding": "description" } ] }',
+    '- "command": exact test command string (e.g. "npm test", "go test ./..."). Empty ONLY if noTest is true.',
+    '- "noTest": true ONLY when no test framework can be detected. When true, "command" must be empty.',
+    '- "noTestJustification": required when noTest is true.',
+    '- "workingDirectory": relative path from project root where command should run.',
+    '- "confidence": high, medium, or low.',
+    '- "evidence": array of path:line refs to manifests/configs.',
+    '- "concerns": array of caveats or limitations.',
+    '- "findings": general path:line observations.',
+    'The "ref" field MUST use path:line format (e.g. main.go:42).',
+    'Do NOT modify any source files. Only read and write the report.',
+  ].join('\n');
+
+  const result = spawnSync(
+    'claude',
+    ['--agent', 'scout', '-p', '--output-format', 'json', prompt],
+    {
+      cwd: dirname(absWorkspace),
+      stdio: ['pipe', 'pipe', 'pipe'],
+      timeout: timeoutMs,
+      env: { ...process.env },
+      maxBuffer: 10 * 1024 * 1024,
+    },
+  );
+
+  return {
+    exitCode: result.status ?? 1,
+    stderr: result.stderr?.toString() || '',
+    error: result.error,
+  };
+}
+
+// --- Output helpers ---
+
+function fail(message) {
+  process.stderr.write(`impulso-scout-dispatch: ${message}\n`);
+  process.exit(1);
+}
+
+function outputReport(report) {
+  process.stdout.write(JSON.stringify(report));
+  process.exit(0);
+}
+
+// --- Validate scout report ---
+
+function validateReport(raw) {
+  try {
+    const report = JSON.parse(raw);
+
+    if (!report || typeof report !== 'object') {
+      return { valid: false, error: 'report is not a JSON object' };
+    }
+
+    if (report.schemaVersion !== 2) {
+      return {
+        valid: false,
+        error: `invalid schemaVersion: ${report.schemaVersion} (must be 2)`,
+      };
+    }
+
+    if (!report.slug || report.slug !== slug) {
+      return {
+        valid: false,
+        error: `slug mismatch: ${report.slug || '(empty)'} vs ${slug}`,
+      };
+    }
+
+    if (!report.reportPath) {
+      return { valid: false, error: 'missing reportPath' };
+    }
+
+    // Validate that reportPath matches the expected workspace path
+    const resolvedReturned = resolve(report.reportPath);
+    const resolvedExpected = resolve(reportPath);
+    if (resolvedReturned !== resolvedExpected) {
+      return {
+        valid: false,
+        error: `reportPath mismatch: returned ${report.reportPath}, expected ${reportPath}`,
+      };
+    }
+
+    // v2: command/noTest exclusivity
+    if (report.noTest === true) {
+      if (report.command && report.command !== '') {
+        return { valid: false, error: 'noTest=true and command are mutually exclusive' };
+      }
+      if (!report.noTestJustification || report.noTestJustification.trim() === '') {
+        return { valid: false, error: 'noTestJustification is required when noTest=true' };
+      }
+    } else {
+      if (!report.command || report.command.trim() === '') {
+        return { valid: false, error: 'command is required when noTest is false or absent' };
+      }
+    }
+
+    // v2: workingDirectory
+    if (!report.workingDirectory || report.workingDirectory.trim() === '') {
+      return { valid: false, error: 'workingDirectory is required' };
+    }
+    const wd = report.workingDirectory;
+    if (require('node:path').isAbsolute(wd)) {
+      return { valid: false, error: `workingDirectory must be relative, got absolute: ${wd}` };
+    }
+    if (wd.includes('..')) {
+      return { valid: false, error: `workingDirectory contains path traversal: ${wd}` };
+    }
+
+    // v2: confidence enum
+    if (!['low', 'medium', 'high'].includes(report.confidence)) {
+      return {
+        valid: false,
+        error: `invalid confidence: ${report.confidence} (must be low, medium, or high)`,
+      };
+    }
+
+    // v2: evidence array (can be empty)
+    if (!Array.isArray(report.evidence)) {
+      return { valid: false, error: 'evidence must be an array' };
+    }
+    for (let i = 0; i < report.evidence.length; i++) {
+      const f = report.evidence[i];
+      if (!f.ref || !/^[^/].+:\d+$/.test(f.ref)) {
+        return {
+          valid: false,
+          error: `evidence[${i}] has invalid ref: ${JSON.stringify(f.ref)} — must be path:line format`,
+        };
+      }
+      if (!f.finding || typeof f.finding !== 'string' || f.finding.trim() === '') {
+        return {
+          valid: false,
+          error: `evidence[${i}] has empty finding text`,
+        };
+      }
+    }
+
+    // v2: concerns is optional (can be absent or array)
+    if (report.concerns !== undefined && !Array.isArray(report.concerns)) {
+      return { valid: false, error: 'concerns must be an array if present' };
+    }
+
+    // findings: non-empty array
+    if (!Array.isArray(report.findings) || report.findings.length === 0) {
+      return {
+        valid: false,
+        error: 'findings must be a non-empty array',
+      };
+    }
+
+    for (let i = 0; i < report.findings.length; i++) {
+      const f = report.findings[i];
+      if (!f.ref || !/^[^/].+:\d+$/.test(f.ref)) {
+        return {
+          valid: false,
+          error: `finding[${i}] has invalid ref: ${JSON.stringify(f.ref)} — must be path:line format`,
+        };
+      }
+      if (!f.finding || typeof f.finding !== 'string' || f.finding.trim() === '') {
+        return {
+          valid: false,
+          error: `finding[${i}] has empty finding text`,
+        };
+      }
+    }
+
+    return { valid: true, report };
+  } catch (e) {
+    return { valid: false, error: `invalid JSON: ${e.message}` };
+  }
+}
+
+// --- Main ---
+
+function main() {
+  // 1. Check for existing validated report
+  if (existsSync(reportPath)) {
+    try {
+      const raw = readFileSync(reportPath, 'utf8');
+      const { valid, report } = validateReport(raw);
+      if (valid) {
+        outputReport(report);
+      }
+      // Invalid existing report — fall through to dispatch
+    } catch {
+      // Unreadable — fall through
+    }
+  }
+
+  // 2. Detect and dispatch via harness
+  const harness = detectHarness();
+  if (!harness) {
+    fail('no harness found on PATH (opencode or claude required for scout dispatch)');
+  }
+
+  const maxAttempts = 2;
+
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    // emit telematics if enabled
+    emitLifecycle('scout.dispatch', 'started', { attempt });
+
+    let result;
+    if (harness === 'opencode') {
+      result = dispatchOpenCode();
+    } else {
+      result = dispatchClaude();
+    }
+
+    if (result.error) {
+      const reason = result.error.message || String(result.error);
+      emitLifecycle('scout.dispatch', 'failed', { attempt, reason });
+      if (attempt < maxAttempts) {
+        emitLifecycle('scout.dispatch', 'retry', {
+          attempt,
+          nextAttempt: attempt + 1,
+        });
+      }
+      continue;
+    }
+
+    // Check if report was produced
+    if (existsSync(reportPath)) {
+      try {
+        const raw = readFileSync(reportPath, 'utf8');
+        const { valid, report, error } = validateReport(raw);
+        if (valid) {
+          emitLifecycle('scout.dispatch', 'completed', {
+            attempt,
+            findingCount: report.findings.length,
+          });
+          outputReport(report);
+        }
+        if (attempt < maxAttempts) {
+          emitLifecycle('scout.dispatch', 'retry', {
+            attempt,
+            reason: `invalid report: ${error}`,
+          });
+        }
+      } catch (e) {
+        if (attempt < maxAttempts) {
+          emitLifecycle('scout.dispatch', 'retry', {
+            attempt,
+            reason: `report read error: ${e.message}`,
+          });
+        }
+      }
+    } else {
+      if (attempt < maxAttempts) {
+        emitLifecycle('scout.dispatch', 'retry', {
+          attempt,
+          reason: 'no report produced',
+        });
+      }
+    }
+
+    // continue loop for retry
+  }
+
+  // All attempts exhausted
+  emitLifecycle('scout.dispatch', 'failed', {
+    attempt: maxAttempts,
+    reason: 'all dispatch attempts exhausted',
+    harness,
+  });
+  fail(`scout dispatch failed after ${maxAttempts} attempts (${harness})`);
+}
+
+// --- Telematics ---
+// Uses existing shared/telematics.cjs module — config-gated: only emits
+// when $HOME/.impulso/config.json has telematics.enabled = true.
+// Redacts sensitive keys and patterns. Fails silently — telematics must
+// never disrupt the scout dispatch.
+
+let _telemetry = null;
+
+function getTelemetry() {
+  if (_telemetry) return _telemetry;
+  try {
+    const { createTelematics } = require('./telematics.cjs');
+    const os = require('node:os');
+    const path = require('node:path');
+    const crypto = require('node:crypto');
+    const home = process.env.IMPULSO_HOME || path.join(os.homedir(), '.impulso');
+    _telemetry = createTelematics({
+      harness: 'scout-dispatch',
+      sessionId: 'scout-' + slug + '-' + Date.now(),
+      processId: process.pid,
+      cwd: absWorkspace,
+      home: home,
+      now: () => new Date().toISOString(),
+      uuid: () => crypto.randomUUID(),
+      fs: require('node:fs'),
+    });
+  } catch (_) {
+    // Module unavailable or config load failed — create no-op fallback
+    _telemetry = {
+      enabled: false,
+      sessionId: null,
+      emit: () => {},
+      close: () => {},
+    };
+  }
+  return _telemetry;
+}
+
+function emitLifecycle(eventType, phase, meta) {
+  const tm = getTelemetry();
+  if (!tm.enabled) return;
+  tm.emit(eventType + '.' + phase, meta || {});
+}
+
+main();