@weldr/runr 0.3.0

package/dist/orchestrator/types.js

@@ -0,0 +1,88 @@
+/**
+ * Orchestrator types for multi-track run coordination.
+ *
+ * The orchestrator manages parallel tracks of serial steps,
+ * with collision-aware scheduling to prevent merge conflicts.
+ */
+import { z } from 'zod';
+// Zod schemas for validation
+export const stepConfigSchema = z.object({
+    task: z.string().min(1),
+    allowlist: z.array(z.string()).optional()
+});
+export const trackConfigSchema = z.object({
+    name: z.string().min(1),
+    steps: z.array(stepConfigSchema).min(1)
+});
+export const orchestrationConfigSchema = z.object({
+    tracks: z.array(trackConfigSchema).min(1)
+});
+export const stepResultSchema = z.object({
+    status: z.enum(['complete', 'stopped', 'timeout']),
+    stop_reason: z.string().optional(),
+    elapsed_ms: z.number()
+});
+export const stepSchema = z.object({
+    task_path: z.string(),
+    allowlist: z.array(z.string()).optional(),
+    owns_raw: z.array(z.string()).optional(),
+    owns_normalized: z.array(z.string()).optional(),
+    run_id: z.string().optional(),
+    run_dir: z.string().optional(),
+    result: stepResultSchema.optional()
+});
+export const trackSchema = z.object({
+    id: z.string(),
+    name: z.string(),
+    steps: z.array(stepSchema),
+    current_step: z.number(),
+    status: z.enum(['pending', 'running', 'waiting', 'complete', 'stopped', 'failed']),
+    error: z.string().optional()
+});
+export const orchestratorPolicySchema = z.object({
+    collision_policy: z.enum(['serialize', 'force', 'fail']),
+    parallel: z.number(),
+    fast: z.boolean(),
+    auto_resume: z.boolean(),
+    ownership_required: z.boolean().optional(),
+    time_budget_minutes: z.number(),
+    max_ticks: z.number()
+});
+const ownershipClaimSchema = z.object({
+    track_id: z.string(),
+    run_id: z.string().optional(),
+    owns_raw: z.array(z.string()),
+    owns_normalized: z.array(z.string())
+});
+const ownershipClaimEventSchema = z.object({
+    timestamp: z.string(),
+    action: z.enum(['acquire', 'release']),
+    track_id: z.string(),
+    run_id: z.string().optional(),
+    claims: z.array(z.string()),
+    owns_raw: z.array(z.string()),
+    owns_normalized: z.array(z.string())
+});
+export const orchestratorStateSchema = z.object({
+    orchestrator_id: z.string(),
+    repo_path: z.string(),
+    tracks: z.array(trackSchema),
+    active_runs: z.record(z.string()),
+    file_claims: z.record(z.union([z.string(), ownershipClaimSchema])),
+    claim_events: z.array(ownershipClaimEventSchema).optional(),
+    status: z.enum(['running', 'complete', 'stopped', 'failed']),
+    started_at: z.string(),
+    ended_at: z.string().optional(),
+    // v1+ policy block
+    policy: orchestratorPolicySchema.optional(),
+    // Legacy fields (v0) - kept for backward compatibility
+    collision_policy: z.enum(['serialize', 'force', 'fail']),
+    time_budget_minutes: z.number(),
+    max_ticks: z.number(),
+    fast: z.boolean().optional()
+});
+/**
+ * Current schema version for orchestration artifacts.
+ * Increment when making breaking changes to the structure.
+ */
+export const ORCHESTRATOR_ARTIFACT_SCHEMA_VERSION = 1;

package/dist/ownership/normalize.js

@@ -0,0 +1,45 @@
+import path from 'node:path';
+/**
+ * Normalize a single ownership pattern to POSIX format with glob suffix.
+ * - Strips leading ./ and /
+ * - Converts backslashes to forward slashes
+ * - Adds /** suffix to bare directories
+ * - Returns null for empty/invalid patterns
+ */
+export function normalizeOwnPattern(pattern) {
+    let normalized = pattern.replace(/\\/g, '/').trim();
+    normalized = normalized.replace(/^\.\/+/, '').replace(/^\/+/, '');
+    normalized = normalized.replace(/\/{2,}/g, '/');
+    if (!normalized) {
+        return null;
+    }
+    const hasGlob = /[*?[\]]/.test(normalized);
+    if (!hasGlob) {
+        normalized = normalized.replace(/\/+$/, '');
+        if (!normalized) {
+            return null;
+        }
+        return `${normalized}/**`;
+    }
+    return normalized;
+}
+/**
+ * Normalize an array of ownership patterns.
+ * Deduplicates and filters out invalid patterns.
+ */
+export function normalizeOwnsPatterns(patterns) {
+    const normalized = [];
+    for (const pattern of patterns) {
+        const entry = normalizeOwnPattern(pattern);
+        if (entry) {
+            normalized.push(entry);
+        }
+    }
+    return [...new Set(normalized)];
+}
+/**
+ * Convert a file path to POSIX format for matching.
+ */
+export function toPosixPath(filePath) {
+    return filePath.split(path.sep).join('/');
+}

package/dist/repo/context.js

@@ -0,0 +1,90 @@
+import path from 'node:path';
+import { git, gitOptional } from './git.js';
+export async function getGitRoot(repoPath) {
+    const result = await git(['rev-parse', '--show-toplevel'], repoPath);
+    return result.stdout.trim();
+}
+export async function getDefaultBranch(repoPath, fallback) {
+    const result = await gitOptional(['symbolic-ref', 'refs/remotes/origin/HEAD'], repoPath);
+    if (result?.stdout) {
+        const parts = result.stdout.trim().split('/');
+        const branch = parts[parts.length - 1];
+        if (branch) {
+            return branch;
+        }
+    }
+    return fallback;
+}
+export async function getCurrentBranch(repoPath) {
+    const result = await git(['rev-parse', '--abbrev-ref', 'HEAD'], repoPath);
+    return result.stdout.trim();
+}
+export async function listChangedFiles(gitRoot) {
+    const result = await git(['status', '--porcelain'], gitRoot);
+    const lines = result.stdout.split('\n').filter((line) => line.trim().length > 0);
+    if (lines.length === 0) {
+        return [];
+    }
+    const files = [];
+    for (const line of lines) {
+        const entry = line.slice(3);
+        const arrow = entry.indexOf('->');
+        if (arrow !== -1) {
+            // Rename: include BOTH old and new paths for ownership/scope enforcement
+            // Old path was touched (deleted from), new path was touched (created at)
+            const oldPath = entry.slice(0, arrow).trim();
+            const newPath = entry.slice(arrow + 2).trim();
+            if (oldPath)
+                files.push(oldPath);
+            if (newPath)
+                files.push(newPath);
+        }
+        else {
+            const filePath = entry.trim();
+            if (filePath)
+                files.push(filePath);
+        }
+    }
+    // Deduplicate: renames or multiple status entries can reference same path
+    return [...new Set(files)];
+}
+export function getTouchedPackages(changedFiles) {
+    const packages = new Set();
+    for (const file of changedFiles) {
+        const parts = file.split(path.sep);
+        const idx = parts.indexOf('packages');
+        if (idx !== -1 && parts.length > idx + 1) {
+            packages.add(path.join('packages', parts[idx + 1]));
+            continue;
+        }
+        if (parts[0] === 'package.json') {
+            packages.add('root');
+        }
+    }
+    return Array.from(packages);
+}
+export function toRunBranch(runId, slug) {
+    const safeSlug = slug
+        .toLowerCase()
+        .replace(/[^a-z0-9-]/g, '-')
+        .replace(/-+/g, '-')
+        .replace(/^-+|-+$/g, '');
+    return `agent/${runId}/${safeSlug || 'task'}`;
+}
+export async function buildRepoContext(repoPath, runId, slug, defaultBranchFallback) {
+    const gitRoot = await getGitRoot(repoPath);
+    const defaultBranch = await getDefaultBranch(gitRoot, defaultBranchFallback);
+    const currentBranch = await getCurrentBranch(gitRoot);
+    const runBranch = toRunBranch(runId, slug);
+    const changedFiles = await listChangedFiles(gitRoot);
+    const touchedPackages = getTouchedPackages(changedFiles);
+    return {
+        repo_path: repoPath,
+        git_root: gitRoot,
+        default_branch: defaultBranch,
+        run_branch: runBranch,
+        current_branch: currentBranch,
+        changed_files: changedFiles,
+        touched_packages: touchedPackages
+    };
+}

package/dist/repo/git.js

@@ -0,0 +1,13 @@
+import { execa } from 'execa';
+export async function git(args, cwd) {
+    const result = await execa('git', args, { cwd });
+    return { stdout: result.stdout, stderr: result.stderr };
+}
+export async function gitOptional(args, cwd) {
+    try {
+        return await git(args, cwd);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/repo/worktree.js

@@ -0,0 +1,239 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { git, gitOptional } from './git.js';
+/**
+ * Resolve the actual git directory for a worktree.
+ * In a worktree, .git is a file containing "gitdir: <path>".
+ * In a normal repo, .git is the directory itself.
+ */
+function resolveWorktreeGitDir(worktreePath) {
+    const dotGitPath = path.join(worktreePath, '.git');
+    let stat;
+    try {
+        stat = fs.statSync(dotGitPath);
+    }
+    catch (err) {
+        const e = err;
+        if (e.code === 'ENOENT') {
+            throw new Error(`Worktree missing .git file/dir at ${dotGitPath} (worktreePath=${worktreePath})`);
+        }
+        throw err;
+    }
+    if (stat.isDirectory()) {
+        return dotGitPath;
+    }
+    // Worktree: .git is a file with "gitdir: ..."
+    const content = fs.readFileSync(dotGitPath, 'utf8').trim();
+    const m = content.match(/^gitdir:\s*(.+)\s*$/i);
+    if (!m) {
+        throw new Error(`Unexpected .git file format at ${dotGitPath}: ${content.slice(0, 120)}`);
+    }
+    const gitdirPath = m[1].trim();
+    // gitdir can be relative to worktreePath
+    return path.isAbsolute(gitdirPath)
+        ? gitdirPath
+        : path.resolve(worktreePath, gitdirPath);
+}
+/**
+ * Add patterns to .git/info/exclude.
+ * This prevents env artifacts like node_modules symlinks from showing as untracked.
+ */
+function upsertInfoExclude(gitdir, patterns) {
+    const infoDir = path.join(gitdir, 'info');
+    const excludePath = path.join(infoDir, 'exclude');
+    fs.mkdirSync(infoDir, { recursive: true });
+    const existing = fs.existsSync(excludePath)
+        ? fs.readFileSync(excludePath, 'utf8')
+        : '';
+    const existingLines = new Set(existing
+        .split(/\r?\n/)
+        .map(l => l.trim())
+        .filter(l => l.length > 0 && !l.startsWith('#')));
+    // Find patterns we need to add
+    const toAdd = patterns.filter(p => !existingLines.has(p));
+    if (toAdd.length === 0)
+        return;
+    // Build new content
+    const needsNewline = existing.length > 0 && !existing.endsWith('\n');
+    const header = existing.includes('# runr env ignores') || existing.includes('# agent-framework env ignores')
+        ? ''
+        : '# runr env ignores\n';
+    const addition = (needsNewline ? '\n' : '') + header + toAdd.map(p => `${p}\n`).join('');
+    fs.writeFileSync(excludePath, existing + addition, 'utf8');
+}
+/**
+ * Ensure repository-level git excludes for runr artifacts.
+ * Call this at run start (before preflight) to prevent .runr/ and .runr-worktrees/
+ * (or legacy .agent/ and .agent-worktrees/) from showing as dirty.
+ *
+ * This writes to the MAIN repo's .git/info/exclude (not tracked, no history pollution).
+ *
+ * @param repoRoot - The target repository root path
+ * @param patterns - Patterns to add (e.g., ['.runr', '.runr/', '.runr-worktrees'])
+ */
+export function ensureRepoInfoExclude(repoRoot, patterns) {
+    const mainGitDir = path.join(repoRoot, '.git');
+    // Only proceed if this looks like a git repo
+    if (!fs.existsSync(mainGitDir) || !fs.statSync(mainGitDir).isDirectory()) {
+        return;
+    }
+    upsertInfoExclude(mainGitDir, patterns);
+}
+/**
+ * Create a git worktree for isolated run execution.
+ *
+ * @param originalRepoPath - The source repository path
+ * @param worktreePath - Where to create the worktree (e.g., worktrees/<id>)
+ * @param runBranch - Optional branch name to create/use
+ * @returns WorktreeInfo with paths and base SHA
+ */
+export async function createWorktree(originalRepoPath, worktreePath, runBranch) {
+    // Get current HEAD SHA as base
+    const headResult = await git(['rev-parse', 'HEAD'], originalRepoPath);
+    const baseSha = headResult.stdout.trim();
+    // Ensure parent directory exists
+    const parentDir = path.dirname(worktreePath);
+    if (!fs.existsSync(parentDir)) {
+        fs.mkdirSync(parentDir, { recursive: true });
+    }
+    // Remove existing worktree if present (from failed run)
+    if (fs.existsSync(worktreePath)) {
+        await gitOptional(['worktree', 'remove', '--force', worktreePath], originalRepoPath);
+        // If git worktree remove failed, try rmdir
+        if (fs.existsSync(worktreePath)) {
+            fs.rmSync(worktreePath, { recursive: true, force: true });
+        }
+    }
+    if (runBranch) {
+        // Check if branch exists (gitOptional returns null on error/non-existent)
+        const branchCheck = await gitOptional(['rev-parse', '--verify', runBranch], originalRepoPath);
+        if (branchCheck !== null) {
+            // Branch exists, create worktree attached to it
+            await git(['worktree', 'add', worktreePath, runBranch], originalRepoPath);
+        }
+        else {
+            // Create new branch and worktree together
+            await git(['worktree', 'add', '-b', runBranch, worktreePath, baseSha], originalRepoPath);
+        }
+    }
+    else {
+        // Detached HEAD at base SHA
+        await git(['worktree', 'add', '--detach', worktreePath, baseSha], originalRepoPath);
+    }
+    // Validate worktree was created successfully and is clean
+    const statusBefore = await git(['status', '--porcelain'], worktreePath);
+    if (statusBefore.stdout.trim().length > 0) {
+        throw new Error(`Newly created worktree is not clean:\n${statusBefore.stdout}`);
+    }
+    // Inject excludes into MAIN repo's .git/info/exclude (git only reads from there, not worktree gitdir)
+    // This prevents env artifacts like node_modules symlinks from showing as untracked
+    const mainGitDir = path.join(originalRepoPath, '.git');
+    upsertInfoExclude(mainGitDir, [
+        'node_modules',
+        'node_modules/',
+        '/node_modules',
+    ]);
+    // Symlink node_modules from original repo if present (for npm/pnpm projects)
+    const originalNodeModules = path.join(originalRepoPath, 'node_modules');
+    const worktreeNodeModules = path.join(worktreePath, 'node_modules');
+    if (fs.existsSync(originalNodeModules) && !fs.existsSync(worktreeNodeModules)) {
+        fs.symlinkSync(originalNodeModules, worktreeNodeModules, 'dir');
+    }
+    // Sanity check: worktree should still be clean after env setup
+    const statusAfter = await git(['status', '--porcelain'], worktreePath);
+    if (statusAfter.stdout.trim().length > 0) {
+        throw new Error(`Worktree became dirty after env setup:\n${statusAfter.stdout}`);
+    }
+    return {
+        worktree_enabled: true,
+        original_repo_path: originalRepoPath,
+        effective_repo_path: worktreePath,
+        base_sha: baseSha,
+        run_branch: runBranch,
+        created_at: new Date().toISOString()
+    };
+}
+/**
+ * Validate that a worktree exists and is usable.
+ *
+ * @param worktreePath - Path to the worktree
+ * @returns true if valid, false otherwise
+ */
+export async function validateWorktree(worktreePath) {
+    if (!fs.existsSync(worktreePath)) {
+        return false;
+    }
+    try {
+        const result = await gitOptional(['rev-parse', '--is-inside-work-tree'], worktreePath);
+        return result?.stdout?.trim() === 'true';
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Remove a worktree cleanly.
+ *
+ * @param originalRepoPath - The source repository path
+ * @param worktreePath - Path to the worktree to remove
+ */
+export async function removeWorktree(originalRepoPath, worktreePath) {
+    if (!fs.existsSync(worktreePath)) {
+        return;
+    }
+    // Try git worktree remove first (cleaner)
+    const result = await gitOptional(['worktree', 'remove', '--force', worktreePath], originalRepoPath);
+    // If git failed (result is null), manually remove
+    if (result === null && fs.existsSync(worktreePath)) {
+        fs.rmSync(worktreePath, { recursive: true, force: true });
+    }
+}
+/**
+ * Recreate a worktree from saved info (for resume).
+ * Validates branch matches if worktree exists but has wrong branch.
+ *
+ * @param info - Saved worktree info from config snapshot
+ * @param force - Allow recreation despite branch mismatch
+ * @returns Result with updated info and flags, or throws if recreation fails
+ */
+export async function recreateWorktree(info, force = false) {
+    // Check if worktree already exists and is valid
+    if (await validateWorktree(info.effective_repo_path)) {
+        // Ensure excludes are present in MAIN repo (upgrades old worktrees created before this fix)
+        const mainGitDir = path.join(info.original_repo_path, '.git');
+        upsertInfoExclude(mainGitDir, ['node_modules', 'node_modules/', '/node_modules']);
+        // Verify branch matches if one was specified
+        if (info.run_branch) {
+            const currentBranchResult = await gitOptional(['rev-parse', '--abbrev-ref', 'HEAD'], info.effective_repo_path);
+            const currentBranch = currentBranchResult?.stdout?.trim();
+            if (currentBranch && currentBranch !== info.run_branch) {
+                if (!force) {
+                    throw new Error(`Branch mismatch: worktree is on '${currentBranch}' but run was on '${info.run_branch}'. ` +
+                        `Use --force to override.`);
+                }
+                console.warn(`WARNING: Branch mismatch (expected '${info.run_branch}', found '${currentBranch}'). Continuing due to --force.`);
+                return {
+                    info,
+                    recreated: false,
+                    branchMismatch: true,
+                    nodeModulesSymlinked: fs.existsSync(path.join(info.effective_repo_path, 'node_modules'))
+                };
+            }
+        }
+        return {
+            info,
+            recreated: false,
+            branchMismatch: false,
+            nodeModulesSymlinked: fs.existsSync(path.join(info.effective_repo_path, 'node_modules'))
+        };
+    }
+    // Recreate from original repo
+    const recreatedInfo = await createWorktree(info.original_repo_path, info.effective_repo_path, info.run_branch);
+    const nodeModulesPath = path.join(info.effective_repo_path, 'node_modules');
+    return {
+        info: recreatedInfo,
+        recreated: true,
+        branchMismatch: false,
+        nodeModulesSymlinked: fs.existsSync(nodeModulesPath)
+    };
+}

package/dist/store/run-store.js

@@ -0,0 +1,107 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { getRunsRoot } from './runs-root.js';
+export class RunStore {
+    runDir;
+    timelinePath;
+    seqPath;
+    lastEvent = null;
+    lastWorkerCall = null;
+    constructor(runDir) {
+        this.runDir = runDir;
+        this.timelinePath = path.join(runDir, 'timeline.jsonl');
+        this.seqPath = path.join(runDir, 'seq.txt');
+    }
+    /**
+     * Initialize a RunStore for a new or existing run.
+     * @param runId - The run ID (timestamp format)
+     * @param repoPath - The target repository path (required)
+     */
+    static init(runId, repoPath) {
+        const rootDir = getRunsRoot(repoPath);
+        const runDir = path.join(rootDir, runId);
+        fs.mkdirSync(runDir, { recursive: true });
+        fs.mkdirSync(path.join(runDir, 'artifacts'), { recursive: true });
+        fs.mkdirSync(path.join(runDir, 'handoffs'), { recursive: true });
+        if (!fs.existsSync(path.join(runDir, 'timeline.jsonl'))) {
+            fs.writeFileSync(path.join(runDir, 'timeline.jsonl'), '');
+        }
+        return new RunStore(runDir);
+    }
+    get path() {
+        return this.runDir;
+    }
+    writeConfigSnapshot(config) {
+        const target = path.join(this.runDir, 'config.snapshot.json');
+        fs.writeFileSync(target, JSON.stringify(config, null, 2));
+    }
+    writePlan(content) {
+        const target = path.join(this.runDir, 'plan.md');
+        fs.writeFileSync(target, content);
+    }
+    writeState(state) {
+        const target = path.join(this.runDir, 'state.json');
+        fs.writeFileSync(target, JSON.stringify(state, null, 2));
+    }
+    readState() {
+        const target = path.join(this.runDir, 'state.json');
+        const raw = fs.readFileSync(target, 'utf-8');
+        return JSON.parse(raw);
+    }
+    writeSummary(content) {
+        const target = path.join(this.runDir, 'summary.md');
+        fs.writeFileSync(target, content);
+    }
+    writeArtifact(name, content) {
+        const target = path.join(this.runDir, 'artifacts', name);
+        fs.writeFileSync(target, content);
+    }
+    writeMemo(name, content) {
+        const target = path.join(this.runDir, 'handoffs', name);
+        fs.writeFileSync(target, content);
+    }
+    writeFingerprint(fingerprint) {
+        const target = path.join(this.runDir, 'env.fingerprint.json');
+        fs.writeFileSync(target, JSON.stringify(fingerprint, null, 2));
+    }
+    readFingerprint() {
+        const target = path.join(this.runDir, 'env.fingerprint.json');
+        if (!fs.existsSync(target)) {
+            return null;
+        }
+        const raw = fs.readFileSync(target, 'utf-8');
+        return JSON.parse(raw);
+    }
+    appendEvent(event) {
+        const seq = this.nextSeq();
+        const full = {
+            ...event,
+            seq,
+            timestamp: new Date().toISOString()
+        };
+        fs.appendFileSync(this.timelinePath, `${JSON.stringify(full)}\n`);
+        this.lastEvent = full;
+        return full;
+    }
+    getLastEvent() {
+        return this.lastEvent;
+    }
+    recordWorkerCall(info) {
+        this.lastWorkerCall = info;
+    }
+    getLastWorkerCall() {
+        return this.lastWorkerCall;
+    }
+    nextSeq() {
+        let current = 0;
+        if (fs.existsSync(this.seqPath)) {
+            const raw = fs.readFileSync(this.seqPath, 'utf-8').trim();
+            if (raw) {
+                current = Number.parseInt(raw, 10) || 0;
+            }
+        }
+        const next = current + 1;
+        fs.writeFileSync(this.seqPath, String(next));
+        return next;
+    }
+}

package/dist/store/run-utils.js

@@ -0,0 +1,69 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { getRunsRoot } from './runs-root.js';
+/**
+ * Find the most recent run ID by scanning the runs directory.
+ * Run IDs are expected to be 14-digit timestamps (YYYYMMDDHHmmss).
+ * @param repoPath - The target repository path (defaults to current working directory)
+ * @returns The latest run ID or null if no runs exist
+ */
+export function findLatestRunId(repoPath = process.cwd()) {
+    const rootDir = getRunsRoot(repoPath);
+    if (!fs.existsSync(rootDir)) {
+        return null;
+    }
+    const entries = fs
+        .readdirSync(rootDir, { withFileTypes: true })
+        .filter((e) => e.isDirectory() && /^\d{14}$/.test(e.name))
+        .map((e) => e.name)
+        .sort()
+        .reverse();
+    return entries[0] ?? null;
+}
+/**
+ * Resolve a run ID, supporting 'latest' as a special value.
+ * @param runId - The run ID or 'latest'
+ * @param repoPath - The target repository path (defaults to current working directory)
+ * @returns The resolved run ID
+ * @throws Error if 'latest' is specified but no runs exist
+ * @throws Error if the specified run directory does not exist
+ */
+export function resolveRunId(runId, repoPath = process.cwd()) {
+    const rootDir = getRunsRoot(repoPath);
+    let resolvedId = runId;
+    if (runId === 'latest') {
+        const latest = findLatestRunId(repoPath);
+        if (!latest) {
+            throw new Error('No runs found. Run a task first with `agent run`.');
+        }
+        resolvedId = latest;
+    }
+    // Validate that the run directory exists
+    const runDir = path.join(rootDir, resolvedId);
+    if (!fs.existsSync(runDir)) {
+        // List available runs for helpful error message
+        const knownRuns = listRecentRunIds(repoPath, 5);
+        const hint = knownRuns.length > 0 ? `Known runs: ${knownRuns.join(', ')}` : 'No runs found.';
+        throw new Error(`Run not found: ${resolvedId}. ${hint}`);
+    }
+    return resolvedId;
+}
+/**
+ * List recent run IDs, sorted by most recent first.
+ * @param repoPath - The target repository path (defaults to current working directory)
+ * @param limit - Maximum number of runs to return
+ * @returns Array of run IDs
+ */
+export function listRecentRunIds(repoPath = process.cwd(), limit = 10) {
+    const rootDir = getRunsRoot(repoPath);
+    if (!fs.existsSync(rootDir)) {
+        return [];
+    }
+    return fs
+        .readdirSync(rootDir, { withFileTypes: true })
+        .filter((e) => e.isDirectory() && /^\d{14}$/.test(e.name))
+        .map((e) => e.name)
+        .sort()
+        .reverse()
+        .slice(0, limit);
+}