@weldr/runr 0.3.0 → 0.3.1

package/README.md

@@ -1,57 +1,122 @@
 # Runr
 
-Phase-gated orchestration for agent tasks.
+**Stop losing 30 minutes when the agent derails.**
 
-> **Status**: v0.3.0 — Renamed from `agent-runner`. Early, opinionated, evolving.
+![Failure Recovery](demo/failure-checkpoint.gif)
+
+*When verification fails after 3 checkpoints, progress isn't lost — Runr saves verified work as git commits.*
+
+## Quickstart
+
+```bash
+npm install -g @weldr/runr
+cd your-repo
+runr init
+runr run --task .runr/tasks/your-task.md --worktree
+```
 
-## The Problem
+**If it stops:** Run the suggested command in `.runr/runs/<run_id>/handoffs/stop.json`
 
-AI agents can write code. They can also:
-- Claim success without verification
-- Modify files they shouldn't touch
-- Get stuck in infinite loops
-- Fail in ways that are impossible to debug
+![Next Action](demo/next-action.gif)
 
-**Runr doesn't make agents smarter. It makes them accountable.**
+*Runr writes a stop handoff so agents know exactly what to do next — no guessing, no hallucinating.*
 
-## What This Does
+## How It Works
 
-Runr orchestrates AI workers (Claude, Codex) through a phase-based workflow with hard gates:
+Runr orchestrates AI workers through phase gates with checkpoints:
 
 ```
 PLAN → IMPLEMENT → VERIFY → REVIEW → CHECKPOINT → done
-         ↑___________|  (retry if needed)
+         ↑___________|  (retry if verification fails)
 ```
 
-Every phase has criteria. You don't advance without meeting them.
+- **Phase gates** — Agent can't skip verification or claim false success
+- **Checkpoints** — Verified milestones saved as git commits
+- **Stop handoffs** — Structured diagnostics with next actions
+- **Scope guards** — Files outside scope are protected
 
-## Why Phase Gates?
+> **Status**: v0.3.0 — Renamed from `agent-runner`. Early, opinionated, evolving.
+
+## Meta-Agent Quickstart (Recommended)
 
-Most agent tools optimize for speed. Runr optimizes for **trust**.
+**The easiest way to use Runr:** Let your coding agent drive it.
 
-When a run fails (and it will), you get:
-- **Structured diagnostics** — exactly why it stopped
-- **Checkpoints** — resume from where it failed
-- **Scope guards** — files it couldn't touch, it didn't touch
-- **Evidence** — "done" means "proven done"
+Runr works as a **reliable execution backend**. Instead of learning CLI commands, your agent (Claude Code, Codex, etc.) operates Runr for you — handling runs, interpreting failures, and resuming from checkpoints.
 
-## Quick Start
+### Setup (One-Time)
 
 ```bash
-# Install
-git clone https://github.com/vonwao/runr.git
-cd runr && npm install && npm run build && npm link
+# 1. Install Runr
+npm install -g @weldr/runr
 
-# Verify
-runr version
+# 2. Verify environment
 runr doctor
 
-# Run a task
+# 3. Create minimal config
+mkdir -p .runr/tasks
+cat > .runr/runr.config.json << 'EOF'
+{
+  "agent": { "name": "my-project", "version": "1" },
+  "scope": {
+    "presets": ["typescript", "vitest"]
+  },
+  "verification": {
+    "tier0": ["npm run typecheck"],
+    "tier1": ["npm test"]
+  }
+}
+EOF
+```
+
+### Usage
+
+Just tell your coding agent:
+
+> "Use Runr to add user authentication with OAuth2. Create checkpoints after each milestone."
+
+The agent will:
+1. Create a task file (`.runr/tasks/add-auth.md`)
+2. Run `runr run --task ... --worktree`
+3. Monitor progress with `runr status`
+4. Handle failures, resume from checkpoints
+5. Report results with commit links
+
+**See [RUNR_OPERATOR.md](./RUNR_OPERATOR.md)** for the complete agent integration guide.
+
+### Why This Works
+
+Most devs already have a coding agent open. Telling them:
+- "Drop this in your agent, and it'll drive Runr for you"
+
+…has near-zero friction compared to:
+- "Learn these CLI commands, create config files, understand phase gates"
+
+The agent becomes your operator. Runr stays the reliable execution layer.
+
+---
+
+## Quick Start (Direct CLI)
+
+```bash
+# Install
+npm install -g @weldr/runr
+
+# Initialize in your project
 cd /your/project
-runr run --task .runr/tasks/my-task.md --worktree
+runr init
+
+# Run a task
+runr run --task .runr/tasks/example-feature.md --worktree
+
+# If it fails, resume from last checkpoint
+runr resume <run_id>
+
+# Get machine-readable diagnostics
+runr summarize <run_id>
+# Output: .runr/runs/<run_id>/handoffs/stop.json
 ```
 
-> Not on npm yet. Coming soon as `@weldr/runr`.
+> Prefer source install? See [Development](#development).
 
 ## Configuration
 
@@ -91,15 +156,17 @@ Available: `nextjs`, `react`, `drizzle`, `prisma`, `vitest`, `jest`, `playwright
 
 | Command | What it does |
 |---------|--------------|
+| `runr init` | Initialize config (auto-detect verify commands) |
 | `runr run --task <file>` | Start a task |
 | `runr resume <id>` | Continue from checkpoint |
+| `runr watch <id> --auto-resume` | Watch run + auto-resume on failure |
 | `runr status [id]` | Show run state |
 | `runr follow [id]` | Tail run progress |
-| `runr report <id>` | Generate run report |
+| `runr report <id>` | Generate run report (includes next_action) |
 | `runr gc` | Clean up old runs |
 | `runr doctor` | Check environment |
 
-### The Fun Commands
+### Aliases
 
 Same functionality, different vibe:
 
@@ -146,26 +213,23 @@ Every stop produces `stop.json` + `stop.md` with diagnostics.
 
 ## Philosophy
 
-**This is not magic.** Runs fail. The goal is *understandable, resumable* failure.
+This isn't magic. Runs fail. The goal is understandable, resumable failure.
 
-**This is not a chatbot.** Task in, code out. No conversation.
+This isn't a chatbot. Task in, code out.
 
-**This is not a code generator.** It orchestrates generators. Different job.
+This isn't a code generator. It orchestrates generators.
 
-**Agents lie. Logs don't.** If it can't prove it, it didn't do it.
+Agents lie. Logs don't. If it can't prove it, it didn't do it.
 
 ## Migrating from agent-runner
 
-If you're upgrading from `agent-runner`:
-
 | Old | New |
 |-----|-----|
 | `agent` CLI | `runr` CLI |
 | `.agent/` directory | `.runr/` directory |
 | `agent.config.json` | `runr.config.json` |
 | `.agent-worktrees/` | `.runr-worktrees/` |
-
-Both old and new locations work during the transition period. You'll see deprecation warnings for old locations.
+Old paths still work for now, with deprecation warnings.
 
 ## Development
 
@@ -179,21 +243,21 @@ npm run dev -- run --task task.md  # run from source
 
 | Version | Date | Highlights |
 |---------|------|------------|
-| v0.3.0 | 2026-01-01 | **Renamed to Runr**, new CLI, new directory structure |
-| v0.2.2 | 2025-12-31 | Worktree location fix, guard diagnostics |
-| v0.2.1 | 2025-12-29 | Scope presets, review digest |
-| v0.2.0 | 2025-12-28 | Review loop detection |
-| v0.1.0 | 2025-12-27 | Initial stable release |
+| v0.3.0 | **Renamed to Runr**, new CLI, new directory structure |
+| v0.2.2 | Worktree location fix, guard diagnostics |
+| v0.2.1 | Scope presets, review digest |
+| v0.2.0 | Review loop detection |
+| v0.1.0 | Initial stable release |
 
-See [CHANGELOG.md](CHANGELOG.md) for detailed release notes.
+See [CHANGELOG.md](CHANGELOG.md) for details.
 
 ## Contributing
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.
+See [CONTRIBUTING.md](CONTRIBUTING.md).
 
 ## License
 
-Apache 2.0 — See [LICENSE](LICENSE)
+Apache 2.0 — See [LICENSE](LICENSE).
 
 ---
 

package/dist/cli.js

@@ -5,6 +5,7 @@ import { resumeCommand } from './commands/resume.js';
 import { statusCommand, statusAllCommand } from './commands/status.js';
 import { reportCommand, findLatestRunId } from './commands/report.js';
 import { summarizeCommand } from './commands/summarize.js';
+import { nextCommand } from './commands/next.js';
 import { compareCommand } from './commands/compare.js';
 import { guardsOnlyCommand } from './commands/guards-only.js';
 import { doctorCommand } from './commands/doctor.js';
@@ -15,6 +16,8 @@ import { orchestrateCommand, resumeOrchestrationCommand, waitOrchestrationComman
 import { pathsCommand } from './commands/paths.js';
 import { metricsCommand } from './commands/metrics.js';
 import { versionCommand } from './commands/version.js';
+import { initCommand } from './commands/init.js';
+import { watchCommand } from './commands/watch.js';
 const program = new Command();
 // Check if invoked as deprecated 'agent' command
 const invokedAs = process.argv[1]?.split('/').pop() || 'runr';
@@ -24,6 +27,21 @@ if (invokedAs === 'agent') {
 program
     .name('runr')
     .description('Phase-gated orchestration for agent tasks');
+program
+    .command('init')
+    .description('Initialize Runr configuration for a repository')
+    .option('--repo <path>', 'Path to repository (defaults to current directory)', '.')
+    .option('--interactive', 'Launch interactive setup wizard to configure verification commands', false)
+    .option('--print', 'Display generated config in terminal without writing to disk', false)
+    .option('--force', 'Overwrite existing .runr/runr.config.json if present', false)
+    .action(async (options) => {
+    await initCommand({
+        repo: options.repo,
+        interactive: options.interactive,
+        print: options.print,
+        force: options.force
+    });
+});
 program
     .command('run')
     .option('--repo <path>', 'Target repo path (default: current directory)', '.')
@@ -132,6 +150,7 @@ program
     .option('--repo <path>', 'Target repo path (default: current directory)', '.')
     .option('--tail <count>', 'Tail last N events', '50')
     .option('--kpi-only', 'Show compact KPI summary only')
+    .option('--json', 'Output KPI as JSON (includes next_action and suggested_command)')
     .action(async (runId, options) => {
     let resolvedRunId = runId;
     if (runId === 'latest') {
@@ -146,7 +165,8 @@ program
         runId: resolvedRunId,
         repo: options.repo,
         tail: Number.parseInt(options.tail, 10),
-        kpiOnly: options.kpiOnly
+        kpiOnly: options.kpiOnly,
+        json: options.json
     });
 });
 program
@@ -166,6 +186,23 @@ program
     }
     await summarizeCommand({ runId: resolvedRunId, repo: options.repo });
 });
+program
+    .command('next')
+    .description('Print suggested next command from stop handoff')
+    .argument('<runId>', 'Run ID (or "latest")')
+    .option('--repo <path>', 'Target repo path (default: current directory)', '.')
+    .action(async (runId, options) => {
+    let resolvedRunId = runId;
+    if (runId === 'latest') {
+        const latest = findLatestRunId(options.repo);
+        if (!latest) {
+            console.error('No runs found');
+            process.exit(1);
+        }
+        resolvedRunId = latest;
+    }
+    await nextCommand(resolvedRunId, { repo: options.repo });
+});
 program
     .command('compare')
     .description('Compare KPIs between two runs')
@@ -258,6 +295,25 @@ program
         olderThan: Number.parseInt(options.olderThan, 10)
     });
 });
+program
+    .command('watch')
+    .description('Watch run progress and optionally auto-resume on failure')
+    .argument('<runId>', 'Run ID to watch')
+    .option('--repo <path>', 'Target repo path (default: current directory)', '.')
+    .option('--auto-resume', 'Automatically resume on transient failures', false)
+    .option('--max-attempts <N>', 'Maximum auto-resume attempts (default: 3)', '3')
+    .option('--interval <seconds>', 'Poll interval in seconds (default: 5)', '5')
+    .option('--json', 'Output JSON events', false)
+    .action(async (runId, options) => {
+    await watchCommand({
+        runId,
+        repo: options.repo,
+        autoResume: options.autoResume,
+        maxAttempts: Number.parseInt(options.maxAttempts, 10),
+        interval: Number.parseInt(options.interval, 10) * 1000,
+        json: options.json
+    });
+});
 program
     .command('wait')
     .description('Block until run reaches terminal state (for meta-agent coordination)')

package/dist/commands/init.js

@@ -0,0 +1,440 @@
+import fs from 'node:fs';
+import path from 'node:path';
+/**
+ * Detect Python project verification commands
+ */
+function detectPythonVerification(repoPath) {
+    const hasPyprojectToml = fs.existsSync(path.join(repoPath, 'pyproject.toml'));
+    const hasPytestIni = fs.existsSync(path.join(repoPath, 'pytest.ini'));
+    const hasPoetryLock = fs.existsSync(path.join(repoPath, 'poetry.lock'));
+    // If no Python markers, return null
+    if (!hasPyprojectToml && !hasPytestIni && !hasPoetryLock) {
+        return null;
+    }
+    const verification = {
+        tier0: [],
+        tier1: [],
+        tier2: []
+    };
+    const presets = [];
+    // Parse pyproject.toml if it exists
+    let pyprojectContent = null;
+    if (hasPyprojectToml) {
+        try {
+            const pyprojectPath = path.join(repoPath, 'pyproject.toml');
+            const content = fs.readFileSync(pyprojectPath, 'utf-8');
+            // Simple TOML parsing for common sections
+            // Look for [tool.poetry], [tool.pytest], etc.
+            if (content.includes('[tool.poetry]') || hasPoetryLock) {
+                presets.push('poetry');
+                // Tier 1: Poetry install/check
+                verification.tier1.push('poetry check');
+            }
+            if (content.includes('[tool.pytest]') || hasPytestIni) {
+                presets.push('pytest');
+                // Tier 2: Run tests
+                verification.tier2.push('pytest');
+            }
+            // Check for mypy, black, ruff, etc.
+            if (content.includes('[tool.mypy]') || content.includes('mypy')) {
+                verification.tier0.push('mypy .');
+            }
+            if (content.includes('[tool.black]') || content.includes('black')) {
+                verification.tier0.push('black --check .');
+            }
+            if (content.includes('[tool.ruff]') || content.includes('ruff')) {
+                verification.tier0.push('ruff check .');
+            }
+        }
+        catch {
+            // If parsing fails, continue with basic detection
+        }
+    }
+    // If pytest.ini exists but not already detected
+    if (hasPytestIni && !verification.tier2.includes('pytest')) {
+        presets.push('pytest');
+        verification.tier2.push('pytest');
+    }
+    // If nothing was detected, return null
+    if (verification.tier0.length === 0 && verification.tier1.length === 0 && verification.tier2.length === 0) {
+        return null;
+    }
+    return {
+        verification,
+        presets,
+        source: 'python'
+    };
+}
+/**
+ * Detect verification commands from package.json scripts
+ */
+function detectFromPackageJson(repoPath) {
+    const packageJsonPath = path.join(repoPath, 'package.json');
+    if (!fs.existsSync(packageJsonPath)) {
+        return null;
+    }
+    try {
+        const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
+        const scripts = packageJson.scripts || {};
+        const verification = {
+            tier0: [],
+            tier1: [],
+            tier2: []
+        };
+        const presets = [];
+        // Tier 0: fast checks (lint, typecheck)
+        if (scripts.typecheck) {
+            verification.tier0.push('npm run typecheck');
+        }
+        else if (scripts.tsc || scripts['type-check']) {
+            verification.tier0.push(`npm run ${scripts.tsc ? 'tsc' : 'type-check'}`);
+        }
+        if (scripts.lint) {
+            verification.tier0.push('npm run lint');
+        }
+        else if (scripts.eslint) {
+            verification.tier0.push('npm run eslint');
+        }
+        // Tier 1: build (slower, but catches integration issues)
+        if (scripts.build) {
+            verification.tier1.push('npm run build');
+        }
+        else if (scripts.compile) {
+            verification.tier1.push('npm run compile');
+        }
+        // Tier 2: tests (slowest, most comprehensive)
+        if (scripts.test) {
+            verification.tier2.push('npm run test');
+        }
+        else if (scripts.jest || scripts.vitest) {
+            verification.tier2.push(`npm run ${scripts.jest ? 'jest' : 'vitest'}`);
+        }
+        // Detect presets from dependencies
+        const allDeps = {
+            ...packageJson.dependencies,
+            ...packageJson.devDependencies
+        };
+        if (allDeps.typescript)
+            presets.push('typescript');
+        if (allDeps.vitest)
+            presets.push('vitest');
+        if (allDeps.jest)
+            presets.push('jest');
+        if (allDeps.next)
+            presets.push('nextjs');
+        if (allDeps.react && !allDeps.next)
+            presets.push('react');
+        if (allDeps.drizzle)
+            presets.push('drizzle');
+        if (allDeps.prisma || allDeps['@prisma/client'])
+            presets.push('prisma');
+        if (allDeps.playwright || allDeps['@playwright/test'])
+            presets.push('playwright');
+        if (allDeps.tailwindcss)
+            presets.push('tailwind');
+        if (allDeps.eslint)
+            presets.push('eslint');
+        // If nothing detected, return null
+        if (verification.tier0.length === 0 && verification.tier1.length === 0 && verification.tier2.length === 0) {
+            return null;
+        }
+        return {
+            verification,
+            presets,
+            source: 'package.json'
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Generate default config when auto-detection fails
+ */
+function generateDefaultConfig(repoPath) {
+    const hasSrc = fs.existsSync(path.join(repoPath, 'src'));
+    const hasTests = fs.existsSync(path.join(repoPath, 'tests')) ||
+        fs.existsSync(path.join(repoPath, 'test'));
+    const presets = [];
+    // Check for common config files
+    if (fs.existsSync(path.join(repoPath, 'tsconfig.json'))) {
+        presets.push('typescript');
+    }
+    // Determine why we couldn't detect verification
+    let reason = 'no-package-json';
+    const packageJsonPath = path.join(repoPath, 'package.json');
+    if (fs.existsSync(packageJsonPath)) {
+        try {
+            const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
+            if (packageJson.scripts && Object.keys(packageJson.scripts).length > 0) {
+                reason = 'no-matching-scripts';
+            }
+            else {
+                reason = 'empty-scripts';
+            }
+        }
+        catch {
+            reason = 'invalid-package-json';
+        }
+    }
+    return {
+        verification: {
+            tier0: [],
+            tier1: [],
+            tier2: []
+        },
+        presets,
+        source: 'none',
+        reason
+    };
+}
+/**
+ * Build config object from detection results
+ */
+function buildConfig(repoPath, detection) {
+    const hasSrc = fs.existsSync(path.join(repoPath, 'src'));
+    const hasTests = fs.existsSync(path.join(repoPath, 'tests')) ||
+        fs.existsSync(path.join(repoPath, 'test'));
+    // Build allowlist based on directory structure
+    const allowlist = [];
+    if (hasSrc)
+        allowlist.push('src/**');
+    if (hasTests) {
+        allowlist.push('tests/**');
+        allowlist.push('test/**');
+    }
+    if (allowlist.length === 0) {
+        // Default: allow everything except common excludes
+        allowlist.push('**/*.ts', '**/*.tsx', '**/*.js', '**/*.jsx');
+    }
+    return {
+        agent: {
+            name: path.basename(repoPath),
+            version: '1'
+        },
+        scope: {
+            allowlist,
+            denylist: ['node_modules/**', '.env'],
+            lockfiles: ['package-lock.json', 'pnpm-lock.yaml', 'yarn.lock'],
+            presets: detection.presets,
+            env_allowlist: [
+                'node_modules',
+                'node_modules/**',
+                '.next/**',
+                'dist/**',
+                'build/**',
+                '.turbo/**',
+                '.eslintcache',
+                'coverage/**'
+            ]
+        },
+        verification: {
+            tier0: detection.verification.tier0,
+            tier1: detection.verification.tier1,
+            tier2: detection.verification.tier2,
+            risk_triggers: [],
+            max_verify_time_per_milestone: 600
+        },
+        repo: {},
+        workers: {
+            codex: {
+                bin: 'codex',
+                args: ['exec', '--full-auto', '--json'],
+                output: 'jsonl'
+            },
+            claude: {
+                bin: 'claude',
+                args: ['-p', '--output-format', 'json', '--dangerously-skip-permissions'],
+                output: 'json'
+            }
+        },
+        phases: {
+            plan: 'claude',
+            implement: 'codex',
+            review: 'claude'
+        },
+        resilience: {
+            auto_resume: false,
+            max_auto_resumes: 1,
+            auto_resume_delays_ms: [30000, 120000, 300000],
+            max_worker_call_minutes: 45,
+            max_review_rounds: 2
+        }
+    };
+}
+/**
+ * Create example task files
+ */
+function createExampleTasks(runrDir) {
+    const tasksDir = path.join(runrDir, 'tasks');
+    fs.mkdirSync(tasksDir, { recursive: true });
+    const exampleBugfix = `# Fix Bug: [Description]
+
+## Goal
+Fix [specific bug] in [component/module]
+
+## Requirements
+- Identify root cause
+- Implement fix
+- Add test to prevent regression
+
+## Success Criteria
+- Bug is fixed (verified manually or with specific test)
+- All existing tests still pass
+- New test added covering the bug scenario
+`;
+    const exampleFeature = `# Add Feature: [Description]
+
+## Goal
+Implement [feature] that allows users to [action]
+
+## Requirements
+- [Requirement 1]
+- [Requirement 2]
+- [Requirement 3]
+
+## Success Criteria
+- Feature works as described
+- Tests added covering main use cases
+- All verification checks pass (lint, typecheck, build, tests)
+`;
+    const exampleDocs = `# Update Documentation
+
+## Goal
+Update documentation for [topic/module]
+
+## Requirements
+- Document new features/changes
+- Update code examples if needed
+- Fix any outdated information
+
+## Success Criteria
+- Documentation is accurate and clear
+- Examples run without errors
+- All verification checks pass
+`;
+    fs.writeFileSync(path.join(tasksDir, 'example-bugfix.md'), exampleBugfix);
+    fs.writeFileSync(path.join(tasksDir, 'example-feature.md'), exampleFeature);
+    fs.writeFileSync(path.join(tasksDir, 'example-docs.md'), exampleDocs);
+}
+/**
+ * Initialize Runr configuration for a repository
+ */
+export async function initCommand(options) {
+    const repoPath = path.resolve(options.repo);
+    const runrDir = path.join(repoPath, '.runr');
+    const configPath = path.join(runrDir, 'runr.config.json');
+    // Handle --interactive flag
+    if (options.interactive) {
+        console.log('🚧 Interactive setup is planned for a future release');
+        console.log('');
+        console.log('For now, use `runr init` without --interactive to generate config automatically,');
+        console.log('then edit .runr/runr.config.json to customize verification commands.');
+        process.exit(0);
+    }
+    // Check if config already exists
+    if (fs.existsSync(configPath) && !options.force) {
+        console.error('Error: .runr/runr.config.json already exists');
+        console.error('Use --force to overwrite');
+        process.exit(1);
+    }
+    // Detect verification commands - try Python first, then package.json, then default
+    const detection = detectPythonVerification(repoPath) ||
+        detectFromPackageJson(repoPath) ||
+        generateDefaultConfig(repoPath);
+    // Build config
+    const config = buildConfig(repoPath, detection);
+    // If --print mode, just output and exit
+    if (options.print) {
+        console.log(JSON.stringify(config, null, 2));
+        return;
+    }
+    // Create .runr directory
+    fs.mkdirSync(runrDir, { recursive: true });
+    // Write config
+    fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n');
+    // Create example tasks
+    createExampleTasks(runrDir);
+    // Report results
+    console.log('✅ Runr initialized successfully!\n');
+    console.log(`Config written to: ${configPath}`);
+    console.log(`Example tasks created in: ${path.join(runrDir, 'tasks')}/\n`);
+    if (detection.source === 'package.json') {
+        console.log('Detected from package.json:');
+        if (detection.verification.tier0.length > 0) {
+            console.log(`  tier0 (fast): ${detection.verification.tier0.join(', ')}`);
+        }
+        if (detection.verification.tier1.length > 0) {
+            console.log(`  tier1 (build): ${detection.verification.tier1.join(', ')}`);
+        }
+        if (detection.verification.tier2.length > 0) {
+            console.log(`  tier2 (tests): ${detection.verification.tier2.join(', ')}`);
+        }
+        if (detection.presets.length > 0) {
+            console.log(`  presets: ${detection.presets.join(', ')}`);
+        }
+        console.log('');
+    }
+    else if (detection.source === 'python') {
+        console.log('Detected Python project:');
+        if (detection.verification.tier0.length > 0) {
+            console.log(`  tier0 (fast): ${detection.verification.tier0.join(', ')}`);
+        }
+        if (detection.verification.tier1.length > 0) {
+            console.log(`  tier1 (build): ${detection.verification.tier1.join(', ')}`);
+        }
+        if (detection.verification.tier2.length > 0) {
+            console.log(`  tier2 (tests): ${detection.verification.tier2.join(', ')}`);
+        }
+        if (detection.presets.length > 0) {
+            console.log(`  presets: ${detection.presets.join(', ')}`);
+        }
+        console.log('');
+    }
+    else {
+        // No verification detected - provide detailed guidance
+        console.log('⚠️  No verification commands detected\n');
+        // Explain why based on the reason
+        const reason = detection.reason;
+        if (reason === 'no-package-json') {
+            console.log('No package.json found in this repository.');
+            console.log('For JavaScript/TypeScript projects, add a package.json with npm scripts.');
+        }
+        else if (reason === 'empty-scripts') {
+            console.log('Found package.json but it has no scripts defined.');
+            console.log('Add verification scripts like "test", "build", "lint", or "typecheck".');
+        }
+        else if (reason === 'no-matching-scripts') {
+            console.log('Found package.json with scripts, but none match common verification patterns.');
+            console.log('Expected scripts: test, build, lint, typecheck, tsc, eslint, jest, vitest.');
+        }
+        else if (reason === 'invalid-package-json') {
+            console.log('Found package.json but could not parse it (invalid JSON).');
+        }
+        console.log('');
+        console.log('📝 Next steps:');
+        console.log('');
+        console.log('Option 1: Manual configuration');
+        console.log(`  • Edit: ${configPath}`);
+        console.log('  • Add verification commands to tier0/tier1/tier2 arrays');
+        console.log('  • Example tier0: ["npm run lint", "npm run typecheck"]');
+        console.log('  • Example tier1: ["npm run build"]');
+        console.log('  • Example tier2: ["npm run test"]');
+        console.log('');
+        console.log('Option 2: Interactive setup');
+        console.log('  • Run: runr init --interactive --force');
+        console.log('  • Follow prompts to configure verification');
+        console.log('');
+    }
+    if (detection.source !== 'none') {
+        console.log('Next steps:');
+        console.log('  1. Review/edit .runr/runr.config.json');
+        console.log('  2. Create a task file in .runr/tasks/');
+        console.log('  3. Run: runr run --task .runr/tasks/your-task.md --worktree');
+    }
+    else {
+        console.log('After configuring verification:');
+        console.log('  1. Create a task file in .runr/tasks/');
+        console.log('  2. Run: runr run --task .runr/tasks/your-task.md --worktree');
+    }
+}

package/dist/commands/next.js

@@ -0,0 +1,25 @@
+import { getRunsRoot } from '../store/runs-root.js';
+import fs from 'node:fs';
+import path from 'node:path';
+/**
+ * Print the suggested next command from stop.json handoff
+ */
+export async function nextCommand(runId, options = {}) {
+    const repoPath = options.repo || process.cwd();
+    const runsRoot = getRunsRoot(repoPath);
+    // Read stop.json directly (no need to resolve - CLI already handles "latest")
+    const stopJsonPath = path.join(runsRoot, runId, 'handoffs', 'stop.json');
+    if (!fs.existsSync(stopJsonPath)) {
+        console.error(`No stop handoff found for run ${runId}`);
+        console.error(`Expected: ${stopJsonPath}`);
+        process.exit(1);
+    }
+    const stopData = JSON.parse(fs.readFileSync(stopJsonPath, 'utf-8'));
+    if (!stopData.next_actions || stopData.next_actions.length === 0) {
+        console.error(`No next actions available for run ${runId}`);
+        process.exit(1);
+    }
+    // Print the first suggested command
+    const nextAction = stopData.next_actions[0];
+    console.log(nextAction.command);
+}

package/dist/commands/report.js

@@ -19,6 +19,9 @@ export async function reportCommand(options) {
     const timelinePath = path.join(runDir, 'timeline.jsonl');
     const defaultKpi = {
         version: 1,
+        run_id: options.runId,
+        phase: state.phase || null,
+        checkpoint_sha: state.checkpoint_commit_sha || null,
         total_duration_ms: null,
         unattributed_ms: null,
         started_at: null,
@@ -26,7 +29,7 @@ export async function reportCommand(options) {
         phases: {},
         workers: { claude: 'unknown', codex: 'unknown' },
         verify: { attempts: 0, retries: 0, total_duration_ms: 0 },
-        milestones: { completed: 0 },
+        milestones: { completed: 0, total: state.milestones?.length || 0 },
         reliability: {
             infra_retries: 0,
             fallback_used: false,
@@ -35,11 +38,18 @@ export async function reportCommand(options) {
             late_results_ignored: 0
         },
         outcome: 'unknown',
-        stop_reason: null
+        stop_reason: null,
+        next_action: 'inspect_logs',
+        suggested_command: null
     };
     const scan = fs.existsSync(timelinePath)
         ? await scanTimeline(timelinePath, options.tail)
         : { tailEvents: [], kpi: defaultKpi };
+    // Merge run-specific fields into KPI (these aren't in timeline events)
+    scan.kpi.run_id = options.runId;
+    scan.kpi.phase = state.phase || null;
+    scan.kpi.checkpoint_sha = state.checkpoint_commit_sha || null;
+    scan.kpi.milestones.total = state.milestones?.length || 0;
     const flags = readFlags(scan.runStarted);
     const contextPackArtifact = readContextPackArtifact(runDir);
     const header = [
@@ -57,6 +67,11 @@ export async function reportCommand(options) {
         `allow_deps: ${flags.allow_deps ?? 'unknown'}`
     ].join('\n');
     const kpiBlock = formatKpiBlock(scan.kpi, contextPackArtifact);
+    if (options.json) {
+        // JSON output: full KPI object with next_action and suggested_command
+        console.log(JSON.stringify(scan.kpi, null, 2));
+        return;
+    }
     if (options.kpiOnly) {
         // Compact output: just run_id and KPIs
         console.log(`${options.runId}: ${scan.kpi.outcome} ${formatDuration(scan.kpi.total_duration_ms)} milestones=${scan.kpi.milestones.completed}`);
@@ -322,8 +337,41 @@ export function computeKpiFromEvents(events) {
         const attributedMs = Object.values(phases).reduce((sum, p) => sum + p.duration_ms, 0);
         unattributedMs = totalDurationMs - attributedMs;
     }
+    // Compute next_action and suggested_command
+    let nextAction = 'inspect_logs';
+    let suggestedCommand = null;
+    if (outcome === 'complete') {
+        nextAction = 'none';
+    }
+    else if (outcome === 'stopped' && stopReason) {
+        const resumableReasons = ['verification_failed_max_retries', 'stalled_timeout', 'max_ticks_reached', 'time_budget_exceeded', 'implement_blocked'];
+        const scopeViolationReasons = ['guard_violation', 'plan_scope_violation', 'ownership_violation'];
+        const configIssueReasons = ['plan_parse_failed', 'implement_parse_failed', 'review_parse_failed'];
+        if (resumableReasons.includes(stopReason)) {
+            nextAction = 'resume';
+            suggestedCommand = `runr resume <run_id>`;
+        }
+        else if (scopeViolationReasons.includes(stopReason)) {
+            nextAction = 'resolve_scope_violation';
+            suggestedCommand = `# Review .runr/runr.config.json scope settings`;
+        }
+        else if (stopReason === 'parallel_file_collision') {
+            nextAction = 'resolve_branch_mismatch';
+            suggestedCommand = `# Wait for conflicting run to finish, then resume`;
+        }
+        else if (configIssueReasons.includes(stopReason)) {
+            nextAction = 'fix_config';
+            suggestedCommand = `runr init --interactive`;
+        }
+    }
+    else if (outcome === 'running') {
+        suggestedCommand = `runr status <run_id>`;
+    }
     return {
         version: 1,
+        run_id: '', // Will be filled by reportCommand
+        phase: null, // Will be filled by reportCommand
+        checkpoint_sha: null, // Will be filled by reportCommand
         total_duration_ms: totalDurationMs,
         unattributed_ms: unattributedMs,
         started_at: startedAt,
@@ -339,7 +387,8 @@ export function computeKpiFromEvents(events) {
             total_duration_ms: verifyDurationMs
         },
         milestones: {
-            completed: milestonesCompleted
+            completed: milestonesCompleted,
+            total: 0 // Will be filled by reportCommand
         },
         reliability: {
             infra_retries: infraRetries,
@@ -349,7 +398,9 @@ export function computeKpiFromEvents(events) {
             late_results_ignored: lateResultsIgnored
         },
         outcome,
-        stop_reason: stopReason
+        stop_reason: stopReason,
+        next_action: nextAction,
+        suggested_command: suggestedCommand
     };
 }
 async function scanTimeline(timelinePath, tailCount) {

package/dist/commands/watch.js

@@ -0,0 +1,187 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { getRunsRoot } from '../store/runs-root.js';
+import { resumeCommand } from './resume.js';
+/**
+ * Check if a failure is resumable (transient or recoverable)
+ */
+function isResumable(state) {
+    if (state.phase !== 'STOPPED') {
+        return false;
+    }
+    const resumableReasons = [
+        'verification_failed_max_retries',
+        'stalled_timeout',
+        'max_ticks_reached',
+        'time_budget_exceeded',
+        'implement_blocked'
+    ];
+    const nonResumableReasons = [
+        'guard_violation',
+        'plan_scope_violation',
+        'ownership_violation',
+        'review_loop_detected',
+        'parallel_file_collision'
+    ];
+    if (!state.stop_reason) {
+        return false;
+    }
+    if (resumableReasons.includes(state.stop_reason)) {
+        return true;
+    }
+    if (nonResumableReasons.includes(state.stop_reason)) {
+        return false;
+    }
+    // Unknown stop reason: default to non-resumable (safe)
+    return false;
+}
+/**
+ * Read current run state
+ */
+function readState(repo, runId) {
+    const statePath = path.join(getRunsRoot(repo), runId, 'state.json');
+    if (!fs.existsSync(statePath)) {
+        return null;
+    }
+    try {
+        const raw = fs.readFileSync(statePath, 'utf-8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Emit watch event
+ */
+function emitEvent(event, json) {
+    if (json) {
+        console.log(JSON.stringify(event));
+    }
+    else {
+        switch (event.event) {
+            case 'watching':
+                console.log(`[${event.timestamp}] Watching run ${event.run_id} (phase: ${event.phase})`);
+                break;
+            case 'failed':
+                console.log(`[${event.timestamp}] Run ${event.run_id} failed: ${event.stop_reason}`);
+                break;
+            case 'resumed':
+                console.log(`[${event.timestamp}] Auto-resuming (attempt ${event.attempt}/${event.max_attempts}) from checkpoint ${event.checkpoint || 'unknown'}`);
+                break;
+            case 'succeeded':
+                console.log(`[${event.timestamp}] Run ${event.run_id} completed successfully!`);
+                break;
+            case 'max_attempts':
+                console.log(`[${event.timestamp}] Max auto-resume attempts (${event.max_attempts}) reached. Stopped.`);
+                break;
+            case 'non_resumable':
+                console.log(`[${event.timestamp}] Run ${event.run_id} stopped with non-resumable reason: ${event.stop_reason}`);
+                break;
+        }
+    }
+}
+/**
+ * Sleep for N milliseconds
+ */
+function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+/**
+ * Watch a run and optionally auto-resume on failure
+ */
+export async function watchCommand(options) {
+    const interval = options.interval || 5000; // 5 seconds default
+    const maxAttempts = options.maxAttempts ?? (options.autoResume ? 3 : 0);
+    let attemptCount = 0;
+    while (true) {
+        const state = readState(options.repo, options.runId);
+        if (!state) {
+            console.error(`Error: Run ${options.runId} not found`);
+            process.exit(1);
+        }
+        const timestamp = new Date().toISOString();
+        // Check if terminal
+        if (state.phase === 'STOPPED') {
+            if (state.stop_reason === 'complete') {
+                // Success
+                emitEvent({
+                    timestamp,
+                    run_id: options.runId,
+                    event: 'succeeded'
+                }, options.json || false);
+                process.exit(0);
+            }
+            // Failed
+            emitEvent({
+                timestamp,
+                run_id: options.runId,
+                event: 'failed',
+                stop_reason: state.stop_reason,
+                checkpoint: state.checkpoint_commit_sha
+            }, options.json || false);
+            // Check if auto-resume
+            if (options.autoResume && isResumable(state)) {
+                if (attemptCount >= maxAttempts) {
+                    emitEvent({
+                        timestamp,
+                        run_id: options.runId,
+                        event: 'max_attempts',
+                        max_attempts: maxAttempts
+                    }, options.json || false);
+                    process.exit(1);
+                }
+                attemptCount++;
+                emitEvent({
+                    timestamp,
+                    run_id: options.runId,
+                    event: 'resumed',
+                    attempt: attemptCount,
+                    max_attempts: maxAttempts,
+                    checkpoint: state.checkpoint_commit_sha
+                }, options.json || false);
+                // Cooldown before resume (10 seconds)
+                await sleep(10000);
+                // Resume (don't await, let it run in background)
+                try {
+                    await resumeCommand({
+                        runId: options.runId,
+                        repo: options.repo,
+                        time: 120,
+                        maxTicks: 50,
+                        allowDeps: false,
+                        force: false,
+                        autoResume: false
+                    });
+                }
+                catch (err) {
+                    console.error(`Resume failed: ${err}`);
+                    process.exit(1);
+                }
+                // Continue watching after resume
+                await sleep(interval);
+                continue;
+            }
+            else {
+                // Non-resumable or auto-resume disabled
+                if (!isResumable(state)) {
+                    emitEvent({
+                        timestamp,
+                        run_id: options.runId,
+                        event: 'non_resumable',
+                        stop_reason: state.stop_reason
+                    }, options.json || false);
+                }
+                process.exit(1);
+            }
+        }
+        // Still running
+        emitEvent({
+            timestamp,
+            run_id: options.runId,
+            event: 'watching',
+            phase: state.phase
+        }, options.json || false);
+        await sleep(interval);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@weldr/runr",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Phase-gated orchestration for agent tasks",
   "type": "module",
   "bin": {