@repo-os/repoos 0.5.45

package/dist/core/types.js

@@ -0,0 +1,27 @@
+/**
+ * RepoOS core types.
+ *
+ * The repo is the source of truth. A "task" is a markdown file with YAML
+ * frontmatter living under the configured work directory (default: `work/`).
+ * Task *status* is a frontmatter field — files never move between folders.
+ */
+/** Canonical lifecycle states. Order matters: it defines board column order. */
+export const STATUSES = ["draft", "inbox", "ready", "active", "review", "done"];
+export const PRIORITIES = ["p0", "p1", "p2", "p3"];
+export const TASK_TYPES = ["feature", "bug", "chore", "spec", "refactor"];
+/**
+ * Machine-readable reasons `needsInput` gets set, one per escalation call
+ * site. Stored alongside the flag so a later automated success (e.g. a
+ * review that finally completes cleanly) can tell whether IT is what the
+ * human was waited on for, and clear the flag itself rather than leaving it
+ * stuck forever once the underlying problem resolves. A boolean alone can't
+ * make that call safely — clearing on every success would just as happily
+ * wipe out an unrelated flag (e.g. a CTO policy question) that happened to
+ * still be pending.
+ */
+export const NEEDS_INPUT_REASONS = [
+    "review-failed",
+    "dev-error",
+    "watchdog-stuck",
+    "cto-escalation",
+];

package/dist/core/worktree-gc.d.ts

@@ -0,0 +1,57 @@
+import type { RepoOSConfig, Task } from "./types.js";
+export type GcMode = "integrate-only" | "full";
+export interface GcKept {
+    branch: string;
+    path: string;
+    /** Why it was left in place. */
+    reason: string;
+}
+export interface GcReport {
+    mode: GcMode;
+    dryRun: boolean;
+    /** Worktrees removed (or that would be, when dryRun). `branch` is "" for detached. */
+    removedWorktrees: Array<{
+        branch: string;
+        path: string;
+    }>;
+    /** Branches deleted (or that would be). */
+    removedBranches: string[];
+    /** Stale entries left in place with the reason. */
+    keptDirty: GcKept[];
+    /** True when `git worktree prune` ran (metadata for vanished directories). */
+    prunedMetadata: boolean;
+    /** Non-fatal problems (a `git worktree remove` that would not take, etc.). */
+    errors: string[];
+}
+export interface SweepOptions {
+    mode: GcMode;
+    dryRun?: boolean;
+    /**
+     * Task ids whose `repoos/integrate/<id>` candidate must be spared — a job is
+     * still queued/running/recovering for them. The boot sweep passes this.
+     */
+    activeJobIds?: Set<string>;
+    /**
+     * Every task on the board. Only needed for `mode: "full"`; omitted, it is read
+     * from a fresh `buildIndex`. `mode: "integrate-only"` never looks at tasks.
+     */
+    tasks?: Task[];
+}
+/**
+ * Sweep stale worktrees/branches. Synchronous and fail-soft — any git hiccup is
+ * recorded in `report.errors` and the sweep moves on.
+ */
+export declare function sweepStaleWorktrees(config: RepoOSConfig, opts: SweepOptions): GcReport;
+/** Number of registered git worktrees, including the main checkout. */
+export declare function countWorktrees(root: string): number;
+/**
+ * Run the conservative `integrate-only` sweep, then log its result and — when
+ * the surviving worktree count exceeds `threshold` (0 disables) — a
+ * "run `repoos gc`" warning. Shared by the boot path and every close-out.
+ * Fully fail-soft: a git hiccup is swallowed, never surfaced to the caller.
+ */
+export declare function sweepAndWarn(config: RepoOSConfig, opts: {
+    activeJobIds?: Set<string>;
+    threshold?: number;
+    log: (level: "info" | "warn", msg: string, meta?: Record<string, unknown>) => void;
+}): void;

package/dist/core/worktree-gc.js

@@ -0,0 +1,194 @@
+/**
+ * Garbage-collect leaked task worktrees and branches.
+ *
+ * Two things leak them:
+ *  - a close-out job that FAILS never removes its `repoos/integrate/<id>`
+ *    candidate worktree (the success path does, in the orchestrator's
+ *    `cleanup()`), and
+ *  - historically, close-outs that predate the non-blocking merge queue — plus
+ *    CLI `repoos mv <id> done`, which is a pure status edit — left the feature
+ *    worktree/branch behind entirely.
+ *
+ * Left alone they accumulate without bound, and every server cold boot pays one
+ * `git status` per registered worktree while enriching the index
+ * (`buildIndexAsync` -> `resolveWorktreeStatuses`).
+ *
+ * Scope boundary: this ONLY ever touches worktrees whose path is inside
+ * `worktreesDir(root)` (the `<root>-worktrees/` sibling directory that
+ * `ensureWorktree` always uses). The main checkout, this Claude Code session's
+ * `<root>/.claude/worktrees/*`, and any other coding agent's or tool's worktrees
+ * live outside that directory and are never RepoOS-managed — so no
+ * agent-specific branch-name matching is used anywhere.
+ */
+import { existsSync, realpathSync } from "node:fs";
+import { relative, isAbsolute } from "node:path";
+import { spawnSync } from "node:child_process";
+import { worktreesDir } from "./config.js";
+import { buildIndex } from "./indexer.js";
+import { isGitRepo, currentBranch, listWorktrees, removeWorktree, deleteBranch, pruneWorktrees, isAncestor, } from "./git.js";
+const CANDIDATE_BRANCH_PREFIX = "repoos/integrate/";
+/**
+ * True when the worktree has no meaningful uncommitted work. `dist/` and
+ * `screenshots/` are generated build output (routinely committed on a branch
+ * and re-dirtied) — excluded here the same way `DIFF_SOURCE_PATHS` does for the
+ * review diff. A missing directory counts as clean (nothing left to lose).
+ */
+function worktreeClean(path) {
+    if (!existsSync(path))
+        return true;
+    const run = spawnSync("git", ["status", "--porcelain", "--", ".", ":(exclude)dist", ":(exclude)screenshots"], { cwd: path, encoding: "utf8", timeout: 4000 });
+    if (run.status !== 0)
+        return false; // can't tell -> be conservative
+    return (run.stdout ?? "").trim() === "";
+}
+/** Resolve symlinks (macOS `/var` -> `/private/var`) so path containment checks line up. */
+function realpath(p) {
+    try {
+        return realpathSync(p);
+    }
+    catch {
+        return p;
+    }
+}
+function isInside(dir, candidate) {
+    const rel = relative(realpath(dir), realpath(candidate));
+    return rel !== "" && !rel.startsWith("..") && !isAbsolute(rel);
+}
+/**
+ * Sweep stale worktrees/branches. Synchronous and fail-soft — any git hiccup is
+ * recorded in `report.errors` and the sweep moves on.
+ */
+export function sweepStaleWorktrees(config, opts) {
+    const root = config.root;
+    const report = {
+        mode: opts.mode,
+        dryRun: !!opts.dryRun,
+        removedWorktrees: [],
+        removedBranches: [],
+        keptDirty: [],
+        prunedMetadata: false,
+        errors: [],
+    };
+    if (!isGitRepo(root)) {
+        report.errors.push("not a git repository");
+        return report;
+    }
+    const wtDir = worktreesDir(root);
+    const mainBranch = currentBranch(root) ?? "main";
+    const activeJobIds = opts.activeJobIds ?? new Set();
+    // branch -> task, for the "is this worktree still live" check (full mode only).
+    const taskByBranch = new Map();
+    if (opts.mode === "full") {
+        const tasks = opts.tasks ?? buildIndex(config).tasks;
+        for (const t of tasks) {
+            if (t.branch)
+                taskByBranch.set(t.branch, t);
+        }
+    }
+    const scoped = listWorktrees(root).filter((w) => !w.isMain && !w.isBare && isInside(wtDir, w.path));
+    const remove = (branch, path, forceBranch) => {
+        if (report.dryRun) {
+            report.removedWorktrees.push({ branch, path });
+            if (branch)
+                report.removedBranches.push(branch);
+            return;
+        }
+        if (!removeWorktree(root, branch || path)) {
+            report.errors.push(`could not remove worktree for ${branch || path}`);
+            return;
+        }
+        report.removedWorktrees.push({ branch, path });
+        if (branch && deleteBranch(root, branch, { force: forceBranch })) {
+            report.removedBranches.push(branch);
+        }
+        else if (branch) {
+            report.errors.push(`worktree gone but branch ${branch} not deleted`);
+        }
+    };
+    for (const w of scoped) {
+        const branch = w.branch ?? "";
+        // --- repoos/integrate/<id> candidates: throwaway, both modes ---
+        if (branch.startsWith(CANDIDATE_BRANCH_PREFIX)) {
+            const taskId = branch.slice(CANDIDATE_BRANCH_PREFIX.length);
+            if (activeJobIds.has(taskId)) {
+                report.keptDirty.push({ branch, path: w.path, reason: "close-out job still active" });
+                continue;
+            }
+            remove(branch, w.path, /* forceBranch */ true);
+            continue;
+        }
+        if (opts.mode === "integrate-only")
+            continue;
+        // --- feature worktrees ---
+        if (!branch) {
+            // Detached HEAD with no branch ref: only safe to drop when its directory
+            // is already gone (pure stale metadata).
+            if (!existsSync(w.path)) {
+                report.removedWorktrees.push({ branch: "", path: w.path });
+            }
+            else {
+                report.keptDirty.push({
+                    branch: "",
+                    path: w.path,
+                    reason: "detached worktree, directory present",
+                });
+            }
+            continue;
+        }
+        const task = taskByBranch.get(branch);
+        if (task && task.status !== "done")
+            continue; // live work — leave it
+        const merged = isAncestor(root, branch, mainBranch) === true;
+        const clean = worktreeClean(w.path);
+        if (merged && clean) {
+            remove(branch, w.path, /* forceBranch */ false);
+        }
+        else {
+            report.keptDirty.push({
+                branch,
+                path: w.path,
+                reason: !merged ? `commits not in ${mainBranch}` : "uncommitted changes",
+            });
+        }
+    }
+    // Clear metadata for any directory that is now (or was already) gone.
+    if (!report.dryRun) {
+        pruneWorktrees(root);
+        report.prunedMetadata = true;
+    }
+    return report;
+}
+/** Number of registered git worktrees, including the main checkout. */
+export function countWorktrees(root) {
+    return listWorktrees(root).length;
+}
+/**
+ * Run the conservative `integrate-only` sweep, then log its result and — when
+ * the surviving worktree count exceeds `threshold` (0 disables) — a
+ * "run `repoos gc`" warning. Shared by the boot path and every close-out.
+ * Fully fail-soft: a git hiccup is swallowed, never surfaced to the caller.
+ */
+export function sweepAndWarn(config, opts) {
+    try {
+        const report = sweepStaleWorktrees(config, {
+            mode: "integrate-only",
+            activeJobIds: opts.activeJobIds,
+        });
+        if (report.removedWorktrees.length || report.errors.length) {
+            opts.log("info", "worktree gc", {
+                removed: report.removedWorktrees.map((w) => w.branch || w.path),
+                errors: report.errors,
+            });
+        }
+        const threshold = opts.threshold ?? 20;
+        if (threshold > 0) {
+            const n = countWorktrees(config.root);
+            if (n > threshold) {
+                opts.log("warn", `${n} git worktrees registered (advisory ceiling ${threshold}) — run \`repoos gc\` to reclaim leftovers from done/abandoned tasks`, { worktrees: n, threshold });
+            }
+        }
+    }
+    catch (e) {
+        opts.log("warn", `worktree gc failed: ${e.message}`);
+    }
+}

package/dist/server/__tests__/integration-job.test.d.ts

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

package/dist/server/__tests__/integration-job.test.js

@@ -0,0 +1,129 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { execSync } from "node:child_process";
+import { createJobCoordinator } from "../integration-job.js";
+import { createRepositoryLock } from "../repo-lock.js";
+describe("integration jobs (0118)", () => {
+    let testRepo;
+    let testRepoGit;
+    beforeEach(() => {
+        // Create a temporary git repo for testing
+        testRepo = join(tmpdir(), `repoos-test-${Date.now()}`);
+        mkdirSync(testRepo, { recursive: true });
+        testRepoGit = `git -C ${testRepo}`;
+        // Initialize git repo
+        execSync(`${testRepoGit} init`, { stdio: "ignore" });
+        execSync(`${testRepoGit} config user.email "test@example.com"`, { stdio: "ignore" });
+        execSync(`${testRepoGit} config user.name "Test User"`, { stdio: "ignore" });
+        // Create an initial commit on main
+        writeFileSync(join(testRepo, "README.md"), "# Test Repo\n");
+        execSync(`${testRepoGit} add README.md`, { stdio: "ignore" });
+        execSync(`${testRepoGit} commit -m "Initial commit"`, { stdio: "ignore" });
+    });
+    afterEach(() => {
+        try {
+            rmSync(testRepo, { recursive: true, force: true });
+        }
+        catch {
+            /* ignore cleanup errors */
+        }
+    });
+    it("should enqueue jobs and maintain FIFO order", () => {
+        const coordinator = createJobCoordinator(testRepo);
+        // Enqueue two tasks
+        const job1 = coordinator.enqueue({ id: "task1", branch: "feat/task1" });
+        const job2 = coordinator.enqueue({ id: "task2", branch: "feat/task2" });
+        expect(job1).toBeDefined();
+        expect(job2).toBeDefined();
+        expect(job1.taskId).toBe("task1");
+        expect(job2.taskId).toBe("task2");
+        const all = coordinator.allJobs();
+        expect(all).toHaveLength(2);
+        expect(all[0].taskId).toBe("task1");
+        expect(all[1].taskId).toBe("task2");
+    });
+    it("should be idempotent: repeated enqueue returns existing job", () => {
+        const coordinator = createJobCoordinator(testRepo);
+        const job1 = coordinator.enqueue({ id: "task1", branch: "feat/task1" });
+        const job1Again = coordinator.enqueue({ id: "task1", branch: "feat/task1" });
+        expect(job1.enqueuedAt).toBe(job1Again.enqueuedAt);
+        expect(coordinator.allJobs()).toHaveLength(1);
+    });
+    it("should recover interrupted jobs on startup", () => {
+        const coordinator = createJobCoordinator(testRepo);
+        // Create a job in syncing phase
+        const job = coordinator.enqueue({ id: "task1", branch: "feat/task1" });
+        coordinator.updateJob("task1", { phase: "syncing", startedAt: new Date().toISOString() });
+        // Create a new coordinator (simulating restart)
+        const coordinator2 = createJobCoordinator(testRepo);
+        const interrupted = coordinator2.findInterruptedJobs();
+        expect(interrupted).toHaveLength(1);
+        expect(interrupted[0].taskId).toBe("task1");
+        expect(interrupted[0].phase).toBe("syncing");
+    });
+    it("should not recover done/failed jobs", () => {
+        const coordinator = createJobCoordinator(testRepo);
+        const job1 = coordinator.enqueue({ id: "task1", branch: "feat/task1" });
+        coordinator.updateJob("task1", { phase: "done" });
+        const job2 = coordinator.enqueue({ id: "task2", branch: "feat/task2" });
+        coordinator.updateJob("task2", { phase: "failed", reason: "test failure" });
+        const interrupted = coordinator.findInterruptedJobs();
+        expect(interrupted).toHaveLength(0);
+    });
+    it("should serialize repo lock across concurrent jobs", () => {
+        const lock = createRepositoryLock(testRepo);
+        // First job acquires lock
+        expect(lock.acquire("task1")).toBe(true);
+        expect(lock.isLocked()).toBe(true);
+        expect(lock.getHolder()).toBe("task1");
+        // Second job cannot acquire
+        expect(lock.acquire("task2")).toBe(false);
+        // First job releases
+        expect(lock.release("task1")).toBe(true);
+        expect(lock.isLocked()).toBe(false);
+        // Now second job can acquire
+        expect(lock.acquire("task2")).toBe(true);
+    });
+    it("should clean up stale locks after timeout", () => {
+        const lock = createRepositoryLock(testRepo);
+        // Write a stale lock file (>60 seconds old)
+        const lockPath = join(testRepo, ".repoos/close-out.lock");
+        const staleTime = new Date(Date.now() - 70_000); // 70 seconds ago
+        writeFileSync(lockPath, JSON.stringify({ taskId: "stale", acquiredAt: staleTime.toISOString() }));
+        // Should be able to acquire even though file exists (it's stale)
+        expect(lock.acquire("task1")).toBe(true);
+    });
+    it("should track baseMainSha and detect drift", () => {
+        const coordinator = createJobCoordinator(testRepo);
+        const job = coordinator.enqueue({ id: "task1", branch: "feat/task1" });
+        expect(job.baseMainSha).toBeNull();
+        // Simulate recording baseMainSha during validation
+        coordinator.updateJob("task1", {
+            phase: "validating",
+            baseMainSha: "abc123",
+        });
+        const updated = coordinator.getJob("task1");
+        expect(updated?.baseMainSha).toBe("abc123");
+    });
+    it("should persist and recover full job state", () => {
+        const coordinator = createJobCoordinator(testRepo);
+        const job = coordinator.enqueue({ id: "task1", branch: "feat/task1" });
+        coordinator.updateJob("task1", {
+            phase: "publishing",
+            startedAt: new Date().toISOString(),
+            baseMainSha: "main-sha-abc",
+            branchSha: "branch-sha-def",
+            candidateSha: "candidate-sha-ghi",
+        });
+        // Create new coordinator and verify state persisted
+        const coordinator2 = createJobCoordinator(testRepo);
+        const recovered = coordinator2.getJob("task1");
+        expect(recovered).toBeDefined();
+        expect(recovered?.phase).toBe("publishing");
+        expect(recovered?.baseMainSha).toBe("main-sha-abc");
+        expect(recovered?.branchSha).toBe("branch-sha-def");
+        expect(recovered?.candidateSha).toBe("candidate-sha-ghi");
+    });
+});