@repo-os/repoos 0.5.45

package/dist/server/repo-lock.js

@@ -0,0 +1,141 @@
+/**
+ * Repository-level locks for mutual exclusion on the main checkout.
+ *
+ * The close-out lock serializes publication to main, and the root lock
+ * additionally prevents a hotfix from running while a close-out holds the
+ * main checkout. Both locks share a single file to keep acquisition atomic.
+ */
+import { existsSync, writeFileSync, unlinkSync, mkdirSync, statSync, readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+const LOCK_FILE = ".repoos/close-out.lock";
+const ROOT_LOCK_FILE = ".repoos/root.lock";
+export function createRepositoryLock(root) {
+    return {
+        acquire(taskId) {
+            const lockPath = join(root, LOCK_FILE);
+            if (existsSync(lockPath)) {
+                try {
+                    const stat = statSync(lockPath);
+                    const age = Date.now() - stat.mtime.getTime();
+                    if (age > 60_000) {
+                        unlinkSync(lockPath);
+                    }
+                    else {
+                        return false;
+                    }
+                }
+                catch {
+                    return false;
+                }
+            }
+            try {
+                mkdirSync(dirname(lockPath), { recursive: true });
+                writeFileSync(lockPath, JSON.stringify({ taskId, acquiredAt: new Date().toISOString() }));
+                return true;
+            }
+            catch {
+                return false;
+            }
+        },
+        release(taskId) {
+            const lockPath = join(root, LOCK_FILE);
+            try {
+                if (existsSync(lockPath)) {
+                    const content = readFileSync(lockPath, "utf8");
+                    const lock = JSON.parse(content);
+                    if (lock.taskId === taskId) {
+                        unlinkSync(lockPath);
+                        return true;
+                    }
+                }
+            }
+            catch {
+                /* ignore */
+            }
+            return false;
+        },
+        isLocked() {
+            const lockPath = join(root, LOCK_FILE);
+            return existsSync(lockPath);
+        },
+        getHolder() {
+            const lockPath = join(root, LOCK_FILE);
+            try {
+                if (existsSync(lockPath)) {
+                    const content = readFileSync(lockPath, "utf8");
+                    const lock = JSON.parse(content);
+                    return lock.taskId || null;
+                }
+            }
+            catch {
+                /* ignore */
+            }
+            return null;
+        },
+    };
+}
+export function createRootLock(root) {
+    const lockPath = join(root, ROOT_LOCK_FILE);
+    return {
+        acquire(taskId, kind) {
+            if (existsSync(lockPath)) {
+                try {
+                    const stat = statSync(lockPath);
+                    const age = Date.now() - stat.mtime.getTime();
+                    // Hotfix holds last indefinitely (until finalization), so use a
+                    // longer stale window (10 min) to avoid crashing a live hotfix.
+                    if (age > 600_000) {
+                        unlinkSync(lockPath);
+                    }
+                    else {
+                        return false;
+                    }
+                }
+                catch {
+                    return false;
+                }
+            }
+            try {
+                mkdirSync(dirname(lockPath), { recursive: true });
+                writeFileSync(lockPath, JSON.stringify({ taskId, kind, acquiredAt: new Date().toISOString() }));
+                return true;
+            }
+            catch {
+                return false;
+            }
+        },
+        release(taskId) {
+            try {
+                if (existsSync(lockPath)) {
+                    const content = readFileSync(lockPath, "utf8");
+                    const lock = JSON.parse(content);
+                    if (lock.taskId === taskId) {
+                        unlinkSync(lockPath);
+                        return true;
+                    }
+                }
+            }
+            catch {
+                /* ignore */
+            }
+            return false;
+        },
+        isLocked() {
+            return existsSync(lockPath);
+        },
+        getHolder() {
+            try {
+                if (existsSync(lockPath)) {
+                    const content = readFileSync(lockPath, "utf8");
+                    const lock = JSON.parse(content);
+                    const kind = lock.kind === "hotfix" || lock.kind === "close-out" ? lock.kind : "close-out";
+                    return { taskId: lock.taskId, kind };
+                }
+            }
+            catch {
+                /* ignore */
+            }
+            return null;
+        },
+    };
+}

package/dist/server/review-guard.d.ts

@@ -0,0 +1,14 @@
+import type { RepoOSConfig, Task } from "../core/types.js";
+export interface ReviewGuardResult {
+    ok: boolean;
+    /** Human-readable failure reason when not ok. */
+    detail?: string;
+}
+/**
+ * Stage and commit the worktree's implementation changes (excluding generated
+ * artifacts and the task's own file), and reject a vacuous review transition.
+ * Mutates the worktree's git state: on success the branch carries the agent's
+ * work. Returns `ok: false` with a human-readable reason when the branch
+ * cannot be prepared or there is no source change without `no_source_change`.
+ */
+export declare function guardReviewTransition(config: RepoOSConfig, task: Task): Promise<ReviewGuardResult>;

package/dist/server/review-guard.js

@@ -0,0 +1,159 @@
+/**
+ * The commit+validate gate that every transition into `review` must pass.
+ *
+ * Originally handoff-finalization carried this logic privately; #0170 added
+ * the vacuous-handoff rejection and #0210 made it the single boundary for ALL
+ * paths into `review` — the trusted handoff signal, `PATCH /api/tasks/:id`,
+ * and a direct task-file edit picked up by the file watcher. This module is
+ * that shared gate.
+ *
+ * It enforces two guarantees before a task may land in `review`:
+ *   1. No uncommitted implementation changes are left behind — either they
+ *      are committed (excluding `dist`/`screenshots`/the task file itself) or
+ *      the transition is rejected.
+ *   2. A transition with zero source changes since the branch diverged from
+ *      main is rejected unless the task is marked `no_source_change: true`.
+ *
+ * The function is idempotent: calling it again after a successful commit (e.g.
+ * a PATCH route runs it, then the index's file-watch hook runs it again for
+ * the same transition) finds the work already committed and passes without
+ * re-committing or spuriously rejecting. Vacuity is therefore judged against
+ * the branch's divergence point (merge-base with main), not the staged diff.
+ */
+import { existsSync, realpathSync } from "node:fs";
+import { resolve } from "node:path";
+import { runGit, worktreePathForBranch, branchChangesSinceBase, currentBranch, agentTouchedFiles, } from "../core/git.js";
+function samePath(a, b) {
+    try {
+        return realpathSync(a) === realpathSync(b);
+    }
+    catch {
+        return resolve(a) === resolve(b);
+    }
+}
+/** True for generated/task-file paths that never count as "source changes". */
+function isGeneratedOrTask(path, taskPath) {
+    return (path === taskPath ||
+        path.startsWith("dist/") ||
+        path === "dist" ||
+        path.startsWith("screenshots/") ||
+        path === "screenshots");
+}
+/**
+ * Stage and commit the worktree's implementation changes (excluding generated
+ * artifacts and the task's own file), and reject a vacuous review transition.
+ * Mutates the worktree's git state: on success the branch carries the agent's
+ * work. Returns `ok: false` with a human-readable reason when the branch
+ * cannot be prepared or there is no source change without `no_source_change`.
+ */
+export async function guardReviewTransition(config, task) {
+    if (!task.branch) {
+        return { ok: false, detail: `task #${task.id} has no branch to finalize from` };
+    }
+    const registered = worktreePathForBranch(config.root, task.branch);
+    const isHotfix = task.hotfix === true;
+    if (!registered || (!isHotfix && samePath(registered, config.root)) || !existsSync(registered)) {
+        return {
+            ok: false,
+            detail: `task #${task.id} has no registered worktree for branch ${task.branch}`,
+        };
+    }
+    const clearIndex = await runGit(registered, 
+    // The guard owns the index for this commit. Clear any stale staging (for
+    // example a prior accidental `git add -f node_modules`) before selectively
+    // staging implementation changes below. This leaves working-tree edits
+    // untouched.
+    ["reset", "--quiet", "HEAD", "--", "."], 10_000);
+    if (clearIndex.status !== 0) {
+        return {
+            ok: false,
+            detail: `could not clear the staging index: ${concise(clearIndex)}`,
+        };
+    }
+    if (isHotfix) {
+        const touched = agentTouchedFiles(registered, "HEAD");
+        const sourceFiles = touched.filter((p) => !isGeneratedOrTask(p, task.path));
+        if (sourceFiles.length > 0) {
+            const add = await runGit(registered, ["add", "--", ...sourceFiles], 30_000);
+            if (add.status !== 0)
+                return { ok: false, detail: `git add failed: ${concise(add)}` };
+        }
+        const staged = await runGit(registered, ["diff", "--cached", "--quiet"], 10_000);
+        if (staged.status === 1) {
+            const commit = await runGit(registered, ["commit", "-m", `hotfix(${task.id}): ${task.title}`], 30_000);
+            if (commit.status !== 0)
+                return { ok: false, detail: `git commit failed: ${concise(commit)}` };
+        }
+        else if (staged.status !== 0) {
+            return { ok: false, detail: `could not inspect staged changes: ${concise(staged)}` };
+        }
+        return { ok: true };
+    }
+    const add = await runGit(registered, 
+    // `git add` honors .gitignore. Do not name ignored paths as exclusions:
+    // Git rejects those pathspecs even though they are exclusions.
+    ["add", "-A", "--", "."], 30_000);
+    if (add.status !== 0)
+        return { ok: false, detail: `git add failed: ${concise(add)}` };
+    // Remove generated and task metadata paths after staging. Unlike pathspec
+    // exclusions, `git reset` is safe whether these paths are ignored, tracked,
+    // or absent, and it preserves their working-tree contents.
+    const unstageGenerated = await runGit(registered, ["reset", "--quiet", "HEAD", "--", "dist", "screenshots", task.path], 10_000);
+    if (unstageGenerated.status !== 0) {
+        return {
+            ok: false,
+            detail: `could not unstage generated artifacts: ${concise(unstageGenerated)}`,
+        };
+    }
+    // Drop any OTHER task's work/*.md from this commit. A concurrent board write,
+    // a `repoos` CLI call, or a stale merge can leave a sibling task file dirty in
+    // the worktree, and the `git add -A` above folds it into this task's
+    // "implement" commit — which then publishes to main on close-out (observed:
+    // #0319 landed #0202/#0275 frontmatter drift). Only this task's own file
+    // (already unstaged above) is the handoff's to carry.
+    const stagedWorkFiles = (await runGit(registered, ["diff", "--cached", "--name-only", "--", config.workDir], 10_000)).stdout
+        .split("\n")
+        .map((s) => s.trim())
+        .filter((p) => p && p.endsWith(".md") && p !== task.path);
+    if (stagedWorkFiles.length > 0) {
+        const unstageForeign = await runGit(registered, ["reset", "--quiet", "HEAD", "--", ...stagedWorkFiles], 10_000);
+        if (unstageForeign.status !== 0) {
+            return {
+                ok: false,
+                detail: `could not unstage unrelated task files: ${concise(unstageForeign)}`,
+            };
+        }
+    }
+    const staged = await runGit(registered, ["diff", "--cached", "--quiet"], 10_000);
+    if (staged.status === 1) {
+        const commit = await runGit(registered, ["commit", "-m", `feat(${task.id}): implement ${task.title}`], 30_000);
+        if (commit.status !== 0)
+            return { ok: false, detail: `git commit failed: ${concise(commit)}` };
+    }
+    else if (staged.status !== 0) {
+        return { ok: false, detail: `could not inspect staged changes: ${concise(staged)}` };
+    }
+    // Judge vacuity against the branch's divergence point, so the guard is
+    // idempotent: work already committed (by a previous guard run, the handoff
+    // path, or the agent) keeps the transition valid. Only non-generated, non
+    // -task paths count as evidence of implementation.
+    const baseBranch = currentBranch(config.root) ?? "main";
+    const changes = branchChangesSinceBase(registered, baseBranch);
+    const realChange = changes.paths.some((p) => !isGeneratedOrTask(p, task.path));
+    if (!realChange && !task.noSourceChange) {
+        return {
+            ok: false,
+            detail: "no implementation found since the branch diverged; use no_source_change: true to force a no-op handoff",
+        };
+    }
+    return { ok: true };
+}
+function concise(run) {
+    return ([run.stdout, run.stderr]
+        .join("\n")
+        .split("\n")
+        .map((line) => line.trim())
+        .filter(Boolean)
+        .slice(-8)
+        .join(" · ") || `exit ${run.status}`);
+}

package/dist/server/review.d.ts

@@ -0,0 +1,243 @@
+import type { Agent, AgentOutputEntry, RepoOSConfig, Task } from "../core/types.js";
+import type { LiveIndex, RepoEvent } from "./live-index.js";
+import { type AgentRunner } from "./agents.js";
+/** A stored agent review, as served to the UI. */
+export interface ReviewReport {
+    /** Task id this report belongs to. */
+    id: string;
+    /** ISO timestamp the report was written. */
+    at: string;
+    /** Agent role name that produced it (normally "reviewer"). */
+    agent: string;
+    /** Coding-agent CLI and model behind that role. */
+    cli: string;
+    model: string;
+    /** Branch that was reviewed. */
+    branch: string;
+    /** "ok" when the agent reported; "failed" when the run itself failed. */
+    state: "ok" | "failed";
+    /** The report markdown (or the failure detail when state is "failed"). */
+    markdown: string;
+}
+export interface ReviewRunResult {
+    ok: boolean;
+    /** True when no review was attempted at all (agent disabled, no worktree). */
+    skipped?: boolean;
+    reason?: string;
+    report?: ReviewReport;
+}
+/**
+ * Prefix on the SSE event id used for a task's reviewer conversation. The
+ * engineer session streams under the plain task id; reviewer output streams
+ * under `review:<taskId>` so the two conversations can never mix on the wire
+ * or in the UI (0110).
+ */
+export declare const REVIEW_SESSION_ID_PREFIX = "review:";
+/**
+ * The mission handed to the review agent. Deliberately narrow: what to look
+ * at, what to write, and a hard boundary on what it may not touch.
+ */
+export declare function reviewMission(task: Task, agent: Agent, workdir: string, baseBranch: string): string;
+/**
+ * The mission handed to the review agent for a follow-up chat turn. The human
+ * asked a question about the review; the reviewer answers in the same read-only
+ * style, grounded in the task spec, its own previous report (when one exists),
+ * and the actual code. It still never touches the repo beyond reading.
+ */
+export declare function reviewFollowupMission(task: Task, agent: Agent, workdir: string, baseBranch: string, text: string, previousReport: ReviewReport | null): string;
+export declare class ReviewManager {
+    private readonly config;
+    private readonly emit;
+    private readonly runs;
+    /** Tasks the status guard just put back in `review`, by timestamp. */
+    private readonly reverted;
+    /** AgentRunner to send auto-bounce messages to the engineer session. */
+    private readonly runner?;
+    /**
+     * Reflects a trusted write straight into the index (see server.ts's other
+     * `applyFileChange(path, { guarded: true })` call sites). Without this the
+     * revert below is only ever seen by the async file watcher, which under
+     * load can fire the transition-into-review path twice for one write —
+     * `claimRevert` is single-use, so the second, spurious firing starts a
+     * second review the guard was supposed to prevent.
+     */
+    private readonly index?;
+    /**
+     * Own logger rather than a constructor param (0187 review): the only call
+     * site is `startServer`, and every review event is a task-lifecycle event —
+     * it belongs on the same per-task log stream `logger.task()` already
+     * writes to elsewhere, keyed by the same `config.root`.
+     */
+    private readonly logger;
+    /** Database for recording review sessions. */
+    private readonly db;
+    constructor(config: RepoOSConfig, emit: (e: RepoEvent) => void, runner?: AgentRunner, index?: LiveIndex);
+    /** Whether an enabled review agent exists — the Agents page toggle. */
+    enabled(): boolean;
+    isRunning(taskId: string): boolean;
+    /**
+     * How many reviews are in flight (the server's idle check).
+     *
+     * `this.runs` is the single source of truth for running reviews: fresh turns
+     * register in `run()`/`send()`, and adopted turns (re-attached after a reload)
+     * are registered by `armAdoptedTimeouts()` at boot. So counting `this.runs`
+     * already covers every in-flight review, including adopted ones — adding a
+     * separate count of `runner.running()` review sessions here would DOUBLE-count
+     * each adopted review (0288 review round 2).
+     */
+    runningCount(): number;
+    /**
+     * Claim the "this task is only back in `review` because the guard put it
+     * there" marker, if it is fresh. The revert lands on disk as an ordinary
+     * status change, so without this the trigger would start another review,
+     * whose agent would move it to done again, forever.
+     */
+    claimRevert(taskId: string): boolean;
+    /** Where a task's report lives. Derived cache — safe to delete. */
+    path(taskId: string): string;
+    /** The stored report for a task, or null when none was ever written. */
+    read(taskId: string): ReviewReport | null;
+    /**
+     * The synchronous gate both `run` and `send` share: is a review possible for
+     * this task right now? Resolved before firing the async spawn so an HTTP
+     * handler can answer "why not" without waiting for a prompt that will never
+     * start.
+     */
+    canRun(task: Task): {
+        ok: boolean;
+        reason?: string;
+    };
+    /**
+     * Same gate for a follow-up chat turn, which additionally needs a prior
+     * conversation (a review must have run at least once).
+     */
+    canSend(task: Task): {
+        ok: boolean;
+        reason?: string;
+    };
+    /**
+     * Run the review agent against a task sitting in `review`.
+     *
+     * Skips silently (no event, no file) when the review agent is disabled or
+     * the task has no worktree to inspect — "disabled means nothing happens" is
+     * the contract, not "something happens quietly and fails".
+     *
+     * A fresh run every time: the reviewer conversation is reset, so the run is
+     * a new assessment (the initial landing review, or a deliberate "Review
+     * again"), never a continuation of the prior one (0110).
+     */
+    run(task: Task): Promise<ReviewRunResult>;
+    /**
+     * Spawn (or re-start) a durable review turn in the AgentRunner and arm its
+     * hard timeout. Completion is event-driven: `AgentRunner` fires `onReviewDone`
+     * (0288), which lands in `handleReviewDone` — so a review that is in flight
+     * across a server reload is finalized by the NEW process's `ReviewManager`
+     * rather than dying with a `runPrompt` continuation.
+     */
+    private spawnDurable;
+    /**
+     * Re-arm the hard review timeout for durable review sessions re-attached
+     * from the previous server (0288). The spawning process's timer died with the
+     * reload, so without this an adopted review could hang forever. Also registers
+     * each adopted turn as a `Run` so cancellation and the run/chat mode keep
+     * working across the handoff. Called once at boot, after the runner has
+     * adopted still-alive review children.
+     */
+    armAdoptedTimeouts(): void;
+    /**
+     * Re-spawn reviews that a real (non-reload) server shutdown killed. On
+     * shutdown `handle.close()` runs `reviews.cancelAll()`, which SIGKILLs every
+     * in-flight review agent (unlike the engineer, which is left running and
+     * re-adopted by PID). The next boot's `adoptRunningAgents()` then finds
+     * nothing to re-attach, so the task sits in `review` forever with a stale or
+     * missing report. This closes that gap — the review equivalent of
+     * `recoverPendingHandoffs()`.
+     *
+     * A task is re-reviewed when it is in `review`, has a reviewer enabled and a
+     * worktree, is not already running/adopted, was not deliberately cancelled,
+     * AND its stored report is missing or older than the branch's HEAD commit
+     * (i.e. the engineer pushed a fix the report never saw). Runs are staggered
+     * so a batch doesn't spawn every reviewer at once.
+     *
+     * Must be called AFTER the index has populated — it reads `index.getTasks()`.
+     */
+    recoverInterruptedReviews(tasks: Task[]): void;
+    /** Durable review-turn completion hook (0288). */
+    handleReviewDone(sessionKey: string, exitedCleanly?: boolean, reviewKind?: "run" | "chat"): void;
+    /** Finalize a fresh review run from its durable session transcript. */
+    private finalizeRun;
+    /**
+     * Increment the `review_passes` frontmatter counter. Unlike `review_rounds`
+     * (which counts only auto-bounced rounds and caps at MAX_AUTO_REVIEW_ROUNDS),
+     * this counts every completed review pass — auto and manual ("Review again")
+     * alike — so the UI badge (`D# · R#`) matches the true number of review
+     * sessions.
+     *
+     * The write also bumps `updated_at` (a field the live index's `diff()`
+     * watches, since it omits `extra`) and commits the file, so the drawer's
+     * badge refreshes live and `main` stays clean/mergeable. Best-effort, never
+     * fails.
+     */
+    private bumpReviewPasses;
+    /** Record a review session to the database. Best-effort, never fails. */
+    private recordReviewSession;
+    /**
+     * Send a follow-up chat turn to the reviewer. The human's message joins the
+     * reviewer conversation (never the engineer session), and the reviewer's
+     * answer streams into the same conversation. Chat turns do not overwrite the
+     * stored report — the verdict callout keeps describing the last full review.
+     */
+    send(task: Task, text: string): Promise<ReviewRunResult>;
+    /** Finalize a follow-up chat turn from its durable session transcript. */
+    private finalizeChat;
+    /** Record a review chat turn to the database. Best-effort, never fails. */
+    private recordReviewChatTurn;
+    /** The retained reviewer conversation for a task, or [] when none exists. */
+    session(taskId: string): AgentOutputEntry[];
+    /**
+     * Abandon a task's review: kill the child if one is running and mark the run
+     * cancelled so it writes nothing. Called when the task leaves `review` by a
+     * human route (the close-out, a status change from the API), where both the
+     * report and the status guard have stopped being relevant — and where the
+     * worktree is about to be removed out from under the child.
+     */
+    cancel(taskId: string): void;
+    /** Cancel every in-flight review (server shutdown). */
+    cancelAll(): void;
+    private cancelledFilePath;
+    private readCancelled;
+    private writeCancelled;
+    private isCancelled;
+    private markCancelled;
+    private clearCancelled;
+    /**
+     * Auto-bounce logic: if the verdict is "needs some work" or "back to the
+     * drawing board" and we haven't exceeded the max rounds, send the findings
+     * back to the engineer session and increment the review_rounds counter.
+     */
+    private autoBounce;
+    /** The runner session key (== SSE event id) for a task's reviewer chat. */
+    private reviewKey;
+    /** Whether a review conversation exists for the task (memory or persisted). */
+    private hasSession;
+    /** Drop the task's durable conversation, in memory and on disk. */
+    private resetReviewSession;
+    /**
+     * Emit the human's follow-up text under the review session id. The durable
+     * transcript records it too (via the runner session's `humanEntry`), and the
+     * live SSE stream is emitted here because the runner does not surface a
+     * seeded human entry on spawn.
+     */
+    private emitHumanEntry;
+    /** Append a trusted system marker into the durable review transcript. */
+    private appendMarker;
+    /** Persist a report, creating `<cacheDir>/reviews/` on first use. */
+    private write;
+    /**
+     * Defense in depth for the one thing the review agent must never do. If the
+     * task file says `done` when the review ends, the reviewer moved it there:
+     * every human route out of `review` cancels the run first, so a live run can
+     * only be looking at a task a human has not touched. Put it back and say so.
+     */
+    private enforceStillInReview;
+}