@weldr/runr 0.3.0

package/dist/commands/status.js

@@ -0,0 +1,189 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { RunStore } from '../store/run-store.js';
+import { getRunsRoot } from '../store/runs-root.js';
+import { getActiveRuns, getCollisionRisk } from '../supervisor/collision.js';
+/**
+ * Get status of a single run.
+ */
+export async function statusCommand(options) {
+    const runStore = RunStore.init(options.runId, options.repo);
+    const state = runStore.readState();
+    console.log(JSON.stringify(state, null, 2));
+}
+/**
+ * Get status of all runs in the repo.
+ * Displays a table sorted by: running runs first (most recent), then stopped runs (most recent).
+ */
+export async function statusAllCommand(options) {
+    const runsRoot = getRunsRoot(options.repo);
+    if (!fs.existsSync(runsRoot)) {
+        console.log('No runs found.');
+        return;
+    }
+    const runDirs = fs.readdirSync(runsRoot, { withFileTypes: true })
+        .filter(d => d.isDirectory())
+        .map(d => d.name);
+    if (runDirs.length === 0) {
+        console.log('No runs found.');
+        return;
+    }
+    const summaries = [];
+    // Pre-compute active runs for collision detection
+    const allActiveRuns = getActiveRuns(options.repo);
+    for (const runId of runDirs) {
+        const statePath = path.join(runsRoot, runId, 'state.json');
+        if (!fs.existsSync(statePath)) {
+            continue;
+        }
+        try {
+            const stateRaw = fs.readFileSync(statePath, 'utf-8');
+            const state = JSON.parse(stateRaw);
+            // Get last worker call info
+            const workerCallPath = path.join(runsRoot, runId, 'last_worker_call.json');
+            let workerCall = null;
+            if (fs.existsSync(workerCallPath)) {
+                try {
+                    workerCall = JSON.parse(fs.readFileSync(workerCallPath, 'utf-8'));
+                }
+                catch {
+                    // Ignore parse errors
+                }
+            }
+            const isRunning = state.phase !== 'STOPPED';
+            const updatedAt = state.updated_at ? new Date(state.updated_at) : new Date(0);
+            const age = formatAge(updatedAt);
+            // In-flight worker info
+            let inFlight = '-';
+            if (isRunning && workerCall) {
+                const elapsed = Math.floor((Date.now() - new Date(workerCall.at).getTime()) / 1000);
+                inFlight = `${workerCall.worker}/${workerCall.stage} (${elapsed}s)`;
+            }
+            // Compute collision risk with other active runs (excluding this run)
+            // Only show risk for running runs; stopped runs show '-'
+            let collisionRisk = '-';
+            if (isRunning) {
+                collisionRisk = 'none';
+                const otherActiveRuns = allActiveRuns.filter(r => r.runId !== runId);
+                if (otherActiveRuns.length > 0) {
+                    // Extract files_expected from milestones
+                    const touchFiles = [];
+                    for (const milestone of state.milestones) {
+                        if (milestone.files_expected) {
+                            touchFiles.push(...milestone.files_expected);
+                        }
+                    }
+                    collisionRisk = getCollisionRisk(state.scope_lock?.allowlist ?? [], touchFiles, otherActiveRuns);
+                }
+            }
+            summaries.push({
+                runId,
+                status: isRunning ? 'running' : 'stopped',
+                phase: state.phase,
+                milestones: `${state.milestone_index + 1}/${state.milestones.length}`,
+                age,
+                stopReason: state.stop_reason ?? '-',
+                autoResumeCount: state.auto_resume_count ?? 0,
+                inFlight,
+                collisionRisk,
+                updatedAt
+            });
+        }
+        catch {
+            // Skip runs with invalid state
+        }
+    }
+    if (summaries.length === 0) {
+        console.log('No valid runs found.');
+        return;
+    }
+    // Sort: running first (most recent), then stopped (most recent)
+    summaries.sort((a, b) => {
+        if (a.status !== b.status) {
+            return a.status === 'running' ? -1 : 1;
+        }
+        return b.updatedAt.getTime() - a.updatedAt.getTime();
+    });
+    // Print table
+    printTable(summaries);
+}
+/**
+ * Format age as human-readable string.
+ */
+function formatAge(date) {
+    const now = Date.now();
+    const diffMs = now - date.getTime();
+    if (diffMs < 0)
+        return 'future';
+    const seconds = Math.floor(diffMs / 1000);
+    if (seconds < 60)
+        return `${seconds}s`;
+    const minutes = Math.floor(seconds / 60);
+    if (minutes < 60)
+        return `${minutes}m`;
+    const hours = Math.floor(minutes / 60);
+    if (hours < 24)
+        return `${hours}h`;
+    const days = Math.floor(hours / 24);
+    return `${days}d`;
+}
+/**
+ * Print formatted table of run summaries.
+ */
+function printTable(summaries) {
+    // Column headers
+    const headers = ['RUN ID', 'STATUS', 'PHASE', 'PROGRESS', 'AGE', 'STOP REASON', 'RESUMES', 'RISK', 'IN-FLIGHT'];
+    // Calculate column widths
+    const widths = headers.map((h, i) => {
+        const values = summaries.map(s => {
+            switch (i) {
+                case 0: return s.runId;
+                case 1: return s.status;
+                case 2: return s.phase;
+                case 3: return s.milestones;
+                case 4: return s.age;
+                case 5: return s.stopReason;
+                case 6: return String(s.autoResumeCount);
+                case 7: return s.collisionRisk;
+                case 8: return s.inFlight;
+                default: return '';
+            }
+        });
+        return Math.max(h.length, ...values.map(v => v.length));
+    });
+    // Print header
+    const headerLine = headers.map((h, i) => h.padEnd(widths[i])).join('  ');
+    console.log(headerLine);
+    console.log('-'.repeat(headerLine.length));
+    // Print rows
+    for (const s of summaries) {
+        const row = [
+            s.runId.padEnd(widths[0]),
+            s.status.padEnd(widths[1]),
+            s.phase.padEnd(widths[2]),
+            s.milestones.padEnd(widths[3]),
+            s.age.padEnd(widths[4]),
+            s.stopReason.padEnd(widths[5]),
+            String(s.autoResumeCount).padEnd(widths[6]),
+            s.collisionRisk.padEnd(widths[7]),
+            s.inFlight.padEnd(widths[8])
+        ];
+        console.log(row.join('  '));
+    }
+    // Print summary
+    const running = summaries.filter(s => s.status === 'running').length;
+    const stopped = summaries.filter(s => s.status === 'stopped').length;
+    const allowlistRisk = summaries.filter(s => s.collisionRisk === 'allowlist').length;
+    const collisionRisk = summaries.filter(s => s.collisionRisk === 'collision').length;
+    console.log('');
+    let summaryLine = `Total: ${summaries.length} runs (${running} running, ${stopped} stopped)`;
+    if (allowlistRisk > 0 || collisionRisk > 0) {
+        const riskParts = [];
+        if (allowlistRisk > 0)
+            riskParts.push(`${allowlistRisk} allowlist`);
+        if (collisionRisk > 0)
+            riskParts.push(`${collisionRisk} collision`);
+        summaryLine += ` — risk: ${riskParts.join(', ')}`;
+    }
+    console.log(summaryLine);
+}

package/dist/commands/summarize.js

@@ -0,0 +1,220 @@
+import { RunStore } from '../store/run-store.js';
+import { resolveRunId } from '../store/run-utils.js';
+import { getRunsRoot } from '../store/runs-root.js';
+import { computeKpiFromEvents } from './report.js';
+import { diagnoseStop, formatStopMarkdown } from '../diagnosis/index.js';
+import fs from 'node:fs';
+import path from 'node:path';
+import readline from 'node:readline';
+/**
+ * Generate a machine-readable JSON summary of a run.
+ * Outputs compact JSON to stdout for piping/parsing.
+ * Supports 'latest' as runId to resolve to most recent run.
+ */
+export async function summarizeCommand(options) {
+    // Resolve 'latest' to actual run ID and validate existence
+    const resolvedRunId = resolveRunId(options.runId, options.repo);
+    const runDir = path.join(getRunsRoot(options.repo), resolvedRunId);
+    const runStore = RunStore.init(resolvedRunId, options.repo);
+    const state = runStore.readState();
+    // Read timeline events for KPI computation
+    const timelinePath = path.join(runDir, 'timeline.jsonl');
+    const events = await readTimelineEvents(timelinePath);
+    const kpi = computeKpiFromEvents(events);
+    // Read config.snapshot.json for worktree_enabled and other config
+    const configSnapshot = readConfigSnapshot(runDir);
+    // Extract config flags from run_started event
+    const runStartedEvent = events.find((e) => e.type === 'run_started');
+    const configPayload = extractConfigPayload(runStartedEvent, configSnapshot);
+    // Get total milestones from state if available
+    const totalMilestones = state.milestones?.length ?? null;
+    // Extract ticks info from timeline events (sum across all sessions including resumes)
+    const ticksInfo = extractTicksInfo(events, state);
+    // Generate diagnosis for stopped runs (not for successful completions)
+    let diagnosisResult;
+    const isFailedStop = state.phase === 'STOPPED' && state.stop_reason !== 'complete';
+    if (isFailedStop) {
+        const diagnosisContext = {
+            runId: resolvedRunId,
+            runDir,
+            state: {
+                phase: state.phase,
+                stop_reason: state.stop_reason,
+                milestone_index: state.milestone_index,
+                milestones_total: state.milestones?.length ?? 0,
+                last_error: state.last_error
+            },
+            events,
+            configSnapshot: configSnapshot
+        };
+        diagnosisResult = diagnoseStop(diagnosisContext);
+        // Write diagnosis artifacts to handoffs directory
+        const handoffsDir = path.join(runDir, 'handoffs');
+        if (!fs.existsSync(handoffsDir)) {
+            fs.mkdirSync(handoffsDir, { recursive: true });
+        }
+        // Write stop.json
+        const stopJsonPath = path.join(handoffsDir, 'stop.json');
+        fs.writeFileSync(stopJsonPath, JSON.stringify(diagnosisResult, null, 2) + '\n', 'utf-8');
+        // Write stop.md
+        const stopMdPath = path.join(handoffsDir, 'stop.md');
+        const stopMd = formatStopMarkdown(diagnosisResult);
+        fs.writeFileSync(stopMdPath, stopMd + '\n', 'utf-8');
+    }
+    const summary = {
+        run_id: resolvedRunId,
+        outcome: kpi.outcome,
+        stop_reason: kpi.stop_reason,
+        duration_seconds: msToSeconds(kpi.total_duration_ms),
+        milestones: {
+            completed: kpi.milestones.completed,
+            total: totalMilestones
+        },
+        worker_calls: {
+            claude: kpi.workers.claude,
+            codex: kpi.workers.codex
+        },
+        verification: {
+            attempts: kpi.verify.attempts,
+            retries: kpi.verify.retries,
+            duration_seconds: msToSeconds(kpi.verify.total_duration_ms) ?? 0
+        },
+        reliability: {
+            infra_retries: kpi.reliability.infra_retries,
+            fallback_used: kpi.reliability.fallback_used,
+            fallback_count: kpi.reliability.fallback_count,
+            stalls_triggered: kpi.reliability.stalls_triggered,
+            late_results_ignored: kpi.reliability.late_results_ignored,
+            max_ticks_hit: ticksInfo.max_ticks_hit,
+            ticks_used: ticksInfo.ticks_used
+        },
+        config: configPayload,
+        timestamps: {
+            started_at: kpi.started_at,
+            ended_at: kpi.ended_at
+        },
+        diagnosis: diagnosisResult
+            ? {
+                primary: diagnosisResult.primary_diagnosis,
+                confidence: diagnosisResult.confidence,
+                next_action: diagnosisResult.next_actions[0]?.command
+            }
+            : undefined
+    };
+    // Write summary.json to run directory (idempotent - overwrites if exists)
+    const summaryPath = path.join(runDir, 'summary.json');
+    const formattedJson = JSON.stringify(summary, null, 2);
+    fs.writeFileSync(summaryPath, formattedJson + '\n', 'utf-8');
+    console.log(`Summary written to ${summaryPath}`);
+    // Log diagnosis info if available
+    if (diagnosisResult) {
+        const handoffsDir = path.join(runDir, 'handoffs');
+        console.log(`Diagnosis written to ${path.join(handoffsDir, 'stop.json')} and stop.md`);
+        console.log(`  Primary: ${diagnosisResult.primary_diagnosis} (${Math.round(diagnosisResult.confidence * 100)}%)`);
+        if (diagnosisResult.next_actions[0]) {
+            console.log(`  Next: ${diagnosisResult.next_actions[0].title}`);
+        }
+    }
+}
+async function readTimelineEvents(timelinePath) {
+    if (!fs.existsSync(timelinePath)) {
+        return [];
+    }
+    const events = [];
+    const stream = fs.createReadStream(timelinePath, { encoding: 'utf-8' });
+    const rl = readline.createInterface({ input: stream, crlfDelay: Infinity });
+    for await (const line of rl) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        try {
+            const event = JSON.parse(trimmed);
+            events.push(event);
+        }
+        catch {
+            // Skip malformed lines
+        }
+    }
+    return events;
+}
+function readConfigSnapshot(runDir) {
+    const snapshotPath = path.join(runDir, 'config.snapshot.json');
+    // Handle missing config.snapshot.json gracefully with defaults
+    if (!fs.existsSync(snapshotPath)) {
+        return {
+            worktree_enabled: false
+        };
+    }
+    try {
+        const raw = fs.readFileSync(snapshotPath, 'utf-8');
+        const parsed = JSON.parse(raw);
+        // worktree_enabled is determined by presence of _worktree field
+        const worktreeEnabled = parsed._worktree !== undefined && parsed._worktree !== null;
+        return {
+            worktree_enabled: worktreeEnabled
+        };
+    }
+    catch {
+        // Handle parse errors gracefully with defaults
+        return {
+            worktree_enabled: false
+        };
+    }
+}
+function extractConfigPayload(runStartedEvent, configSnapshot) {
+    const defaults = {
+        dry_run: null,
+        no_branch: null,
+        allow_dirty: null,
+        allow_deps: null,
+        worktree_enabled: configSnapshot?.worktree_enabled ?? false,
+        time_budget_minutes: null,
+        max_ticks: null
+    };
+    if (!runStartedEvent?.payload || typeof runStartedEvent.payload !== 'object') {
+        return defaults;
+    }
+    const payload = runStartedEvent.payload;
+    return {
+        dry_run: payload.dry_run ?? null,
+        no_branch: payload.no_branch ?? null,
+        allow_dirty: payload.allow_dirty ?? null,
+        allow_deps: payload.allow_deps ?? null,
+        worktree_enabled: configSnapshot?.worktree_enabled ?? false,
+        time_budget_minutes: payload.time_budget_minutes ?? null,
+        max_ticks: payload.max_ticks ?? null
+    };
+}
+function msToSeconds(ms) {
+    if (ms === null)
+        return null;
+    return Math.round(ms / 1000);
+}
+/**
+ * Extract ticks info from timeline events and state.
+ * Sums ticks_used across all sessions (including resumes).
+ */
+function extractTicksInfo(events, state) {
+    // Check if stop_reason indicates max_ticks_reached
+    const stopReason = state.stop_reason;
+    const maxTicksHit = stopReason === 'max_ticks_reached';
+    // Sum ticks_used from max_ticks_reached events and stop events with ticks_used
+    let totalTicks = 0;
+    for (const event of events) {
+        if (event.type === 'max_ticks_reached' || event.type === 'stop') {
+            const payload = event.payload;
+            const ticksUsed = payload?.ticks_used;
+            if (typeof ticksUsed === 'number') {
+                totalTicks += ticksUsed;
+            }
+        }
+    }
+    // If no ticks_used found in events, estimate from phase_start count
+    if (totalTicks === 0) {
+        totalTicks = events.filter((e) => e.type === 'phase_start').length;
+    }
+    return {
+        max_ticks_hit: maxTicksHit,
+        ticks_used: totalTicks
+    };
+}

package/dist/commands/version.js

@@ -0,0 +1,82 @@
+/**
+ * Version command.
+ *
+ * Outputs version information in JSON or human-readable format.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { execSync } from 'node:child_process';
+// Get agent version from package.json
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const packageJsonPath = path.resolve(__dirname, '../../package.json');
+const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
+const AGENT_VERSION = packageJson.version;
+/**
+ * Current artifact schema version.
+ * This should match the schema_version stamped into all artifacts.
+ */
+export const ARTIFACT_SCHEMA_VERSION = 1;
+/**
+ * Get the current git commit hash (short form).
+ * Returns null if not in a git repo or git not available.
+ */
+function getGitCommit() {
+    // Check CI environment variables first
+    const ciCommit = process.env.GITHUB_SHA
+        || process.env.CI_COMMIT_SHA
+        || process.env.GIT_COMMIT;
+    if (ciCommit) {
+        return ciCommit.slice(0, 7);
+    }
+    // Try git command (best-effort, non-fatal)
+    try {
+        const commit = execSync('git rev-parse --short HEAD', {
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'ignore']
+        }).trim();
+        return commit || null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Build version output object.
+ */
+export function getVersionInfo() {
+    return {
+        schema_version: 1,
+        agent_version: AGENT_VERSION,
+        artifact_schema_version: ARTIFACT_SCHEMA_VERSION,
+        node: process.version,
+        platform: process.platform,
+        commit: getGitCommit()
+    };
+}
+/**
+ * Format version for human-readable output.
+ */
+function formatVersion(info) {
+    const lines = [];
+    lines.push(`Agent Runner v${info.agent_version}`);
+    lines.push(`  Artifact Schema: v${info.artifact_schema_version}`);
+    lines.push(`  Node: ${info.node}`);
+    lines.push(`  Platform: ${info.platform}`);
+    if (info.commit) {
+        lines.push(`  Commit: ${info.commit}`);
+    }
+    return lines.join('\n');
+}
+/**
+ * Run the version command.
+ */
+export async function versionCommand(options) {
+    const info = getVersionInfo();
+    if (options.json) {
+        console.log(JSON.stringify(info, null, 2));
+    }
+    else {
+        console.log(formatVersion(info));
+    }
+}

package/dist/commands/wait.js

@@ -0,0 +1,170 @@
+/**
+ * agent wait - Block until run reaches terminal state.
+ *
+ * Designed for meta-agent coordination. Returns machine-readable JSON
+ * with run outcome, suitable for scripting and automation.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { getRunsRoot } from '../store/runs-root.js';
+/**
+ * Current schema version for WaitResult.
+ * Increment when making breaking changes to the structure.
+ */
+export const WAIT_RESULT_SCHEMA_VERSION = 1;
+const TERMINAL_PHASES = ['STOPPED', 'DONE'];
+const POLL_INTERVAL_MS = 500;
+const BACKOFF_MAX_MS = 2000;
+function readState(statePath) {
+    if (!fs.existsSync(statePath)) {
+        return null;
+    }
+    try {
+        const content = fs.readFileSync(statePath, 'utf-8');
+        return JSON.parse(content);
+    }
+    catch {
+        return null;
+    }
+}
+function isTerminal(state) {
+    return TERMINAL_PHASES.includes(state.phase);
+}
+function matchesCondition(state, condition) {
+    if (!isTerminal(state))
+        return false;
+    switch (condition) {
+        case 'terminal':
+            return true;
+        case 'complete':
+            return state.stop_reason === 'complete';
+        case 'stop':
+            return state.stop_reason !== 'complete';
+        default:
+            return true;
+    }
+}
+function buildResult(runId, runDir, repoRoot, state, elapsedMs, timedOut) {
+    const isComplete = state.stop_reason === 'complete';
+    const result = {
+        schema_version: WAIT_RESULT_SCHEMA_VERSION,
+        run_id: runId,
+        run_dir: runDir,
+        repo_root: repoRoot,
+        status: timedOut ? 'timeout' : isComplete ? 'complete' : 'stopped',
+        phase: state.phase,
+        progress: {
+            milestone: state.milestone_index + 1,
+            of: state.milestones.length
+        },
+        elapsed_ms: elapsedMs,
+        ts: new Date().toISOString()
+    };
+    if (state.stop_reason && state.stop_reason !== 'complete') {
+        result.stop_reason = state.stop_reason;
+    }
+    // Add resume command for non-complete stops
+    if (!isComplete && !timedOut) {
+        result.resume_command = `agent resume ${runId}`;
+    }
+    // Add collision info if relevant
+    if (state.stop_reason === 'parallel_file_collision') {
+        // Could extract from timeline, but for now just flag it
+        result.collision_info = {};
+    }
+    return result;
+}
+function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+export async function waitCommand(options) {
+    const runDir = path.join(getRunsRoot(options.repo), options.runId);
+    const statePath = path.join(runDir, 'state.json');
+    if (!fs.existsSync(runDir)) {
+        if (options.json) {
+            console.log(JSON.stringify({
+                error: 'run_not_found',
+                run_id: options.runId,
+                message: `Run directory not found: ${runDir}`
+            }));
+        }
+        else {
+            console.error(`Run directory not found: ${runDir}`);
+        }
+        process.exitCode = 1;
+        return;
+    }
+    const repoRoot = path.resolve(options.repo);
+    const startTime = Date.now();
+    const timeoutMs = options.timeout ?? Infinity;
+    let pollInterval = POLL_INTERVAL_MS;
+    let lastState = null;
+    while (true) {
+        const elapsed = Date.now() - startTime;
+        // Check timeout
+        if (elapsed >= timeoutMs) {
+            const state = readState(statePath);
+            if (state) {
+                const result = buildResult(options.runId, runDir, repoRoot, state, elapsed, true);
+                if (options.json) {
+                    console.log(JSON.stringify(result, null, 2));
+                }
+                else {
+                    console.log(`Timeout after ${Math.round(elapsed / 1000)}s`);
+                    console.log(`Current phase: ${state.phase}`);
+                    console.log(`Progress: ${state.milestone_index + 1}/${state.milestones.length}`);
+                }
+            }
+            process.exitCode = 124; // timeout exit code (like GNU timeout)
+            return;
+        }
+        // Read current state
+        const state = readState(statePath);
+        if (!state) {
+            await sleep(pollInterval);
+            continue;
+        }
+        lastState = state;
+        // Check if condition is met
+        if (matchesCondition(state, options.for)) {
+            const result = buildResult(options.runId, runDir, repoRoot, state, elapsed, false);
+            if (options.json) {
+                console.log(JSON.stringify(result, null, 2));
+            }
+            else {
+                const statusWord = result.status === 'complete' ? 'Completed' : 'Stopped';
+                console.log(`${statusWord} after ${Math.round(elapsed / 1000)}s`);
+                console.log(`Phase: ${state.phase}`);
+                console.log(`Progress: ${result.progress.milestone}/${result.progress.of}`);
+                if (result.stop_reason) {
+                    console.log(`Reason: ${result.stop_reason}`);
+                }
+                if (result.resume_command) {
+                    console.log(`Resume: ${result.resume_command}`);
+                }
+            }
+            // Exit code: 0 for complete, 1 for stop
+            process.exitCode = result.status === 'complete' ? 0 : 1;
+            return;
+        }
+        // Backoff polling interval
+        pollInterval = Math.min(pollInterval * 1.2, BACKOFF_MAX_MS);
+        await sleep(pollInterval);
+    }
+}
+/**
+ * Find the latest run ID for --latest flag.
+ */
+export function findLatestRunId(repoPath) {
+    const runsDir = getRunsRoot(repoPath);
+    if (!fs.existsSync(runsDir)) {
+        return null;
+    }
+    const runIds = fs
+        .readdirSync(runsDir, { withFileTypes: true })
+        .filter((e) => e.isDirectory() && /^\d{14}$/.test(e.name))
+        .map((e) => e.name)
+        .sort()
+        .reverse();
+    return runIds[0] ?? null;
+}