@weldr/runr 0.3.0

package/dist/diagnosis/formatter.js

@@ -0,0 +1,136 @@
+/**
+ * Formatter for human-readable diagnosis output.
+ */
+/**
+ * Human-readable descriptions for each diagnosis category.
+ */
+const categoryDescriptions = {
+    auth_expired: 'Worker authentication expired or invalid.',
+    verification_cwd_mismatch: 'Verification commands ran in the wrong directory.',
+    scope_violation: 'Files were modified outside the allowed scope.',
+    lockfile_restricted: 'Lockfile was modified but dependency changes are not allowed.',
+    verification_failure: 'Tests, linting, or type checks failed.',
+    worker_parse_failure: 'Worker returned malformed or unparseable response.',
+    stall_timeout: 'No progress detected for too long.',
+    max_ticks_reached: 'Reached maximum phase transitions before completion.',
+    time_budget_exceeded: 'Ran out of allocated time.',
+    guard_violation_dirty: 'Working directory has uncommitted changes.',
+    ownership_violation: 'Task modified files outside its declared owns: paths.',
+    unknown: 'Could not determine specific cause.'
+};
+/**
+ * Format diagnosis as human-readable markdown.
+ */
+export function formatStopMarkdown(diagnosis) {
+    const lines = [];
+    // Header
+    lines.push('# Stop Diagnosis');
+    lines.push('');
+    // What happened
+    lines.push('## What Happened');
+    lines.push('');
+    lines.push(`- **Run ID**: ${diagnosis.run_id}`);
+    lines.push(`- **Outcome**: ${diagnosis.outcome}`);
+    lines.push(`- **Stop Reason**: ${diagnosis.stop_reason ?? 'N/A'}`);
+    lines.push('');
+    // Probable cause
+    lines.push('## Probable Cause');
+    lines.push('');
+    lines.push(`**${formatCategory(diagnosis.primary_diagnosis)}** (${Math.round(diagnosis.confidence * 100)}% confidence)`);
+    lines.push('');
+    lines.push(categoryDescriptions[diagnosis.primary_diagnosis]);
+    lines.push('');
+    // Evidence
+    if (diagnosis.signals.length > 0) {
+        lines.push('## Evidence');
+        lines.push('');
+        for (const signal of diagnosis.signals.slice(0, 5)) {
+            const snippet = signal.snippet ? `: ${signal.snippet}` : '';
+            lines.push(`- **${signal.source}** → ${signal.pattern}${snippet}`);
+        }
+        lines.push('');
+    }
+    // Next actions
+    if (diagnosis.next_actions.length > 0) {
+        lines.push('## Do This Next');
+        lines.push('');
+        for (let i = 0; i < Math.min(diagnosis.next_actions.length, 4); i++) {
+            const action = diagnosis.next_actions[i];
+            lines.push(`### ${i + 1}. ${action.title}`);
+            lines.push('');
+            if (action.command) {
+                lines.push('```bash');
+                lines.push(action.command);
+                lines.push('```');
+                lines.push('');
+            }
+            lines.push(`*${action.why}*`);
+            lines.push('');
+        }
+    }
+    // Escalation
+    lines.push('## If It Repeats');
+    lines.push('');
+    lines.push(getEscalationAdvice(diagnosis.primary_diagnosis));
+    lines.push('');
+    // Related artifacts
+    if (Object.keys(diagnosis.related_artifacts).length > 0) {
+        lines.push('## Related Artifacts');
+        lines.push('');
+        if (diagnosis.related_artifacts.report) {
+            lines.push(`- **Report**: \`${diagnosis.related_artifacts.report}\``);
+        }
+        if (diagnosis.related_artifacts.timeline) {
+            lines.push(`- **Timeline**: \`${diagnosis.related_artifacts.timeline}\``);
+        }
+        if (diagnosis.related_artifacts.verify_logs) {
+            lines.push(`- **Verify Logs**: \`${diagnosis.related_artifacts.verify_logs}\``);
+        }
+        if (diagnosis.related_artifacts.worker_output) {
+            lines.push(`- **Worker Output**: \`${diagnosis.related_artifacts.worker_output}\``);
+        }
+        lines.push('');
+    }
+    // Footer
+    lines.push('---');
+    lines.push(`*Diagnosed at ${diagnosis.diagnosed_at}*`);
+    return lines.join('\n');
+}
+/**
+ * Format category as human-readable title.
+ */
+function formatCategory(category) {
+    return category
+        .split('_')
+        .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+        .join(' ');
+}
+/**
+ * Get escalation advice for repeated failures.
+ */
+function getEscalationAdvice(category) {
+    switch (category) {
+        case 'auth_expired':
+            return 'Check OAuth token expiry settings. Consider re-authenticating before long runs.';
+        case 'verification_cwd_mismatch':
+            return 'Review your agent.config.json verification section. The cwd must match where package.json lives.';
+        case 'scope_violation':
+            return 'Consider if the task scope is too narrow. You may need to expand allowlist or break into smaller tasks.';
+        case 'lockfile_restricted':
+            return 'If the task genuinely needs new dependencies, use --allow-deps. Otherwise, reword the task.';
+        case 'verification_failure':
+            return 'The implementation may have fundamental issues. Review the test output carefully and consider adjusting requirements.';
+        case 'worker_parse_failure':
+            return 'This may indicate an API issue. Try with a different worker or simpler task prompts.';
+        case 'stall_timeout':
+            return 'Persistent stalls may indicate infrastructure issues. Check network, API quotas, and worker health.';
+        case 'max_ticks_reached':
+            return 'If runs consistently hit tick limits, the task may be too complex. Consider breaking into smaller milestones.';
+        case 'time_budget_exceeded':
+            return 'For complex tasks, allocate more time upfront: --time 120 or higher.';
+        case 'guard_violation_dirty':
+            return 'Always use --worktree for runs on repos with active development.';
+        default:
+            return 'Review the timeline and logs carefully. Open an issue if the problem persists.';
+    }
+}

package/dist/diagnosis/index.js

@@ -0,0 +1,6 @@
+/**
+ * Diagnosis module for auto-diagnosing run stop reasons.
+ */
+export * from './types.js';
+export * from './analyzer.js';
+export * from './formatter.js';

package/dist/diagnosis/types.js

@@ -0,0 +1,7 @@
+/**
+ * Diagnosis types for auto-diagnosing run stop reasons.
+ *
+ * The diagnosis system analyzes timeline events, state, and logs to determine
+ * why a run stopped and what action to take next.
+ */
+export {};

package/dist/env/__tests__/fingerprint.test.js

@@ -0,0 +1,116 @@
+import { describe, it, expect } from 'vitest';
+import { compareFingerprints } from '../fingerprint.js';
+function makeFingerprint(overrides = {}) {
+    return {
+        node_version: 'v20.0.0',
+        package_manager: 'npm',
+        lockfile_hash: 'abc123def456',
+        worker_versions: {
+            codex: 'codex-cli 0.70.0',
+            claude: '2.0.50 (Claude Code)'
+        },
+        created_at: '2025-01-01T00:00:00.000Z',
+        ...overrides
+    };
+}
+describe('compareFingerprints', () => {
+    it('returns empty array when fingerprints match', () => {
+        const original = makeFingerprint();
+        const current = makeFingerprint();
+        const diffs = compareFingerprints(original, current);
+        expect(diffs).toEqual([]);
+    });
+    it('detects node version change', () => {
+        const original = makeFingerprint({ node_version: 'v20.0.0' });
+        const current = makeFingerprint({ node_version: 'v22.0.0' });
+        const diffs = compareFingerprints(original, current);
+        expect(diffs).toHaveLength(1);
+        expect(diffs[0]).toEqual({
+            field: 'node_version',
+            original: 'v20.0.0',
+            current: 'v22.0.0'
+        });
+    });
+    it('detects package manager change', () => {
+        const original = makeFingerprint({ package_manager: 'npm' });
+        const current = makeFingerprint({ package_manager: 'pnpm' });
+        const diffs = compareFingerprints(original, current);
+        expect(diffs).toHaveLength(1);
+        expect(diffs[0].field).toBe('package_manager');
+    });
+    it('detects lockfile hash change', () => {
+        const original = makeFingerprint({ lockfile_hash: 'abc123' });
+        const current = makeFingerprint({ lockfile_hash: 'def456' });
+        const diffs = compareFingerprints(original, current);
+        expect(diffs).toHaveLength(1);
+        expect(diffs[0].field).toBe('lockfile_hash');
+    });
+    it('detects worker version change', () => {
+        const original = makeFingerprint({
+            worker_versions: { codex: '0.70.0', claude: '2.0.50' }
+        });
+        const current = makeFingerprint({
+            worker_versions: { codex: '0.80.0', claude: '2.0.50' }
+        });
+        const diffs = compareFingerprints(original, current);
+        expect(diffs).toHaveLength(1);
+        expect(diffs[0].field).toBe('worker:codex');
+        expect(diffs[0].original).toBe('0.70.0');
+        expect(diffs[0].current).toBe('0.80.0');
+    });
+    it('handles null lockfile gracefully', () => {
+        const original = makeFingerprint({ lockfile_hash: null });
+        const current = makeFingerprint({ lockfile_hash: 'abc123' });
+        const diffs = compareFingerprints(original, current);
+        expect(diffs).toHaveLength(1);
+        expect(diffs[0].field).toBe('lockfile_hash');
+        expect(diffs[0].original).toBeNull();
+    });
+    it('handles null package manager gracefully', () => {
+        const original = makeFingerprint({ package_manager: null });
+        const current = makeFingerprint({ package_manager: null });
+        const diffs = compareFingerprints(original, current);
+        expect(diffs).toEqual([]);
+    });
+    it('handles null worker version gracefully', () => {
+        const original = makeFingerprint({
+            worker_versions: { codex: null, claude: '2.0.50' }
+        });
+        const current = makeFingerprint({
+            worker_versions: { codex: '0.80.0', claude: '2.0.50' }
+        });
+        const diffs = compareFingerprints(original, current);
+        expect(diffs).toHaveLength(1);
+        expect(diffs[0].original).toBeNull();
+        expect(diffs[0].current).toBe('0.80.0');
+    });
+    it('detects multiple changes at once', () => {
+        const original = makeFingerprint({
+            node_version: 'v20.0.0',
+            lockfile_hash: 'old-hash',
+            worker_versions: { codex: '0.70.0', claude: '2.0.50' }
+        });
+        const current = makeFingerprint({
+            node_version: 'v22.0.0',
+            lockfile_hash: 'new-hash',
+            worker_versions: { codex: '0.80.0', claude: '2.0.50' }
+        });
+        const diffs = compareFingerprints(original, current);
+        expect(diffs).toHaveLength(3);
+        expect(diffs.map((d) => d.field).sort()).toEqual([
+            'lockfile_hash',
+            'node_version',
+            'worker:codex'
+        ]);
+    });
+    it('ignores created_at timestamp differences', () => {
+        const original = makeFingerprint({
+            created_at: '2025-01-01T00:00:00.000Z'
+        });
+        const current = makeFingerprint({
+            created_at: '2025-06-15T12:30:00.000Z'
+        });
+        const diffs = compareFingerprints(original, current);
+        expect(diffs).toEqual([]);
+    });
+});

package/dist/env/fingerprint.js

@@ -0,0 +1,111 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { execa } from 'execa';
+async function getNodeVersion() {
+    return process.version;
+}
+async function detectPackageManager(repoPath) {
+    const lockFiles = [
+        { file: 'pnpm-lock.yaml', pm: 'pnpm' },
+        { file: 'yarn.lock', pm: 'yarn' },
+        { file: 'package-lock.json', pm: 'npm' },
+        { file: 'bun.lockb', pm: 'bun' }
+    ];
+    for (const { file, pm } of lockFiles) {
+        if (fs.existsSync(path.join(repoPath, file))) {
+            return pm;
+        }
+    }
+    return null;
+}
+async function getLockfileHash(repoPath) {
+    const lockFiles = [
+        'pnpm-lock.yaml',
+        'yarn.lock',
+        'package-lock.json',
+        'bun.lockb'
+    ];
+    for (const file of lockFiles) {
+        const lockPath = path.join(repoPath, file);
+        if (fs.existsSync(lockPath)) {
+            const content = fs.readFileSync(lockPath);
+            const hash = crypto.createHash('sha256').update(content).digest('hex');
+            return hash.slice(0, 16);
+        }
+    }
+    return null;
+}
+async function getWorkerVersion(bin) {
+    try {
+        const result = await execa(bin, ['--version'], {
+            timeout: 5000,
+            reject: false
+        });
+        if (result.exitCode === 0) {
+            return result.stdout.trim().split('\n')[0];
+        }
+    }
+    catch {
+        // Worker not found
+    }
+    return null;
+}
+async function getWorkerVersions(config) {
+    const versions = {};
+    for (const [name, workerConfig] of Object.entries(config.workers)) {
+        versions[name] = await getWorkerVersion(workerConfig.bin);
+    }
+    return versions;
+}
+export async function captureFingerprint(config, repoPath) {
+    const [nodeVersion, packageManager, lockfileHash, workerVersions] = await Promise.all([
+        getNodeVersion(),
+        detectPackageManager(repoPath),
+        getLockfileHash(repoPath),
+        getWorkerVersions(config)
+    ]);
+    return {
+        node_version: nodeVersion,
+        package_manager: packageManager,
+        lockfile_hash: lockfileHash,
+        worker_versions: workerVersions,
+        created_at: new Date().toISOString()
+    };
+}
+export function compareFingerprints(original, current) {
+    const diffs = [];
+    if (original.node_version !== current.node_version) {
+        diffs.push({
+            field: 'node_version',
+            original: original.node_version,
+            current: current.node_version
+        });
+    }
+    if (original.package_manager !== current.package_manager) {
+        diffs.push({
+            field: 'package_manager',
+            original: original.package_manager,
+            current: current.package_manager
+        });
+    }
+    if (original.lockfile_hash !== current.lockfile_hash) {
+        diffs.push({
+            field: 'lockfile_hash',
+            original: original.lockfile_hash,
+            current: current.lockfile_hash
+        });
+    }
+    for (const workerName of Object.keys(original.worker_versions)) {
+        const origVersion = original.worker_versions[workerName];
+        const currVersion = current.worker_versions[workerName];
+        if (origVersion !== currVersion) {
+            diffs.push({
+                field: `worker:${workerName}`,
+                original: origVersion,
+                current: currVersion
+            });
+        }
+    }
+    return diffs;
+}

package/dist/orchestrator/__tests__/policy.test.js

@@ -0,0 +1,185 @@
+/**
+ * Policy block tests for Phase 7B.
+ *
+ * These tests verify:
+ * 1. Run creates state.policy correctly from CLI/config
+ * 2. Resume without overrides keeps policy unchanged (via getEffectivePolicy)
+ * 3. Legacy states (without policy block) are handled correctly
+ */
+import { describe, it, expect } from 'vitest';
+import { createInitialOrchestratorState, getEffectivePolicy } from '../state-machine.js';
+// Sample config for testing
+const sampleConfig = {
+    tracks: [
+        {
+            name: 'Track A',
+            steps: [{ task: 'tasks/a.md' }]
+        },
+        {
+            name: 'Track B',
+            steps: [{ task: 'tasks/b.md' }]
+        }
+    ]
+};
+describe('Policy Block', () => {
+    describe('createInitialOrchestratorState', () => {
+        it('creates state.policy correctly from CLI options', () => {
+            const state = createInitialOrchestratorState(sampleConfig, '/test/repo', {
+                timeBudgetMinutes: 60,
+                maxTicks: 25,
+                collisionPolicy: 'serialize',
+                fast: true,
+                autoResume: true,
+                parallel: 1,
+                ownershipRequired: true
+            });
+            // Policy block should exist
+            expect(state.policy).toBeDefined();
+            // Policy values should match options
+            expect(state.policy.time_budget_minutes).toBe(60);
+            expect(state.policy.max_ticks).toBe(25);
+            expect(state.policy.collision_policy).toBe('serialize');
+            expect(state.policy.fast).toBe(true);
+            expect(state.policy.auto_resume).toBe(true);
+            expect(state.policy.parallel).toBe(1);
+            expect(state.policy.ownership_required).toBe(true);
+        });
+        it('sets default values for optional policy fields', () => {
+            const state = createInitialOrchestratorState(sampleConfig, '/test/repo', {
+                timeBudgetMinutes: 120,
+                maxTicks: 50,
+                collisionPolicy: 'force'
+                // fast, autoResume, parallel not provided
+            });
+            expect(state.policy).toBeDefined();
+            expect(state.policy.fast).toBe(false);
+            expect(state.policy.auto_resume).toBe(false);
+            expect(state.policy.parallel).toBe(2); // Default: track count
+            expect(state.policy.ownership_required).toBe(false);
+        });
+        it('writes both policy block and legacy fields for backward compatibility', () => {
+            const state = createInitialOrchestratorState(sampleConfig, '/test/repo', {
+                timeBudgetMinutes: 90,
+                maxTicks: 30,
+                collisionPolicy: 'fail',
+                fast: true
+            });
+            // Policy block
+            expect(state.policy.time_budget_minutes).toBe(90);
+            expect(state.policy.max_ticks).toBe(30);
+            expect(state.policy.collision_policy).toBe('fail');
+            expect(state.policy.fast).toBe(true);
+            // Legacy fields (should match)
+            expect(state.time_budget_minutes).toBe(90);
+            expect(state.max_ticks).toBe(30);
+            expect(state.collision_policy).toBe('fail');
+            expect(state.fast).toBe(true);
+        });
+    });
+    describe('getEffectivePolicy', () => {
+        it('returns policy block when present', () => {
+            const state = createInitialOrchestratorState(sampleConfig, '/test/repo', {
+                timeBudgetMinutes: 45,
+                maxTicks: 15,
+                collisionPolicy: 'serialize',
+                fast: true,
+                autoResume: true
+            });
+            const policy = getEffectivePolicy(state);
+            expect(policy.time_budget_minutes).toBe(45);
+            expect(policy.max_ticks).toBe(15);
+            expect(policy.collision_policy).toBe('serialize');
+            expect(policy.fast).toBe(true);
+            expect(policy.auto_resume).toBe(true);
+        });
+        it('falls back to legacy fields when policy block is missing (v0 state)', () => {
+            // Simulate a legacy v0 state without policy block
+            const legacyState = {
+                orchestrator_id: 'orch20240101120000',
+                repo_path: '/test/repo',
+                tracks: [
+                    {
+                        id: 'track-1',
+                        name: 'Track A',
+                        steps: [{ task_path: 'tasks/a.md' }],
+                        current_step: 0,
+                        status: 'pending'
+                    }
+                ],
+                active_runs: {},
+                file_claims: {},
+                status: 'running',
+                started_at: '2024-01-01T12:00:00Z',
+                // No policy block - legacy v0 state
+                collision_policy: 'force',
+                time_budget_minutes: 180,
+                max_ticks: 100,
+                fast: true
+            };
+            const policy = getEffectivePolicy(legacyState);
+            // Should extract from legacy fields
+            expect(policy.time_budget_minutes).toBe(180);
+            expect(policy.max_ticks).toBe(100);
+            expect(policy.collision_policy).toBe('force');
+            expect(policy.fast).toBe(true);
+            // Defaults for fields not in v0
+            expect(policy.auto_resume).toBe(false);
+            expect(policy.parallel).toBe(1); // track count
+        });
+        it('handles legacy state with fast=undefined', () => {
+            const legacyState = {
+                orchestrator_id: 'orch20240101120000',
+                repo_path: '/test/repo',
+                tracks: [],
+                active_runs: {},
+                file_claims: {},
+                status: 'running',
+                started_at: '2024-01-01T12:00:00Z',
+                collision_policy: 'serialize',
+                time_budget_minutes: 60,
+                max_ticks: 25
+                // fast is undefined (missing in v0)
+            };
+            const policy = getEffectivePolicy(legacyState);
+            expect(policy.fast).toBe(false); // Default when undefined
+        });
+    });
+    describe('Resume policy immutability', () => {
+        it('resume without overrides keeps policy unchanged', () => {
+            // Create initial state
+            const state = createInitialOrchestratorState(sampleConfig, '/test/repo', {
+                timeBudgetMinutes: 60,
+                maxTicks: 25,
+                collisionPolicy: 'serialize',
+                fast: true
+            });
+            // Simulate "resuming" by getting effective policy
+            const policyBeforeResume = getEffectivePolicy(state);
+            const policyAfterResume = getEffectivePolicy(state);
+            // Policy should be identical
+            expect(policyAfterResume).toEqual(policyBeforeResume);
+        });
+        it('policy values remain stable across multiple reads', () => {
+            const state = createInitialOrchestratorState(sampleConfig, '/test/repo', {
+                timeBudgetMinutes: 42,
+                maxTicks: 17,
+                collisionPolicy: 'force',
+                fast: false,
+                autoResume: true
+            });
+            // Read policy multiple times
+            const policy1 = getEffectivePolicy(state);
+            const policy2 = getEffectivePolicy(state);
+            const policy3 = getEffectivePolicy(state);
+            // All reads should return identical values
+            expect(policy1).toEqual(policy2);
+            expect(policy2).toEqual(policy3);
+            // And match original options
+            expect(policy1.time_budget_minutes).toBe(42);
+            expect(policy1.max_ticks).toBe(17);
+            expect(policy1.collision_policy).toBe('force');
+            expect(policy1.fast).toBe(false);
+            expect(policy1.auto_resume).toBe(true);
+        });
+    });
+});

package/dist/orchestrator/__tests__/schema-version.test.js

@@ -0,0 +1,65 @@
+/**
+ * Schema version tests for Phase 7C.
+ *
+ * These tests verify:
+ * 1. Artifacts include schema_version field
+ * 2. Schema version is the expected value
+ */
+import { describe, it, expect } from 'vitest';
+import { buildWaitResult, buildSummaryArtifact, buildStopArtifact } from '../artifacts.js';
+import { createInitialOrchestratorState } from '../state-machine.js';
+import { ORCHESTRATOR_ARTIFACT_SCHEMA_VERSION } from '../types.js';
+const sampleConfig = {
+    tracks: [
+        {
+            name: 'Test Track',
+            steps: [{ task: 'tasks/test.md' }]
+        }
+    ]
+};
+describe('Schema Versioning', () => {
+    describe('Orchestration Artifacts', () => {
+        it('buildWaitResult includes schema_version', () => {
+            const state = createInitialOrchestratorState(sampleConfig, '/test/repo', {
+                timeBudgetMinutes: 60,
+                maxTicks: 25,
+                collisionPolicy: 'serialize'
+            });
+            // Mark as complete for testing
+            state.status = 'complete';
+            state.ended_at = new Date().toISOString();
+            const result = buildWaitResult(state, '/test/repo');
+            expect(result.schema_version).toBe(ORCHESTRATOR_ARTIFACT_SCHEMA_VERSION);
+            expect(result.schema_version).toBe(1);
+        });
+        it('buildSummaryArtifact includes schema_version', () => {
+            const state = createInitialOrchestratorState(sampleConfig, '/test/repo', {
+                timeBudgetMinutes: 60,
+                maxTicks: 25,
+                collisionPolicy: 'serialize'
+            });
+            state.status = 'complete';
+            state.ended_at = new Date().toISOString();
+            const summary = buildSummaryArtifact(state, '/test/repo');
+            expect(summary.schema_version).toBe(ORCHESTRATOR_ARTIFACT_SCHEMA_VERSION);
+            expect(summary.schema_version).toBe(1);
+        });
+        it('buildStopArtifact includes schema_version', () => {
+            const state = createInitialOrchestratorState(sampleConfig, '/test/repo', {
+                timeBudgetMinutes: 60,
+                maxTicks: 25,
+                collisionPolicy: 'serialize'
+            });
+            state.status = 'stopped';
+            state.ended_at = new Date().toISOString();
+            const stopArtifact = buildStopArtifact(state, '/test/repo');
+            expect(stopArtifact.schema_version).toBe(ORCHESTRATOR_ARTIFACT_SCHEMA_VERSION);
+            expect(stopArtifact.schema_version).toBe(1);
+        });
+    });
+    describe('Schema version constant', () => {
+        it('ORCHESTRATOR_ARTIFACT_SCHEMA_VERSION is 1', () => {
+            expect(ORCHESTRATOR_ARTIFACT_SCHEMA_VERSION).toBe(1);
+        });
+    });
+});