@weldr/runr 0.3.0

package/dist/supervisor/scope-guard.js

@@ -0,0 +1,55 @@
+import path from 'node:path';
+import picomatch from 'picomatch';
+function toPosix(filePath) {
+    return filePath.split(path.sep).join('/');
+}
+function compile(patterns) {
+    return patterns.map((p) => picomatch(p));
+}
+function matchesAny(matchers, s) {
+    return matchers.some((m) => m(s));
+}
+/**
+ * Partition changed files into env artifacts vs semantic changes.
+ * Env artifacts (matching env_allowlist) are allowed noise that shouldn't
+ * trigger dirty_worktree or scope_violation.
+ */
+export function partitionChangedFiles(changedFiles, envAllowlist) {
+    const envMatchers = compile(envAllowlist);
+    const env_touched = [];
+    const semantic_changed = [];
+    for (const file of changedFiles) {
+        const posixFile = toPosix(file);
+        if (envMatchers.length > 0 && matchesAny(envMatchers, posixFile)) {
+            env_touched.push(file);
+        }
+        else {
+            semantic_changed.push(file);
+        }
+    }
+    return { env_touched, semantic_changed };
+}
+export function checkScope(changedFiles, allowlist, denylist) {
+    const allowMatchers = allowlist.map((pattern) => picomatch(pattern));
+    const denyMatchers = denylist.map((pattern) => picomatch(pattern));
+    const violations = [];
+    for (const file of changedFiles) {
+        const posixFile = toPosix(file);
+        if (denyMatchers.some((match) => match(posixFile))) {
+            violations.push(file);
+            continue;
+        }
+        if (allowMatchers.length > 0 && !allowMatchers.some((match) => match(posixFile))) {
+            violations.push(file);
+        }
+    }
+    return { ok: violations.length === 0, violations };
+}
+export function checkLockfiles(changedFiles, lockfiles, allowDeps) {
+    if (allowDeps) {
+        return { ok: true, violations: [] };
+    }
+    const lockfileSet = new Set(lockfiles);
+    const violations = changedFiles.filter((file) => lockfileSet.has(file));
+    return { ok: violations.length === 0, violations };
+}

package/dist/supervisor/state-machine.js

@@ -0,0 +1,121 @@
+import { buildMilestonesFromTask } from './planner.js';
+/**
+ * Creates initial run state with all timestamps set.
+ *
+ * Progress Tracking Design:
+ * - `started_at`: Run start time (never changes)
+ * - `updated_at`: Last state mutation (any write)
+ * - `phase_started_at`: Current phase start time
+ * - `last_progress_at`: Last meaningful work (for stall detection)
+ *
+ * The supervisor's `recordProgress()` is the canonical way to mark progress.
+ * It updates both `last_progress_at` and `updated_at` together.
+ */
+export function createInitialState(input) {
+    const now = new Date().toISOString();
+    const milestones = buildMilestonesFromTask(input.task_text);
+    return {
+        run_id: input.run_id,
+        repo_path: input.repo_path,
+        phase: 'INIT',
+        milestone_index: 0,
+        milestones,
+        owned_paths: input.owned_paths,
+        scope_lock: {
+            allowlist: input.allowlist,
+            denylist: input.denylist
+        },
+        risk_score: 0,
+        retries: 0,
+        milestone_retries: 0,
+        resume_token: input.run_id,
+        phase_started_at: now,
+        phase_attempt: 0,
+        started_at: now,
+        updated_at: now,
+        last_progress_at: now,
+        worker_stats: {
+            claude: 0,
+            codex: 0,
+            by_phase: {
+                plan: { claude: 0, codex: 0 },
+                implement: { claude: 0, codex: 0 },
+                review: { claude: 0, codex: 0 }
+            }
+        }
+    };
+}
+export function updatePhase(state, phase) {
+    const now = new Date().toISOString();
+    const phaseAttempt = state.phase === phase ? state.phase_attempt + 1 : 1;
+    return {
+        ...state,
+        phase,
+        last_successful_phase: state.phase,
+        phase_started_at: now,
+        phase_attempt: phaseAttempt,
+        updated_at: now
+    };
+}
+export function stopRun(state, reason) {
+    const now = new Date().toISOString();
+    return {
+        ...state,
+        phase: 'STOPPED',
+        stop_reason: reason,
+        updated_at: now,
+        phase_started_at: now
+    };
+}
+/**
+ * Canonical phase order for determining resume target.
+ * Used by both manual resume command and auto-resume.
+ */
+const PHASE_ORDER = ['INIT', 'PLAN', 'IMPLEMENT', 'VERIFY', 'REVIEW', 'CHECKPOINT', 'FINALIZE'];
+/**
+ * Compute the target phase to resume from based on last successful phase.
+ * Shared between resume command and auto-resume to prevent drift.
+ *
+ * Logic:
+ * - If STOPPED with last_successful_phase, resume from phase after that
+ * - If at FINALIZE, stay at FINALIZE
+ * - Otherwise use current phase (for non-STOPPED states)
+ */
+export function computeResumeTargetPhase(state) {
+    // If not stopped, just use current phase
+    if (state.phase !== 'STOPPED') {
+        return state.phase;
+    }
+    // If we have a last successful phase, resume from the next one
+    if (state.last_successful_phase) {
+        const lastIdx = PHASE_ORDER.indexOf(state.last_successful_phase);
+        if (lastIdx >= 0 && lastIdx < PHASE_ORDER.length - 1) {
+            return PHASE_ORDER[lastIdx + 1];
+        }
+        // At FINALIZE or beyond, stay there
+        return state.last_successful_phase;
+    }
+    // No last successful phase, start from INIT
+    return 'INIT';
+}
+/**
+ * Prepare state for resumption (manual or auto).
+ * Clears stop state, sets resume phase, optionally increments auto_resume_count.
+ */
+export function prepareForResume(state, options = {}) {
+    const now = new Date().toISOString();
+    const targetPhase = computeResumeTargetPhase(state);
+    const autoResumeCount = state.auto_resume_count ?? 0;
+    return {
+        ...state,
+        phase: targetPhase,
+        stop_reason: undefined,
+        last_error: undefined,
+        resume_token: options.resumeToken ?? state.run_id,
+        updated_at: now,
+        phase_started_at: now,
+        auto_resume_count: options.incrementAutoResumeCount
+            ? autoResumeCount + 1
+            : autoResumeCount
+    };
+}

package/dist/supervisor/verification-policy.js

@@ -0,0 +1,64 @@
+import picomatch from 'picomatch';
+const ORDERED_TIERS = ['tier0', 'tier1', 'tier2'];
+export function selectTiersWithReasons(policy, context) {
+    const tiers = new Set();
+    const reasons = [];
+    tiers.add('tier0');
+    reasons.push('tier0_always');
+    const matches = triggerMatches(policy, context.changed_files);
+    const highRiskMatches = matches.filter((match) => match.tier !== 'tier0');
+    if (highRiskMatches.length > 0) {
+        tiers.add('tier1');
+        for (const match of highRiskMatches) {
+            reasons.push(`risk_trigger:${match.name}`);
+        }
+    }
+    if (context.is_milestone_end) {
+        tiers.add('tier1');
+        reasons.push('milestone_end');
+    }
+    if (context.risk_level === 'high') {
+        tiers.add('tier1');
+        reasons.push('risk_level_high');
+    }
+    if (context.is_run_end) {
+        tiers.add('tier2');
+        reasons.push('run_end');
+    }
+    const selected = ORDERED_TIERS.filter((tier) => tiers.has(tier));
+    return { tiers: selected, reasons };
+}
+export function selectTiers(policy, context) {
+    return selectTiersWithReasons(policy, context).tiers;
+}
+export function triggerTiers(policy, changedFiles) {
+    const tiers = new Set();
+    for (const match of triggerMatches(policy, changedFiles)) {
+        tiers.add(match.tier);
+    }
+    return Array.from(tiers);
+}
+export function triggerMatches(policy, changedFiles) {
+    if (!policy.risk_triggers.length) {
+        return [];
+    }
+    const matches = [];
+    const files = changedFiles.map((file) => file.replace(/\\/g, '/'));
+    for (const trigger of policy.risk_triggers) {
+        const matcher = picomatch(trigger.patterns);
+        if (files.some((file) => matcher(file))) {
+            const tier = trigger.tier === 'tier2' ? 'tier1' : trigger.tier;
+            matches.push({ name: trigger.name, tier });
+        }
+    }
+    return matches;
+}
+export function commandsForTier(policy, tier) {
+    if (tier === 'tier0') {
+        return policy.tier0;
+    }
+    if (tier === 'tier1') {
+        return policy.tier1;
+    }
+    return policy.tier2;
+}

package/dist/tasks/task-metadata.js

@@ -0,0 +1,72 @@
+import fs from 'node:fs';
+import yaml from 'yaml';
+import { normalizeOwnsPatterns } from '../ownership/normalize.js';
+// Re-export for backward compatibility
+export { normalizeOwnsPatterns } from '../ownership/normalize.js';
+function hasFrontmatter(raw) {
+    const trimmed = raw.startsWith('\ufeff') ? raw.slice(1) : raw;
+    return trimmed.startsWith('---');
+}
+function splitFrontmatter(raw) {
+    const trimmed = raw.startsWith('\ufeff') ? raw.slice(1) : raw;
+    if (!hasFrontmatter(trimmed)) {
+        return { frontmatterText: null, body: raw };
+    }
+    const lines = trimmed.split(/\r?\n/);
+    if (lines[0].trim() !== '---') {
+        return { frontmatterText: null, body: raw };
+    }
+    const endIdx = lines.findIndex((line, idx) => idx > 0 && line.trim() === '---');
+    if (endIdx === -1) {
+        return { frontmatterText: null, body: raw };
+    }
+    const frontmatterText = lines.slice(1, endIdx).join('\n');
+    const body = lines.slice(endIdx + 1).join('\n');
+    return { frontmatterText, body };
+}
+function coerceOwns(value, taskPath) {
+    if (value === undefined || value === null) {
+        return [];
+    }
+    if (typeof value === 'string') {
+        return [value];
+    }
+    if (Array.isArray(value)) {
+        const nonStrings = value.filter((item) => typeof item !== 'string');
+        if (nonStrings.length > 0) {
+            throw new Error(`Invalid owns entry in ${taskPath}: must be string or string[]`);
+        }
+        return value;
+    }
+    throw new Error(`Invalid owns entry in ${taskPath}: must be string or string[]`);
+}
+export function loadTaskMetadata(taskPath) {
+    const raw = fs.readFileSync(taskPath, 'utf-8');
+    const { frontmatterText, body } = splitFrontmatter(raw);
+    let frontmatter = null;
+    let ownsRaw = [];
+    if (frontmatterText !== null) {
+        try {
+            const parsed = yaml.parse(frontmatterText);
+            if (parsed && typeof parsed === 'object') {
+                frontmatter = parsed;
+            }
+            else {
+                frontmatter = {};
+            }
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            throw new Error(`Failed to parse task frontmatter in ${taskPath}: ${message}`);
+        }
+        ownsRaw = coerceOwns(frontmatter.owns, taskPath);
+    }
+    const ownsNormalized = normalizeOwnsPatterns(ownsRaw);
+    return {
+        raw,
+        body,
+        owns_raw: ownsRaw,
+        owns_normalized: ownsNormalized,
+        frontmatter
+    };
+}

package/dist/types/schemas.js

@@ -0,0 +1 @@
+export {};

package/dist/verification/engine.js

@@ -0,0 +1,49 @@
+import { execa } from 'execa';
+export async function runVerification(tier, commands, cwd, timeoutSeconds) {
+    const started = Date.now();
+    let output = '';
+    let ok = true;
+    const commandResults = [];
+    for (const command of commands) {
+        try {
+            const result = await execa(command, {
+                cwd,
+                shell: true,
+                timeout: timeoutSeconds * 1000,
+                all: true
+            });
+            const cmdOutput = result.all ? `${result.all}\n` : '';
+            output += cmdOutput;
+            commandResults.push({
+                command,
+                exit_code: 0,
+                output: cmdOutput
+            });
+        }
+        catch (error) {
+            ok = false;
+            const errWithCode = error;
+            const exitCode = typeof errWithCode.exitCode === 'number' ? errWithCode.exitCode : 1;
+            const errorOutput = typeof errWithCode.all === 'string'
+                ? errWithCode.all
+                : error instanceof Error
+                    ? error.message
+                    : 'Verification command failed';
+            output += `${errorOutput}\n`;
+            commandResults.push({
+                command,
+                exit_code: exitCode,
+                output: errorOutput
+            });
+            break;
+        }
+    }
+    return {
+        tier,
+        commands,
+        command_results: commandResults,
+        ok,
+        duration_ms: Date.now() - started,
+        output
+    };
+}

package/dist/workers/__tests__/claude.test.js

@@ -0,0 +1,88 @@
+import { describe, it, expect } from 'vitest';
+function extractTextFromClaudeJson(output) {
+    try {
+        const parsed = JSON.parse(output);
+        return parsed.result || parsed.content || parsed.message || output;
+    }
+    catch {
+        // If not valid JSON, return raw output
+        return output;
+    }
+}
+describe('extractTextFromClaudeJson', () => {
+    it('extracts result field from valid JSON', () => {
+        const input = '{"result":"Hello World"}';
+        expect(extractTextFromClaudeJson(input)).toBe('Hello World');
+    });
+    it('extracts content field when result is missing', () => {
+        const input = '{"content":"Content text","other":"ignored"}';
+        expect(extractTextFromClaudeJson(input)).toBe('Content text');
+    });
+    it('extracts message field as fallback', () => {
+        const input = '{"message":"Message text"}';
+        expect(extractTextFromClaudeJson(input)).toBe('Message text');
+    });
+    it('returns raw output when not valid JSON', () => {
+        const input = 'This is plain text, not JSON';
+        expect(extractTextFromClaudeJson(input)).toBe('This is plain text, not JSON');
+    });
+    it('returns raw output for truncated JSON', () => {
+        const input = '{"result":"trun';
+        expect(extractTextFromClaudeJson(input)).toBe('{"result":"trun');
+    });
+    it('returns raw output for empty object with no known fields', () => {
+        const input = '{"unknown":"field"}';
+        // Returns the original input since result/content/message are all falsy
+        expect(extractTextFromClaudeJson(input)).toBe('{"unknown":"field"}');
+    });
+    it('handles empty string result', () => {
+        const input = '{"result":"","content":"fallback"}';
+        // Empty string is falsy, so falls through to content
+        expect(extractTextFromClaudeJson(input)).toBe('fallback');
+    });
+    it('handles null values', () => {
+        const input = '{"result":null,"content":"actual content"}';
+        expect(extractTextFromClaudeJson(input)).toBe('actual content');
+    });
+    it('handles nested JSON in result', () => {
+        const input = '{"result":"{\\"nested\\":\\"json\\"}"}';
+        expect(extractTextFromClaudeJson(input)).toBe('{"nested":"json"}');
+    });
+    it('handles array response gracefully', () => {
+        const input = '["array","response"]';
+        // Arrays don't have result/content/message, returns original
+        expect(extractTextFromClaudeJson(input)).toBe('["array","response"]');
+    });
+    it('handles error field in response', () => {
+        const input = '{"error":"Something went wrong","result":""}';
+        // Empty result is falsy, but we don't currently use error field
+        // This returns the raw input since result/content/message are empty/missing
+        expect(extractTextFromClaudeJson(input)).toBe('{"error":"Something went wrong","result":""}');
+    });
+    it('handles whitespace in output', () => {
+        const input = '  {"result":"with spaces"}  ';
+        // JSON.parse handles leading/trailing whitespace
+        expect(extractTextFromClaudeJson(input)).toBe('with spaces');
+    });
+    it('handles newlines in result text', () => {
+        const input = '{"result":"line1\\nline2\\nline3"}';
+        expect(extractTextFromClaudeJson(input)).toBe('line1\nline2\nline3');
+    });
+});
+describe('Claude JSON error handling', () => {
+    it('fails loud on completely invalid input', () => {
+        // Current implementation returns the raw output, which is reasonable
+        // but we might want to distinguish "valid text" from "parse error" later
+        const input = '}{invalid';
+        const result = extractTextFromClaudeJson(input);
+        // Currently returns raw - this is acceptable behavior
+        expect(result).toBe('}{invalid');
+    });
+    it('handles BOM characters', () => {
+        const input = '\uFEFF{"result":"with BOM"}';
+        // JSON.parse may fail with BOM prefix
+        const result = extractTextFromClaudeJson(input);
+        // Should either parse successfully or return raw
+        expect(result.includes('with BOM') || result.includes('\uFEFF')).toBe(true);
+    });
+});

package/dist/workers/__tests__/codex.test.js

@@ -0,0 +1,81 @@
+import { describe, it, expect } from 'vitest';
+function extractTextFromCodexJsonl(output) {
+    const lines = output.trim().split('\n').filter(Boolean);
+    const texts = [];
+    for (const line of lines) {
+        try {
+            const event = JSON.parse(line);
+            if (event.type === 'item.completed' && event.item?.type === 'agent_message' && event.item.text) {
+                texts.push(event.item.text);
+            }
+        }
+        catch {
+            // Skip malformed lines
+        }
+    }
+    return texts.join('\n');
+}
+describe('extractTextFromCodexJsonl', () => {
+    it('extracts agent_message text from valid JSONL', () => {
+        const input = `{"type":"thread.started","thread_id":"abc123"}
+{"type":"turn.started"}
+{"type":"item.completed","item":{"id":"item_0","type":"reasoning","text":"thinking..."}}
+{"type":"item.completed","item":{"id":"item_1","type":"agent_message","text":"HELLO WORLD"}}
+{"type":"turn.completed","usage":{"input_tokens":100,"output_tokens":10}}`;
+        const result = extractTextFromCodexJsonl(input);
+        expect(result).toBe('HELLO WORLD');
+    });
+    it('concatenates multiple agent_message items', () => {
+        const input = `{"type":"item.completed","item":{"type":"agent_message","text":"First message"}}
+{"type":"item.completed","item":{"type":"agent_message","text":"Second message"}}`;
+        const result = extractTextFromCodexJsonl(input);
+        expect(result).toBe('First message\nSecond message');
+    });
+    it('ignores reasoning and command_execution items', () => {
+        const input = `{"type":"item.completed","item":{"type":"reasoning","text":"I should run git status"}}
+{"type":"item.completed","item":{"type":"command_execution","command":"git status","aggregated_output":"clean"}}
+{"type":"item.completed","item":{"type":"agent_message","text":"Done!"}}`;
+        const result = extractTextFromCodexJsonl(input);
+        expect(result).toBe('Done!');
+    });
+    it('handles malformed JSON lines gracefully', () => {
+        const input = `{"type":"item.completed","item":{"type":"agent_message","text":"Valid"}}
+this is not json
+{"broken json
+{"type":"item.completed","item":{"type":"agent_message","text":"Also valid"}}`;
+        const result = extractTextFromCodexJsonl(input);
+        expect(result).toBe('Valid\nAlso valid');
+    });
+    it('returns empty string when no agent_message found', () => {
+        const input = `{"type":"thread.started","thread_id":"abc"}
+{"type":"turn.started"}
+{"type":"item.completed","item":{"type":"reasoning","text":"thinking"}}
+{"type":"turn.completed"}`;
+        const result = extractTextFromCodexJsonl(input);
+        expect(result).toBe('');
+    });
+    it('handles empty input', () => {
+        expect(extractTextFromCodexJsonl('')).toBe('');
+        expect(extractTextFromCodexJsonl('   ')).toBe('');
+        expect(extractTextFromCodexJsonl('\n\n')).toBe('');
+    });
+    it('handles missing item.text gracefully', () => {
+        const input = `{"type":"item.completed","item":{"type":"agent_message"}}
+{"type":"item.completed","item":{"type":"agent_message","text":""}}
+{"type":"item.completed","item":{"type":"agent_message","text":"Has text"}}`;
+        const result = extractTextFromCodexJsonl(input);
+        expect(result).toBe('Has text');
+    });
+    it('handles control characters and unicode', () => {
+        const input = `{"type":"item.completed","item":{"type":"agent_message","text":"Hello\\nWorld\\twith\\ttabs"}}`;
+        const result = extractTextFromCodexJsonl(input);
+        expect(result).toBe('Hello\nWorld\twith\ttabs');
+    });
+    it('handles carriage returns in output', () => {
+        const input = `{"type":"item.completed","item":{"type":"agent_message","text":"Line1"}}\r\n{"type":"item.completed","item":{"type":"agent_message","text":"Line2"}}`;
+        const result = extractTextFromCodexJsonl(input);
+        // After trim and split, we should still get both messages
+        expect(result).toContain('Line1');
+        expect(result).toContain('Line2');
+    });
+});

package/dist/workers/claude.js

@@ -0,0 +1,119 @@
+import { execa } from 'execa';
+function extractTextFromClaudeJson(output) {
+    try {
+        const parsed = JSON.parse(output);
+        return parsed.result || parsed.content || parsed.message || output;
+    }
+    catch {
+        // If not valid JSON, return raw output
+        return output;
+    }
+}
+export async function runClaude(input) {
+    const { bin, args } = input.worker;
+    try {
+        const result = await execa(bin, args, {
+            cwd: input.repo_path,
+            input: input.prompt,
+            stdout: 'pipe',
+            stderr: 'pipe',
+            timeout: 300000 // 5 min timeout
+        });
+        const rawOutput = result.stdout;
+        const text = input.worker.output === 'json'
+            ? extractTextFromClaudeJson(rawOutput)
+            : rawOutput;
+        return {
+            status: result.exitCode === 0 ? 'ok' : 'failed',
+            commands_run: [`${bin} ${args.join(' ')}`],
+            observations: [text || rawOutput]
+        };
+    }
+    catch (error) {
+        const err = error;
+        const output = err.stdout || err.stderr || err.message || 'Claude command failed';
+        return {
+            status: 'failed',
+            commands_run: [`${bin} ${args.join(' ')}`],
+            observations: [output]
+        };
+    }
+}
+/**
+ * Classify error output into categories for preflight reporting.
+ */
+function classifyError(output) {
+    const lower = output.toLowerCase();
+    // Auth errors
+    if (lower.includes('oauth') || lower.includes('token expired') ||
+        lower.includes('authentication') || lower.includes('login') ||
+        lower.includes('401') || lower.includes('unauthorized') ||
+        lower.includes('not authenticated') || lower.includes('sign in')) {
+        return 'auth';
+    }
+    // Network errors
+    if (lower.includes('enotfound') || lower.includes('econnrefused') ||
+        lower.includes('network') || lower.includes('timeout') ||
+        lower.includes('econnreset') || lower.includes('socket')) {
+        return 'network';
+    }
+    // Rate limit errors
+    if (lower.includes('rate limit') || lower.includes('429') ||
+        lower.includes('too many requests') || lower.includes('quota')) {
+        return 'rate_limit';
+    }
+    return 'unknown';
+}
+/**
+ * Ping Claude to verify auth and connectivity.
+ * Success = process exits 0 within timeout.
+ */
+export async function pingClaude(worker) {
+    const { bin, args } = worker;
+    const start = Date.now();
+    const pingPrompt = 'Respond with exactly: ok';
+    try {
+        const result = await execa(bin, args, {
+            input: pingPrompt,
+            stdout: 'pipe',
+            stderr: 'pipe',
+            timeout: 15000 // 15s timeout for ping
+        });
+        const ms = Date.now() - start;
+        // Success = exit code 0
+        if (result.exitCode === 0) {
+            return { ok: true, worker: 'claude', ms };
+        }
+        // Non-zero exit
+        const output = result.stderr || result.stdout || '';
+        return {
+            ok: false,
+            worker: 'claude',
+            ms,
+            category: classifyError(output),
+            message: output.slice(0, 200)
+        };
+    }
+    catch (error) {
+        const ms = Date.now() - start;
+        const err = error;
+        const output = err.stderr || err.stdout || err.message || 'Ping failed';
+        // Check for timeout
+        if (err.code === 'ETIMEDOUT' || (err.message && err.message.includes('timed out'))) {
+            return {
+                ok: false,
+                worker: 'claude',
+                ms,
+                category: 'network',
+                message: 'Ping timed out'
+            };
+        }
+        return {
+            ok: false,
+            worker: 'claude',
+            ms,
+            category: classifyError(output),
+            message: output.slice(0, 200)
+        };
+    }
+}