traintrack 2.0.0

package/dist/runner/turn-runner.js

@@ -0,0 +1,81 @@
+// Why: run ONE headless agent turn as a fresh child process and resolve its
+// structured result. This is the reliable replacement for PTY injection — no
+// idle-guessing: we spawn, stream stdout line-by-line through the event-parser,
+// and the provider's own turn-end event (claude `result` / codex `turn.completed`)
+// is the in-band ACK. Ported from the rust conductor's run_process/run_turn.
+import { spawn } from 'node:child_process';
+import { createTurnParseState, reduceLine, finalizeTurn } from './event-parser.js';
+// Local passthrough: Windows packaging is out of scope for traintrack v1 (macOS/Linux only).
+function getSpawnArgsForWindows(cmd, args) {
+    return { spawnCmd: cmd, spawnArgs: args };
+}
+const MAX_STDERR_CHARS = 64_000;
+/** Spawn a headless turn, stream-parse its stdout, and resolve the turn result + exit code. */
+export function runHeadlessTurn(input) {
+    const { provider, command, args, cwd, env, onDelta } = input;
+    const spawnImpl = input.spawnImpl ?? spawn;
+    const { spawnCmd, spawnArgs } = getSpawnArgsForWindows(command, args);
+    return new Promise((resolve, reject) => {
+        let child;
+        try {
+            child = spawnImpl(spawnCmd, spawnArgs, {
+                // Why: stdin MUST be ignored (= /dev/null). codex exec HANGS FOREVER on a
+                // non-TTY stdin pipe waiting for input (openai/codex #20919); the rust
+                // conductor used Stdio::null for exactly this.
+                stdio: ['ignore', 'pipe', 'pipe'],
+                windowsHide: true,
+                cwd,
+                env: env ?? process.env
+            });
+        }
+        catch (err) {
+            reject(err instanceof Error ? err : new Error(String(err)));
+            return;
+        }
+        const state = createTurnParseState(provider);
+        let stdoutBuf = '';
+        let stderr = '';
+        let settled = false;
+        const consumeLine = (line) => {
+            const { delta } = reduceLine(state, line);
+            if (delta && onDelta) {
+                onDelta(delta);
+            }
+        };
+        child.stdout?.on('data', (chunk) => {
+            stdoutBuf += chunk.toString();
+            let nl = stdoutBuf.indexOf('\n');
+            while (nl >= 0) {
+                consumeLine(stdoutBuf.slice(0, nl));
+                stdoutBuf = stdoutBuf.slice(nl + 1);
+                nl = stdoutBuf.indexOf('\n');
+            }
+        });
+        // Why: drain stderr concurrently so a chatty stderr can't fill the OS pipe
+        // buffer and deadlock the child (the rust run_process deadlock fix).
+        child.stderr?.on('data', (chunk) => {
+            stderr += chunk.toString();
+            if (stderr.length > MAX_STDERR_CHARS) {
+                stderr = stderr.slice(-MAX_STDERR_CHARS);
+            }
+        });
+        child.on('error', (err) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            reject(err);
+        });
+        child.on('close', (code) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            // Flush a trailing partial line that had no terminating newline.
+            if (stdoutBuf.trim()) {
+                consumeLine(stdoutBuf);
+            }
+            resolve({ ...finalizeTurn(state), exitCode: code, stderr });
+        });
+    });
+}

package/dist/setup/blocks.js

@@ -0,0 +1,251 @@
+// The idempotency engine (pure, fs-only; no harness logic).
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+function ensureDir(file) {
+    mkdirSync(dirname(file), { recursive: true });
+}
+/** Build the canonical marker block: start, body, end on their own lines. */
+function renderBlock(start, end, body) {
+    return `${start}\n${body}\n${end}`;
+}
+/** Find the [start, end] span (inclusive of markers) in text at or after `at`, or null. */
+function findSpanFrom(text, start, end, at) {
+    const from = text.indexOf(start, at);
+    if (from === -1)
+        return null;
+    const endStart = text.indexOf(end, from + start.length);
+    if (endStart === -1)
+        return null;
+    return { from, to: endStart + end.length };
+}
+/** Find the first [start, end] span (inclusive of markers) in text, or null. */
+function findSpan(text, start, end) {
+    return findSpanFrom(text, start, end, 0);
+}
+/** Cut a span out of text, collapsing the seam so removal leaves no blank-line
+ *  scar and never drops the file's POSIX trailing newline. */
+function spliceSeam(text, span) {
+    let before = text.slice(0, span.from);
+    let after = text.slice(span.to);
+    // Drop a single leading newline on `after` (the newline that followed the end
+    // marker), then drop a trailing newline on `before` ONLY when a real blank-line
+    // scar is present (i.e. `after` still starts with a newline). When the block was
+    // the last thing in the file, `after` becomes '' and we keep `before`'s trailing
+    // newline so the file stays POSIX-clean.
+    if (after.startsWith('\n'))
+        after = after.slice(1);
+    if (before.endsWith('\n') && after.startsWith('\n')) {
+        before = before.slice(0, -1);
+    }
+    return before + after;
+}
+/** Insert or replace a marker-delimited block in a text file. Creates the file
+ *  (and parent dirs) if missing. Returns 'added' | 'updated' | 'unchanged'. */
+export function upsertBlock(file, start, end, body) {
+    const block = renderBlock(start, end, body);
+    if (!existsSync(file)) {
+        ensureDir(file);
+        writeFileSync(file, block + '\n', 'utf8');
+        return 'added';
+    }
+    const text = readFileSync(file, 'utf8');
+    const span = findSpan(text, start, end);
+    if (!span) {
+        // No existing block — append, keeping a clean separation from prior content.
+        const sep = text.length === 0 || text.endsWith('\n') ? '' : '\n';
+        writeFileSync(file, text + sep + block + '\n', 'utf8');
+        return 'added';
+    }
+    // Replace the first span, then strip any further spans of the same markers so
+    // the file converges to EXACTLY one block even if a prior buggy run, a merge,
+    // or a copy/paste left duplicates behind.
+    const existing = text.slice(span.from, span.to);
+    let next = text.slice(0, span.from) + block + text.slice(span.to);
+    const collapsed = collapseExtraSpans(next, start, end);
+    next = collapsed.text;
+    if (existing === block && !collapsed.removedAny)
+        return 'unchanged';
+    writeFileSync(file, next, 'utf8');
+    return 'updated';
+}
+/** Remove every span AFTER the first (the first is assumed already canonical),
+ *  collapsing the seam each time. Returns the new text and whether any were removed. */
+function collapseExtraSpans(text, start, end) {
+    const first = findSpan(text, start, end);
+    if (!first)
+        return { text, removedAny: false };
+    let removedAny = false;
+    // Search only the region after the first block's end for further spans.
+    let cur = text;
+    let searchFrom = first.to;
+    for (;;) {
+        const span = findSpanFrom(cur, start, end, searchFrom);
+        if (!span)
+            break;
+        cur = spliceSeam(cur, span);
+        removedAny = true;
+        // Continue scanning from where the removed block began.
+        searchFrom = span.from;
+    }
+    return { text: cur, removedAny };
+}
+/** Remove a marker-delimited block if present; preserves the rest of the file.
+ *  Returns 'removed' | 'unchanged'. */
+export function removeBlock(file, start, end) {
+    if (!existsSync(file))
+        return 'unchanged';
+    let text = readFileSync(file, 'utf8');
+    let removedAny = false;
+    // Loop until no span remains so ALL traintrack blocks are removed — a doubled
+    // block (from a prior buggy run, a copy/paste, or a merge) is fully collapsed,
+    // not left orphaned. uninstall then truly removes everything it claims to.
+    for (;;) {
+        const span = findSpan(text, start, end);
+        if (!span)
+            break;
+        text = spliceSeam(text, span);
+        removedAny = true;
+    }
+    if (!removedAny)
+        return 'unchanged';
+    writeFileSync(file, text, 'utf8');
+    return 'removed';
+}
+/** Structural (key-order-INSENSITIVE) deep equality. Exported so dry-run planning
+ *  in configure.ts compares JSON values exactly the way the real upsertJson does. */
+export function deepEqual(a, b) {
+    if (a === b)
+        return true;
+    if (typeof a !== typeof b)
+        return false;
+    if (a === null || b === null)
+        return a === b;
+    if (Array.isArray(a) || Array.isArray(b)) {
+        if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length)
+            return false;
+        return a.every((v, i) => deepEqual(v, b[i]));
+    }
+    if (typeof a === 'object' && typeof b === 'object') {
+        const ao = a;
+        const bo = b;
+        const ak = Object.keys(ao);
+        const bk = Object.keys(bo);
+        if (ak.length !== bk.length)
+            return false;
+        return ak.every((k) => Object.prototype.hasOwnProperty.call(bo, k) && deepEqual(ao[k], bo[k]));
+    }
+    return false;
+}
+function readJson(file) {
+    if (!existsSync(file))
+        return {};
+    const text = readFileSync(file, 'utf8').trim();
+    if (text === '')
+        return {};
+    const parsed = JSON.parse(text);
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed)
+        ? parsed
+        : {};
+}
+function writeJson(file, obj) {
+    ensureDir(file);
+    writeFileSync(file, JSON.stringify(obj, null, 2) + '\n', 'utf8');
+}
+/** Read a JSON file (or {} if missing), set obj[...path] = value (deep), write
+ *  back pretty-printed. Returns 'added' | 'updated' | 'unchanged'. Creates dirs. */
+export function upsertJson(file, path, value) {
+    const obj = readJson(file);
+    let cursor = obj;
+    for (let i = 0; i < path.length - 1; i++) {
+        const key = path[i];
+        const child = cursor[key];
+        if (child === null || typeof child !== 'object' || Array.isArray(child)) {
+            cursor[key] = {};
+        }
+        cursor = cursor[key];
+    }
+    const leaf = path[path.length - 1];
+    const had = Object.prototype.hasOwnProperty.call(cursor, leaf);
+    if (had && deepEqual(cursor[leaf], value))
+        return 'unchanged';
+    cursor[leaf] = value;
+    writeJson(file, obj);
+    return had ? 'updated' : 'added';
+}
+/** Delete obj[...path] if present; write back. Returns 'removed' | 'unchanged'. */
+export function removeJson(file, path) {
+    if (!existsSync(file))
+        return 'unchanged';
+    const obj = readJson(file);
+    let cursor = obj;
+    for (let i = 0; i < path.length - 1; i++) {
+        const child = cursor[path[i]];
+        if (child === null || typeof child !== 'object' || Array.isArray(child))
+            return 'unchanged';
+        cursor = child;
+    }
+    const leaf = path[path.length - 1];
+    if (!Object.prototype.hasOwnProperty.call(cursor, leaf))
+        return 'unchanged';
+    delete cursor[leaf];
+    writeJson(file, obj);
+    return 'removed';
+}
+// ─── Dry-run planners ────────────────────────────────────────────────────────
+// Single source of truth for `--dry-run`: each planX answers exactly the Action
+// the matching mutator WOULD return, using the SAME comparison logic, so dry-run
+// can never disagree with a real run (structural parity, not coincidental).
+/** What upsertBlock WOULD return for these inputs, without writing. */
+export function planBlock(file, start, end, body) {
+    const block = renderBlock(start, end, body);
+    if (!existsSync(file))
+        return 'added';
+    const text = readFileSync(file, 'utf8');
+    const span = findSpan(text, start, end);
+    if (!span)
+        return 'added';
+    const existing = text.slice(span.from, span.to);
+    // A doubled block would be reconciled to one → 'updated' even if the first matches.
+    const next = text.slice(0, span.from) + block + text.slice(span.to);
+    const { removedAny } = collapseExtraSpans(next, start, end);
+    return existing === block && !removedAny ? 'unchanged' : 'updated';
+}
+/** What upsertJson WOULD return for these inputs, without writing. */
+export function planJson(file, path, value) {
+    if (!existsSync(file))
+        return 'added';
+    const obj = readJson(file);
+    let cursor = obj;
+    for (let i = 0; i < path.length - 1; i++) {
+        const child = cursor[path[i]];
+        if (child === null || typeof child !== 'object' || Array.isArray(child))
+            return 'added';
+        cursor = child;
+    }
+    const leaf = path[path.length - 1];
+    if (!Object.prototype.hasOwnProperty.call(cursor, leaf))
+        return 'added';
+    return deepEqual(cursor[leaf], value) ? 'unchanged' : 'updated';
+}
+/** What removeBlock WOULD return for these inputs, without writing. */
+export function planRemoveBlock(file, start, end) {
+    if (!existsSync(file))
+        return 'unchanged';
+    const text = readFileSync(file, 'utf8');
+    return findSpan(text, start, end) ? 'removed' : 'unchanged';
+}
+/** What removeJson WOULD return for these inputs, without writing. */
+export function planRemoveJson(file, path) {
+    if (!existsSync(file))
+        return 'unchanged';
+    const obj = readJson(file);
+    let cursor = obj;
+    for (let i = 0; i < path.length - 1; i++) {
+        const child = cursor[path[i]];
+        if (child === null || typeof child !== 'object' || Array.isArray(child))
+            return 'unchanged';
+        cursor = child;
+    }
+    const leaf = path[path.length - 1];
+    return Object.prototype.hasOwnProperty.call(cursor, leaf) ? 'removed' : 'unchanged';
+}

package/dist/setup/configure.js

@@ -0,0 +1,179 @@
+// Apply/remove the MCP entry + awareness block for one harness.
+// Pure orchestration over blocks.ts — honors ctx.dryRun and ctx.injectAwareness.
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { upsertBlock, removeBlock, upsertJson, removeJson, planBlock, planJson, planRemoveBlock, planRemoveJson, } from './blocks.js';
+// Marker conventions (per the plan). Re-runs replace, never duplicate; uninstall removes cleanly.
+const MD_START = '<!-- >>> traintrack >>> -->';
+const MD_END = '<!-- <<< traintrack <<< -->';
+const TOML_START = '# >>> traintrack >>>';
+const TOML_END = '# <<< traintrack <<<';
+/** The awareness body — the auto-injected "coordinating-a-team" methodology,
+ *  identical text on every harness, wrapped in the file's markers. */
+export const AWARENESS_BODY = [
+    'You are part of a traintrack agent team. Every coding-agent session (Claude Code, Codex, Cursor, OpenCode) opened in this project auto-joins the SAME team over a shared local channel, and you have these tools: list_team, check_messages, send_message, spawn_worker, delegate_task, await_results, join_team.',
+    '',
+    'Working with teammates (the mesh):',
+    '- Run check_messages at the START of each turn, and whenever you see a "📨 N unread" nudge on a tool result — that is a teammate writing to you.',
+    '- list_team shows who is online. send_message(to, body) messages a teammate by handle; they read it on their next turn (you cannot interrupt them mid-task).',
+    '',
+    'When the user asks you to build several things (you act as LEAD):',
+    '1. Propose a short split — which part goes to which worker (claude or codex) — and confirm before spawning, unless told to just go.',
+    '2. spawn_worker(agent, role, task) for each part; workers run headless in their own git worktree and auto-reply.',
+    '3. await_results() to collect, delegate_task(handle, task) for follow-ups, then synthesize. Keep the team small; do simple work yourself.',
+    '',
+    'If a human adds your session to a running team, you are already auto-joined — just check_messages and help.',
+].join('\n');
+/** Pick the marker pair for a comment style. */
+function markers(style) {
+    return style === 'toml' ? { start: TOML_START, end: TOML_END } : { start: MD_START, end: MD_END };
+}
+/** Encode a string as a TOML basic string: wrap in double quotes and escape
+ *  backslashes and double quotes (the two chars that would otherwise break a
+ *  TOML basic string). Without this, a nodePath/serverPath containing a `"` or
+ *  `\` would emit invalid TOML and Codex would silently fail to load the server. */
+function tomlStr(s) {
+    return '"' + s.replace(/\\/g, '\\\\').replace(/"/g, '\\"') + '"';
+}
+/** The toml MCP block body (node/server substituted, properly TOML-escaped). The
+ *  env table tags this session's agent type so auto-presence registers it as the
+ *  right kind (claude/codex/…). */
+function tomlMcpBody(ctx, agentId) {
+    return (`[mcp_servers.traintrack]\n` +
+        `command = ${tomlStr(ctx.nodePath)}\n` +
+        `args = [${tomlStr(ctx.serverPath)}]\n` +
+        `env = { TRAINTRACK_AGENT = ${tomlStr(agentId)} }`);
+}
+/** Did this action actually mutate a file? files[] should list only real writes:
+ *  never on a dry-run, and never for 'unchanged'/'error'/'skipped'. */
+function wrote(action, ctx) {
+    return !ctx.dryRun && (action === 'added' || action === 'updated');
+}
+/** Ensure `file` opens with exactly `frontmatter` (e.g. Cursor MDC `---\n...\n---`).
+ *  Idempotent: if the file already starts with the frontmatter, it is a no-op; if
+ *  it exists without it, the frontmatter is prepended (a blank line separates it
+ *  from existing content). Honors dryRun (never writes). The frontmatter MUST be
+ *  the first bytes of the file for the host to recognize the rule, so it is added
+ *  ahead of the marker-delimited awareness block rather than inside it. */
+function ensureFrontmatter(file, frontmatter, dryRun) {
+    if (dryRun)
+        return;
+    if (!existsSync(file))
+        return; // upsertBlock will create it; prepended on the next pass below
+    const text = readFileSync(file, 'utf8');
+    if (text.startsWith(frontmatter))
+        return;
+    const sep = text.length === 0 || text.startsWith('\n') ? '' : '\n';
+    writeFileSync(file, frontmatter + '\n' + sep + text, 'utf8');
+}
+/** Strip a leading `frontmatter` block from `file` (the inverse of ensureFrontmatter),
+ *  used on uninstall so we leave no orphaned `---\nalwaysApply: true\n---` behind.
+ *  Only removes it when it is the literal head of the file. Honors dryRun. */
+function removeFrontmatter(file, frontmatter, dryRun) {
+    if (dryRun || !existsSync(file))
+        return;
+    const text = readFileSync(file, 'utf8');
+    if (!text.startsWith(frontmatter))
+        return;
+    let rest = text.slice(frontmatter.length);
+    if (rest.startsWith('\n'))
+        rest = rest.slice(1);
+    if (rest.startsWith('\n'))
+        rest = rest.slice(1);
+    writeFileSync(file, rest, 'utf8');
+}
+/** Apply the MCP entry + (optionally) awareness for one harness. */
+export function configureHarness(spec, ctx) {
+    const mcpFile = join(ctx.home, spec.mcp.file);
+    const awarenessFile = join(ctx.home, spec.awarenessFile);
+    const files = [];
+    // --- MCP ---
+    let mcp;
+    if (spec.mcp.kind === 'toml') {
+        mcp = ctx.dryRun
+            ? planBlock(mcpFile, TOML_START, TOML_END, tomlMcpBody(ctx, spec.id))
+            : upsertBlock(mcpFile, TOML_START, TOML_END, tomlMcpBody(ctx, spec.id));
+    }
+    else {
+        const path = spec.mcp.jsonPath ?? ['mcpServers', 'traintrack'];
+        // OpenCode reads a `mcp` map of local-server objects; everyone else uses the
+        // `mcpServers` {command, args, env} shape.
+        const value = spec.mcp.kind === 'json-opencode'
+            ? {
+                type: 'local',
+                command: [ctx.nodePath, ctx.serverPath],
+                enabled: true,
+                environment: { TRAINTRACK_AGENT: spec.id },
+            }
+            : { command: ctx.nodePath, args: [ctx.serverPath], env: { TRAINTRACK_AGENT: spec.id } };
+        mcp = ctx.dryRun ? planJson(mcpFile, path, value) : upsertJson(mcpFile, path, value);
+    }
+    // files[] = paths actually WRITTEN: skip on dry-run, on error, and on 'unchanged'.
+    if (wrote(mcp, ctx))
+        files.push(mcpFile);
+    // --- Awareness ---
+    let awareness;
+    if (!ctx.injectAwareness) {
+        awareness = 'skipped';
+    }
+    else {
+        const m = markers(spec.awarenessStyle);
+        awareness = ctx.dryRun
+            ? planBlock(awarenessFile, m.start, m.end, AWARENESS_BODY)
+            : upsertBlock(awarenessFile, m.start, m.end, AWARENESS_BODY);
+        // Cursor (and any harness with awarenessFrontmatter) needs MDC frontmatter at
+        // the file head or the rule is never auto-applied. Prepend it after the block
+        // is written so it sits ABOVE the markers. Idempotent on re-run.
+        if (spec.awarenessFrontmatter && !ctx.dryRun) {
+            ensureFrontmatter(awarenessFile, spec.awarenessFrontmatter, ctx.dryRun);
+        }
+        if (wrote(awareness, ctx))
+            files.push(awarenessFile);
+    }
+    return {
+        harness: spec.id,
+        mcp,
+        awareness,
+        files,
+        detail: ctx.dryRun ? 'dry-run: no files written' : undefined,
+    };
+}
+/** Remove the MCP entry + awareness for one harness (the inverse of configureHarness). */
+export function unconfigureHarness(spec, ctx) {
+    const mcpFile = join(ctx.home, spec.mcp.file);
+    const awarenessFile = join(ctx.home, spec.awarenessFile);
+    const files = [];
+    // --- MCP ---
+    let mcp;
+    if (spec.mcp.kind === 'toml') {
+        mcp = ctx.dryRun
+            ? planRemoveBlock(mcpFile, TOML_START, TOML_END)
+            : removeBlock(mcpFile, TOML_START, TOML_END);
+    }
+    else {
+        const path = spec.mcp.jsonPath ?? ['mcpServers', 'traintrack'];
+        mcp = ctx.dryRun ? planRemoveJson(mcpFile, path) : removeJson(mcpFile, path);
+    }
+    // files[] = paths actually WRITTEN: a real removal only (never on dry-run).
+    if (!ctx.dryRun && mcp === 'removed')
+        files.push(mcpFile);
+    // --- Awareness ---
+    const m = markers(spec.awarenessStyle);
+    const awareness = ctx.dryRun
+        ? planRemoveBlock(awarenessFile, m.start, m.end)
+        : removeBlock(awarenessFile, m.start, m.end);
+    // Strip the MDC frontmatter we prepended on install (Cursor) so uninstall leaves
+    // no orphaned `---\nalwaysApply: true\n---` head behind.
+    if (spec.awarenessFrontmatter && !ctx.dryRun && awareness === 'removed') {
+        removeFrontmatter(awarenessFile, spec.awarenessFrontmatter, ctx.dryRun);
+    }
+    if (!ctx.dryRun && awareness === 'removed')
+        files.push(awarenessFile);
+    return {
+        harness: spec.id,
+        mcp,
+        awareness,
+        files,
+        detail: ctx.dryRun ? 'dry-run: no files written' : undefined,
+    };
+}

package/dist/setup/detect.js

@@ -0,0 +1,53 @@
+import { existsSync, statSync } from 'node:fs';
+import { join, delimiter } from 'node:path';
+import { HARNESSES } from './harness.js';
+/** Detect which harnesses are available.
+ *
+ * @param args.home       - The user's home directory to probe configHints under.
+ * @param args.onPath     - A function that returns true if a binary is executable on PATH.
+ *                          Injected so tests can stub without touching the real filesystem or PATH.
+ */
+export function detectHarnesses(args) {
+    const { home, onPath } = args;
+    return HARNESSES.map((spec) => {
+        // 1. Check bins on PATH
+        for (const bin of spec.bins) {
+            if (onPath(bin)) {
+                return { spec, present: true, reason: `found '${bin}' on PATH` };
+            }
+        }
+        // 2. Check configHints under home
+        for (const hint of spec.configHints) {
+            const abs = join(home, hint);
+            if (existsSync(abs)) {
+                return { spec, present: true, reason: `config hint found: ${abs}` };
+            }
+        }
+        return { spec, present: false, reason: 'not found on PATH and no config hints present' };
+    });
+}
+/** Real implementation: scan process.env.PATH directories for an executable named `bin`.
+ *  No shelling out — pure Node.js fs checks. */
+export function defaultOnPath(bin) {
+    const pathEnv = process.env['PATH'] ?? '';
+    // Use the platform PATH separator (':' on POSIX, ';' on Windows). traintrack
+    // targets macOS/Linux (see package.json "os"), but splitting on path.delimiter
+    // keeps this correct rather than relying on a hardcoded ':'.
+    const dirs = pathEnv.split(delimiter).filter((d) => d.length > 0);
+    for (const dir of dirs) {
+        const candidate = join(dir, bin);
+        try {
+            const st = statSync(candidate);
+            if (st.isFile()) {
+                // Check executable bit: owner (0o100), group (0o010), or other (0o001)
+                const mode = st.mode;
+                if (mode & 0o111)
+                    return true;
+            }
+        }
+        catch {
+            // ENOENT or EACCES — not found in this dir, continue
+        }
+    }
+    return false;
+}

package/dist/setup/harness.js

@@ -0,0 +1,61 @@
+/** The canonical per-harness target table.
+ *  Every field must match the plan exactly — downstream tasks consume this verbatim. */
+export const HARNESSES = [
+    {
+        id: 'claude',
+        displayName: 'Claude Code',
+        bins: ['claude'],
+        configHints: ['.claude.json', '.claude'],
+        mcp: {
+            kind: 'json',
+            file: '.claude.json',
+            jsonPath: ['mcpServers', 'traintrack'],
+        },
+        awarenessFile: '.claude/CLAUDE.md',
+        awarenessStyle: 'md',
+    },
+    {
+        id: 'codex',
+        displayName: 'Codex',
+        bins: ['codex'],
+        configHints: ['.codex', '.codex/config.toml'],
+        mcp: {
+            kind: 'toml',
+            file: '.codex/config.toml',
+        },
+        awarenessFile: '.codex/AGENTS.md',
+        awarenessStyle: 'toml',
+    },
+    {
+        id: 'cursor',
+        displayName: 'Cursor',
+        bins: ['cursor'],
+        configHints: ['.cursor'],
+        mcp: {
+            kind: 'json',
+            file: '.cursor/mcp.json',
+            jsonPath: ['mcpServers', 'traintrack'],
+        },
+        awarenessFile: '.cursor/rules/traintrack.md',
+        awarenessStyle: 'md',
+        // Cursor only auto-attaches a rule to the model context when it carries MDC
+        // frontmatter. Without `alwaysApply: true` the rule defaults to a non-applied
+        // type and the lead never learns it can run a team. Emit it at the file head.
+        awarenessFrontmatter: '---\nalwaysApply: true\n---',
+    },
+    {
+        id: 'opencode',
+        displayName: 'OpenCode',
+        bins: ['opencode'],
+        configHints: ['.config/opencode', '.opencode'],
+        mcp: {
+            // OpenCode's config uses a `mcp` map with local-server objects, not the
+            // `mcpServers` {command,args} shape — see configure.ts for the value built.
+            kind: 'json-opencode',
+            file: '.config/opencode/opencode.json',
+            jsonPath: ['mcp', 'traintrack'],
+        },
+        awarenessFile: '.config/opencode/AGENTS.md',
+        awarenessStyle: 'md',
+    },
+];