@geraldmaron/construct 1.0.0 → 1.0.2

package/lib/hooks/stop-notify.mjs

@@ -2,31 +2,121 @@
 /**
  * lib/hooks/stop-notify.mjs — Stop notify hook — emits a session summary notification when Claude stops.
  *
- * Runs as a Stop hook. Summarizes the session work, active workflow state, and efficiency signals into a final message written to stdout for the user.
+ * Runs as a Stop hook. Summarizes the session work and efficiency
+ * signals into a final message written to stdout for the user.
+ *
+ * Per-transcript checkpoints in ~/.cx/transcript-checkpoints.json track the last processed
+ * line so every assistant turn in a Stop cycle is priced, not just the final one.
+ * Cost is computed via estimateUsageCost using the model ID from each transcript entry.
+ *
+ * @p95ms 500
+ * @maxBlockingScope Stop
  */
-import { readFileSync, writeFileSync, existsSync, appendFileSync, statSync } from 'fs';
+import { readFileSync, writeFileSync, existsSync, appendFileSync, mkdirSync } from 'fs';
 import { execSync } from 'child_process';
 import { homedir } from 'os';
-import { join } from 'path';
-import { loadWorkflow, summarizeWorkflow, alignmentFindings } from '../workflow-state.mjs';
+import { join, dirname } from 'path';
+import { listSessions, loadSession, updateSession } from '../session-store.mjs';
+import { captureSessionArtifacts } from '../artifact-capture.mjs';
+import { appendSessionStats } from '../memory-stats.mjs';
+import { estimateUsageCost } from '../telemetry/model-pricing-catalog.mjs';
 
-function readLastTranscriptUsage(transcriptPath) {
+function loadTranscriptCheckpoints(checkpointPath) {
   try {
-    if (!transcriptPath || !existsSync(transcriptPath)) return null;
-    const size = statSync(transcriptPath).size;
-    const readSize = Math.min(size, 256 * 1024);
+    if (!existsSync(checkpointPath)) return {};
+    return JSON.parse(readFileSync(checkpointPath, 'utf8')) || {};
+  } catch {
+    return {};
+  }
+}
+
+function saveTranscriptCheckpoints(checkpointPath, data) {
+  try {
+    mkdirSync(dirname(checkpointPath), { recursive: true });
+    writeFileSync(checkpointPath, JSON.stringify(data));
+  } catch { /* non-critical */ }
+}
+
+function collectUnprocessedUsage(transcriptPath, checkpoints) {
+  const entries = [];
+  try {
+    if (!transcriptPath || !existsSync(transcriptPath)) return entries;
     const content = readFileSync(transcriptPath, 'utf8');
-    const tail = content.slice(-readSize);
-    const lines = tail.split(/\r?\n/).filter(Boolean);
-    for (let i = lines.length - 1; i >= 0; i--) {
-      try {
-        const obj = JSON.parse(lines[i]);
-        const usage = obj?.message?.usage || obj?.usage;
-        if (usage && (usage.input_tokens || usage.output_tokens)) return usage;
-      } catch { /* skip */ }
+    const lines = content.split(/\r?\n/);
+    const state = checkpoints[transcriptPath] || { lastLine: 0 };
+
+    // Reset on truncation/rotation rather than skipping lines or double-counting.
+    const startLine = state.lastLine > lines.length ? 0 : state.lastLine;
+
+    for (let i = startLine; i < lines.length; i++) {
+      const line = lines[i];
+      if (!line) continue;
+      let obj;
+      try { obj = JSON.parse(line); } catch { continue; }
+      const usage = obj?.message?.usage || obj?.usage;
+      if (!usage) continue;
+      if (!usage.input_tokens && !usage.output_tokens && !usage.cache_read_input_tokens && !usage.cache_creation_input_tokens) continue;
+      const model =
+        obj?.message?.model ||
+        obj?.model ||
+        obj?.message?.modelID ||
+        obj?.modelID ||
+        null;
+      const ts = obj?.timestamp || obj?.message?.timestamp || null;
+      entries.push({ usage, model, ts });
     }
-  } catch { /* best effort */ }
-  return null;
+    checkpoints[transcriptPath] = { lastLine: lines.length };
+  } catch { /* non-critical */ }
+  return entries;
+}
+
+function priceUsage(model, usage) {
+  const inputTokens = Number(usage?.input_tokens || 0);
+  const outputTokens = Number(usage?.output_tokens || 0);
+  const reasoningTokens = Number(
+    usage?.reasoning_tokens ||
+    usage?.output_token_details?.reasoning ||
+    usage?.completion_tokens_details?.reasoning_tokens ||
+    0,
+  );
+  const cacheReadInputTokens = Number(usage?.cache_read_input_tokens || 0);
+  const cacheCreation5mInputTokens = Number(
+    usage?.cache_creation?.ephemeral_5m_input_tokens ||
+    usage?.cache_creation_5m_input_tokens ||
+    0,
+  );
+  const cacheCreation1hInputTokens = Number(
+    usage?.cache_creation?.ephemeral_1h_input_tokens ||
+    usage?.cache_creation_1h_input_tokens ||
+    0,
+  );
+  const explicitCacheCreationInputTokens = Number(usage?.cache_creation_input_tokens || 0);
+  const cacheCreationInputTokens =
+    explicitCacheCreationInputTokens ||
+    (cacheCreation5mInputTokens + cacheCreation1hInputTokens);
+
+  const pricing = estimateUsageCost(model, {
+    inputTokens,
+    outputTokens,
+    reasoningTokens,
+    cacheReadInputTokens,
+    cacheCreationInputTokens,
+    cacheCreation5mInputTokens,
+    cacheCreation1hInputTokens,
+  });
+
+  return {
+    inputTokens,
+    outputTokens,
+    reasoningTokens,
+    cacheReadInputTokens,
+    cacheCreationInputTokens,
+    cacheCreation5mInputTokens,
+    cacheCreation1hInputTokens,
+    costUsd: pricing.costUsd || 0,
+    costSource: pricing.costSource,
+    modelName: pricing.modelName || model || null,
+  };
 }
 
 function resolveAttribution(workflow) {
@@ -40,9 +130,8 @@ function resolveAttribution(workflow) {
   }
 }
 
-// Stop hooks must echo stdin to stdout
 let raw = '';
-try { raw = readFileSync(0, 'utf8'); } catch { /* no stdin */ }
+try { raw = readFileSync(0, 'utf8'); } catch { /* non-critical */ }
 if (raw) process.stdout.write(raw);
 
 const home = homedir();
@@ -51,108 +140,105 @@ const warnFlagsPath = join(home, '.cx', 'warn-flags.txt');
 const countPath = join(home, '.cx', 'files-changed-count.txt');
 const costLogPath = join(home, '.cx', 'session-cost.jsonl');
 const lastAgentPath = join(home, '.cx', 'last-agent.json');
+const checkpointPath = join(home, '.cx', 'transcript-checkpoints.json');
 
-// Read TS result
 let tsResult = 'unchecked';
-try { tsResult = existsSync(tsResultPath) ? readFileSync(tsResultPath, 'utf8').trim() : 'unchecked'; } catch { /* best effort */ }
+try { tsResult = existsSync(tsResultPath) ? readFileSync(tsResultPath, 'utf8').trim() : 'unchecked'; } catch { /* non-critical */ }
 
-// Read and clear warn flags
 let warnings = [];
 try {
   if (existsSync(warnFlagsPath)) {
     warnings = readFileSync(warnFlagsPath, 'utf8').split('\n').filter(Boolean);
     writeFileSync(warnFlagsPath, '');
   }
-} catch { /* best effort */ }
+} catch { /* non-critical */ }
 
-// Read and clear files-changed count
 let fileCount = 0;
 try {
   if (existsSync(countPath)) {
     fileCount = parseInt(readFileSync(countPath, 'utf8').trim() || '0', 10) || 0;
     writeFileSync(countPath, '0');
   }
-} catch { /* best effort */ }
+} catch { /* non-critical */ }
 
-// Estimate cost from stdin usage tokens using Sonnet 4.5/4.6 defaults.
 let costNote = '';
+let totalCostUsd = 0;
+let turnsLogged = 0;
 try {
   const payload = raw ? JSON.parse(raw) : {};
-  let usage = payload?.usage || payload?.stop_hook_active?.usage || null;
-  const transcriptPath = payload?.transcript_path || payload?.transcriptPath || process.env.CLAUDE_TRANSCRIPT_PATH;
-  if (!usage || (!usage.input_tokens && !usage.output_tokens)) {
-    const fromTranscript = readLastTranscriptUsage(transcriptPath);
-    if (fromTranscript) usage = fromTranscript;
+  const transcriptPath =
+    payload?.transcript_path ||
+    payload?.transcriptPath ||
+    process.env.CLAUDE_TRANSCRIPT_PATH;
+
+  let agentName = null;
+  let taskKey = null;
+  try {
+    if (existsSync(lastAgentPath)) {
+      const lastAgent = JSON.parse(readFileSync(lastAgentPath, 'utf8'));
+      agentName = lastAgent.agent || null;
+      taskKey = lastAgent.taskKey || null;
+      writeFileSync(lastAgentPath, '');
+    }
+  } catch { /* non-critical */ }
+
+  if (!agentName) {
+    agentName = 'construct';
   }
-  usage = usage || {};
-  const inputTokens = usage?.input_tokens || 0;
-  const outputTokens = usage?.output_tokens || 0;
-  const cacheReadInputTokens = usage?.cache_read_input_tokens || 0;
-  const cacheCreation5mInputTokens = usage?.cache_creation?.ephemeral_5m_input_tokens || usage?.cache_creation_5m_input_tokens || 0;
-  const cacheCreation1hInputTokens = usage?.cache_creation?.ephemeral_1h_input_tokens || usage?.cache_creation_1h_input_tokens || 0;
-  const explicitCacheCreationInputTokens = usage?.cache_creation_input_tokens || 0;
-  const cacheCreationInputTokens = explicitCacheCreationInputTokens || cacheCreation5mInputTokens + cacheCreation1hInputTokens;
-  if (inputTokens || outputTokens) {
-    const cost = (
-      inputTokens * 3 +
-      cacheCreation5mInputTokens * 3.75 +
-      cacheCreation1hInputTokens * 6 +
-      Math.max(0, cacheCreationInputTokens - cacheCreation5mInputTokens - cacheCreation1hInputTokens) * 3.75 +
-      cacheReadInputTokens * 0.3 +
-      outputTokens * 15
-    ) / 1_000_000;
-    costNote = `~${cost.toFixed(2)} this response`;
-
-    // Read agent attribution recorded by agent-tracker hook (best effort, cleared after read)
-    let agentName = null;
-    let taskKey = null;
-    try {
-      if (existsSync(lastAgentPath)) {
-        const lastAgent = JSON.parse(readFileSync(lastAgentPath, 'utf8'));
-        agentName = lastAgent.agent || null;
-        taskKey = lastAgent.taskKey || null;
-        writeFileSync(lastAgentPath, '');
-      }
-    } catch { /* best effort */ }
-
-    // Fallback attribution: active workflow task owner, else 'construct'
-    if (!agentName) {
-      try {
-        const wf = loadWorkflow(process.cwd());
-        const resolved = resolveAttribution(wf);
-        agentName = resolved.agent;
-        if (!taskKey && resolved.taskKey) taskKey = resolved.taskKey;
-      } catch { agentName = 'construct'; }
+
+  const checkpoints = loadTranscriptCheckpoints(checkpointPath);
+  let turns = collectUnprocessedUsage(transcriptPath, checkpoints);
+
+  if (turns.length === 0) {
+    const usage = payload?.usage || payload?.stop_hook_active?.usage || null;
+    const model = payload?.model || payload?.session?.model || null;
+    if (usage && (usage.input_tokens || usage.output_tokens)) {
+      turns = [{ usage, model, ts: null }];
     }
+  }
 
-    try {
-      const entry = { ts: new Date().toISOString(), input_tokens: inputTokens, output_tokens: outputTokens, cost_usd: cost };
-      if (cacheReadInputTokens) entry.cache_read_input_tokens = cacheReadInputTokens;
-      if (cacheCreationInputTokens) entry.cache_creation_input_tokens = cacheCreationInputTokens;
-      if (cacheCreation5mInputTokens) entry.cache_creation_5m_input_tokens = cacheCreation5mInputTokens;
-      if (cacheCreation1hInputTokens) entry.cache_creation_1h_input_tokens = cacheCreation1hInputTokens;
-      if (agentName) entry.agent = agentName;
-      if (taskKey) entry.task_key = taskKey;
-      appendFileSync(costLogPath, JSON.stringify(entry) + '\n');
-    } catch { /* best effort */ }
+  const nowIso = new Date().toISOString();
+  for (const turn of turns) {
+    const priced = priceUsage(turn.model, turn.usage);
+    if (
+      !priced.inputTokens &&
+      !priced.outputTokens &&
+      !priced.cacheReadInputTokens &&
+      !priced.cacheCreationInputTokens
+    ) continue;
+
+    const entry = {
+      ts: turn.ts || nowIso,
+      input_tokens: priced.inputTokens,
+      output_tokens: priced.outputTokens,
+      cost_usd: priced.costUsd,
+    };
+    if (priced.reasoningTokens) entry.reasoning_tokens = priced.reasoningTokens;
+    entry.total_tokens = priced.inputTokens + priced.outputTokens + priced.reasoningTokens;
+    if (priced.cacheReadInputTokens) entry.cache_read_input_tokens = priced.cacheReadInputTokens;
+    if (priced.cacheCreationInputTokens) entry.cache_creation_input_tokens = priced.cacheCreationInputTokens;
+    if (priced.cacheCreation5mInputTokens) entry.cache_creation_5m_input_tokens = priced.cacheCreation5mInputTokens;
+    if (priced.cacheCreation1hInputTokens) entry.cache_creation_1h_input_tokens = priced.cacheCreation1hInputTokens;
+    if (priced.modelName) entry.model = priced.modelName;
+    if (priced.costSource) entry.cost_source = priced.costSource;
+    if (agentName) entry.agent = agentName;
+    if (taskKey) entry.task_key = taskKey;
+
+    try { appendFileSync(costLogPath, JSON.stringify(entry) + '\n'); } catch { /* non-critical */ }
+
+    totalCostUsd += priced.costUsd;
+    turnsLogged += 1;
   }
-} catch { /* payload parse failure */ }
 
-// Executive Summary from Workflow
-let execSummary = '';
-try {
-  const workflow = loadWorkflow(process.cwd());
-  if (workflow) {
-    const findings = alignmentFindings(workflow);
-    const high = findings.filter(f => f.severity === 'HIGH').length;
-    const phase = workflow.phase.toUpperCase();
-    execSummary = `${phase}: ${workflow.status}${high > 0 ? ` (${high} blocks)` : ''}`;
+  saveTranscriptCheckpoints(checkpointPath, checkpoints);
+
+  if (totalCostUsd > 0) {
+    const label = turnsLogged > 1 ? `${turnsLogged} turns` : 'this response';
+    costNote = `~$${totalCostUsd.toFixed(2)} ${label}`;
   }
-} catch { /* best effort */ }
+} catch { /* non-critical */ }
 
-// Compose message parts
 const parts = [];
-if (execSummary) parts.push(execSummary);
 if (fileCount > 0) parts.push(`${fileCount} file${fileCount !== 1 ? 's' : ''} updated`);
 if (tsResult === 'pass') parts.push('TS OK');
 else if (tsResult !== 'unchecked') parts.push(`TS: ${tsResult}`);
@@ -165,7 +251,62 @@ const body = [
   parts.join(' · '),
 ].filter(Boolean).join('\n');
 
-// Fire notification
+try {
+  const cwd = process.cwd();
+  const activeSessions = listSessions(cwd, { status: 'active', limit: 1 });
+  if (activeSessions.length > 0) {
+    const sid = activeSessions[0].id;
+    const summaryParts = [];
+    try {
+      const recentCommits = execSync(`git -C "${cwd}" log --oneline -5 2>/dev/null`, { timeout: 4000 }).toString().trim();
+      if (recentCommits) summaryParts.push('commits: ' + recentCommits.split('\n').map((l) => l.trim()).slice(0, 3).join('; '));
+    } catch { /* non-critical */ }
+    if (fileCount > 0) summaryParts.push(fileCount + ' file' + (fileCount !== 1 ? 's' : '') + ' updated');
+    if (warnings.length > 0) summaryParts.push(warnings.length + ' warning' + (warnings.length !== 1 ? 's' : ''));
+    const summary = summaryParts.join(' — ') || 'Session completed';
+    updateSession(cwd, sid, { status: 'completed', summary });
+  }
+} catch { /* non-critical */ }
+
+try {
+  const cwd2 = process.cwd();
+  const closedSessions = listSessions(cwd2, { status: 'completed', limit: 1 });
+  if (closedSessions.length > 0) {
+    const session = loadSession(cwd2, closedSessions[0].id);
+    if (session) captureSessionArtifacts(cwd2, session);
+  }
+} catch { /* non-critical */ }
+
+const memStatsPath = join(home, '.cx', 'session-memory-stats.json');
+try {
+  if (existsSync(memStatsPath)) {
+    const memStats = JSON.parse(readFileSync(memStatsPath, 'utf8'));
+    appendSessionStats(process.cwd(), {
+      project: memStats.project || null,
+      observationsInjected: memStats.observationsInjected || 0,
+      memoryEnabled: memStats.memoryEnabled !== false,
+    });
+    writeFileSync(memStatsPath, '');
+  }
+} catch { /* non-critical */ }
+
+// Auto-generate a performance review every 24h. Cheap — reads the cost
+// ledger + (optionally) telemetry generations and writes a structured
+// JSON file the dashboard's Performance page consumes. Skipped on
+// repeat Stop events within the window to avoid review-spam.
+try {
+  const homeDir = process.env.HOME || homedir();
+  const stampPath = join(homeDir, '.cx', 'performance-reviews', '.last-run');
+  let lastRun = 0;
+  try { lastRun = Number(readFileSync(stampPath, 'utf8')) || 0; } catch { /* fresh */ }
+  if (Date.now() - lastRun > 24 * 60 * 60 * 1000) {
+    const { runGenerator } = await import('../performance/generate.mjs');
+    await runGenerator({ env: process.env });
+    mkdirSync(dirname(stampPath), { recursive: true });
+    writeFileSync(stampPath, String(Date.now()));
+  }
+} catch { /* review is best-effort */ }
+
 const platform = process.platform;
 try {
   if (platform === 'darwin') {
@@ -184,7 +325,6 @@ try {
     process.stderr.write(`[stop-notify] ${title}: ${body}\n`);
   }
 } catch {
-  // Fallback to stderr if notification fails
   process.stderr.write(`[stop-notify] ${title}: ${body}\n`);
 }
 

package/lib/hooks/stop-typecheck.mjs

@@ -3,6 +3,9 @@
  * lib/hooks/stop-typecheck.mjs — Stop typecheck hook — runs TypeScript type-check at session end and records result.
  *
  * Runs as a Stop hook. Invokes tsc --noEmit on the project and records pass/fail to ~/.cx/pending-typecheck.txt for the next session-start hook to surface.
+ *
+ * @p95ms 2000
+ * @maxBlockingScope Stop
  */
 import { readFileSync, writeFileSync, existsSync } from 'fs';
 import { execSync } from 'child_process';
@@ -64,7 +67,6 @@ try {
   try { writeFileSync(tsResultPath, 'pass'); } catch { /* best effort */ }
 } catch (e) {
   const output = (e.stdout?.toString() || '') + (e.stderr?.toString() || '');
-  // Count error lines (lines ending with "error TS####:")
   const errorLines = output.split('\n').filter(l => /error TS\d+:/.test(l));
   const count = errorLines.length || 1;
 
@@ -78,6 +80,16 @@ try {
   process.stderr.write(
     `[stop-typecheck] TypeScript found ${count} error${count !== 1 ? 's' : ''} that need attention. The code runs but won't compile cleanly. Review before releasing.\n`
   );
+
+  try {
+    const { emitRoleEvent } = await import('../roles/hook-emit.mjs');
+    emitRoleEvent({
+      type: 'test.fail',
+      summary: `TypeScript: ${count} error${count !== 1 ? 's' : ''}\n${errorLines.slice(0, 3).join('\n')}`,
+      hookInput: { cwd: projectDir },
+      context: { tool: 'tsc', count },
+    });
+  } catch { /* best effort */ }
 }
 
 process.exit(0);

package/lib/hooks/test-watch.mjs

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+/**
+ * test-watch.mjs — PostToolUse / Bash (async)
+ *
+ * When a Bash invocation ran tests (vitest/jest/npm test/bun test/pytest) and
+ * exited non-zero, emit `test.fail` for cx-qa. Detects flake patterns when the
+ * same test name passes and then fails within an hour and emits `test.flake`.
+ *
+ * @p95ms 30
+ * @maxBlockingScope none (async, non-blocking)
+ */
+
+import { readFileSync, existsSync, appendFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { logHookFailure } from './_lib/log.mjs';
+import { emitRoleEvent } from '../roles/hook-emit.mjs';
+
+let input = {};
+try { input = JSON.parse(readFileSync(0, 'utf8')); }
+catch (err) { logHookFailure({ hook: 'test-watch', err, phase: 'parse' }); process.exit(0); }
+
+const command = input?.tool_input?.command || '';
+const exitCode = input?.tool_response?.exit_code ?? input?.tool_response?.exitCode;
+const stdout = String(input?.tool_response?.stdout || '');
+const stderr = String(input?.tool_response?.stderr || '');
+
+const isTestCmd = /\b(vitest|jest|npm\s+test|bun\s+test|pnpm\s+test|yarn\s+test|pytest|cargo\s+test|go\s+test)\b/.test(command);
+if (!isTestCmd) process.exit(0);
+if (exitCode === 0 || exitCode === undefined) process.exit(0);
+
+const combined = (stderr + '\n' + stdout).slice(-4000);
+const failedNames = [...combined.matchAll(/(?:FAIL|×|✗)\s+([^\n]{3,160})/g)].slice(0, 5).map((m) => m[1].trim());
+const summary = `Tests failed: ${failedNames.length || 'unknown'}; first: ${failedNames[0] || combined.split('\n').find(Boolean)?.slice(0, 160) || command}`;
+
+emitRoleEvent({
+  type: 'test.fail',
+  summary,
+  hookInput: input,
+  context: { command, exitCode, failedNames },
+});
+
+const flakeTrackerPath = join(homedir(), '.cx', 'test-watch-state.json');
+try {
+  const state = existsSync(flakeTrackerPath) ? JSON.parse(readFileSync(flakeTrackerPath, 'utf8')) : {};
+  const now = Date.now();
+  for (const name of failedNames) {
+    const prev = state[name];
+    if (prev && prev.passedAt && now - prev.passedAt < 60 * 60 * 1000) {
+      emitRoleEvent({
+        type: 'test.flake',
+        summary: `Flake suspected: ${name} (passed ${Math.round((now - prev.passedAt) / 60000)} min ago, now failing)`,
+        hookInput: input,
+        context: { name, prevPassedAt: prev.passedAt },
+      });
+    }
+    state[name] = { failedAt: now };
+  }
+  appendFileSync(flakeTrackerPath, '');
+  const trimmed = {};
+  for (const [k, v] of Object.entries(state)) {
+    if ((v.failedAt || v.passedAt || 0) > now - 24 * 60 * 60 * 1000) trimmed[k] = v;
+  }
+  const writeFileSync = (await import('node:fs')).writeFileSync;
+  writeFileSync(flakeTrackerPath, JSON.stringify(trimmed));
+} catch { /* best effort */ }
+
+process.exit(0);

package/lib/host-capabilities.mjs

@@ -1,22 +1,43 @@
 #!/usr/bin/env node
 /**
- * lib/host-capabilities.mjs — <one-line purpose>
+ * lib/host-capabilities.mjs — Detect the active AI harness and its tool surface.
  *
- * <2–6 line summary.>
+ * Inspects the runtime environment (process title, env vars, OpenCode config)
+ * to classify whether Construct is running inside Claude Code, OpenCode,
+ * a plain terminal, or a multi-agent subagent context. The MCP server and
+ * CLI consult the classification to gate harness-specific features.
  */
 import { execFileSync, execSync } from "node:child_process";
 import { readOpenCodeConfig } from "./opencode-config.mjs";
 import net from "node:net";
 
-export async function findAvailablePort(startPort) {
-  return new Promise((resolve) => {
+const LOWEST_PORT = 0;
+const HIGHEST_PORT = 65535;
+const RETRYABLE_PORT_ERRORS = new Set(["EADDRINUSE", "EACCES"]);
+
+export async function findAvailablePort(startPort, { maxPort = HIGHEST_PORT } = {}) {
+  if (!Number.isInteger(startPort) || startPort < LOWEST_PORT || startPort > HIGHEST_PORT) {
+    throw new RangeError(`startPort must be an integer between ${LOWEST_PORT} and ${HIGHEST_PORT}. Received ${startPort}.`);
+  }
+  if (!Number.isInteger(maxPort) || maxPort < LOWEST_PORT || maxPort > HIGHEST_PORT) {
+    throw new RangeError(`maxPort must be an integer between ${LOWEST_PORT} and ${HIGHEST_PORT}. Received ${maxPort}.`);
+  }
+  if (startPort > maxPort) {
+    throw new RangeError(`startPort ${startPort} must be less than or equal to maxPort ${maxPort}.`);
+  }
+
+  return new Promise((resolve, reject) => {
     const server = net.createServer();
     server.listen(startPort, () => {
       const { port } = server.address();
       server.close(() => resolve(port));
     });
-    server.on("error", () => {
-      resolve(findAvailablePort(startPort + 1));
+    server.on("error", (error) => {
+      if (!RETRYABLE_PORT_ERRORS.has(error?.code) || startPort >= maxPort) {
+        reject(error instanceof Error ? error : new Error(String(error)));
+        return;
+      }
+      resolve(findAvailablePort(startPort + 1, { maxPort }));
     });
   });
 }
@@ -81,11 +102,11 @@ export function detectHostCapabilities() {
       version: opencodeRaw,
       orchestration: "primary-plus-subagents",
       promptableWorkers: false,
-      sharedTaskRuntime: "construct-workflow",
+      sharedTaskRuntime: "tracker-plus-plan",
       lifecycleHooks: ["session.error", "session.idle", "tool.execute.before", "tool.execute.after"],
       notes: [
         "Primary agents are promptable; subagents are bounded worker sessions.",
-        "Construct uses .cx/workflow.json plus task permissions and plugins to coordinate parallel worker execution.",
+        "Construct uses tracker state, plan.md, task permissions, and plugins to coordinate parallel worker execution.",
         "Use NEEDS_MAIN_INPUT to route user questions back to the primary persona.",
       ],
     },
@@ -95,10 +116,10 @@ export function detectHostCapabilities() {
       version: codexRaw,
       orchestration: "profile-and-mcp",
       promptableWorkers: false,
-      sharedTaskRuntime: "construct-workflow",
+      sharedTaskRuntime: "tracker-plus-plan",
       lifecycleHooks: [],
       notes: [
-        "Use Construct profiles, MCP workflow tools, and the active session.",
+        "Use Construct profiles, MCP project/memory tools, and the active session.",
         "Native profile switching is not automatic; continue in-session when dispatch is unavailable.",
       ],
     },