@repo-os/repoos 0.5.45

package/dist/server/task-transitions.js

@@ -0,0 +1,78 @@
+/** The full 12-edge allow-list. Absence of a `(from, to)` pair here means the
+ *  transition is rejected, from every caller, with no exceptions. */
+export const TRANSITIONS = {
+    draft: {
+        inbox: { effect: "none", via: "generic-patch" },
+    },
+    inbox: {
+        draft: { effect: "none", via: "generic-patch" },
+        ready: { effect: "none", via: "generic-patch" },
+    },
+    ready: {
+        inbox: { effect: "none", via: "generic-patch" },
+        active: {
+            effect: "provision branch/worktree if new; clear needsInput; spawn agent",
+            via: "action:start",
+        },
+    },
+    active: {
+        active: { effect: "resume agent on existing worktree", via: "action:start" },
+        review: {
+            effect: "commit + validate diff; auto-sync branch; kick off automatic review",
+            via: "generic-patch",
+        },
+        ready: { effect: "stop agent if running; worktree kept, not deleted", via: "action:abandon" },
+    },
+    review: {
+        active: {
+            effect: "resume engineer with reviewer feedback as instruction",
+            via: "generic-patch",
+        },
+        done: {
+            effect: "close-out job: merge, build, check, cleanup worktree+branch",
+            via: "action:done",
+        },
+        ready: { effect: "cancel running review; worktree kept, not deleted", via: "action:abandon" },
+    },
+    done: {
+        ready: {
+            effect: "clear stale branch reference + needsInput; re-provisioning happens on the next Start",
+            via: "action:reopen",
+        },
+    },
+};
+/** Edges the generic write path (PATCH /api/tasks/:id, and therefore the task
+ *  drawer's status dropdown and board drag-drop) may perform directly. Every
+ *  other edge above requires its dedicated action endpoint. */
+const GENERIC_PATCH_EDGES = new Set(Object.entries(TRANSITIONS).flatMap(([from, tos]) => Object.entries(tos ?? {})
+    .filter(([, edge]) => edge.via === "generic-patch")
+    .map(([to]) => `${from}->${to}`)));
+/** Where a rejected target status should actually be requested, for a useful error message. */
+const SUGGESTED_ACTION = {
+    active: "POST /api/tasks/:id/start",
+    done: "POST /api/tasks/:id/done",
+};
+/**
+ * Whether a bare status write (no accompanying action) from `from` to `to`
+ * is allowed. `from === to` is always fine (no-op). Returns a reason and a
+ * pointer to the right endpoint when rejected.
+ */
+export function checkGenericStatusPatch(from, to) {
+    if (from === to)
+        return { ok: true };
+    const edge = TRANSITIONS[from]?.[to];
+    if (!edge) {
+        return {
+            ok: false,
+            reason: `cannot move a task from "${from}" directly to "${to}" — no such transition exists`,
+        };
+    }
+    if (edge.via !== "generic-patch") {
+        const suggestion = SUGGESTED_ACTION[to];
+        return {
+            ok: false,
+            reason: `"${from}" → "${to}" requires ${suggestion ?? `the ${edge.via.replace("action:", "")} action`}, not a direct status write`,
+        };
+    }
+    return { ok: true };
+}

package/dist/server/task-watchdog.d.ts

@@ -0,0 +1,158 @@
+import type { RepoOSConfig, Task } from "../core/types.js";
+import type { LiveIndex } from "./live-index.js";
+import type { AgentRunner } from "./agents.js";
+import type { ReviewReport, ReviewRunResult } from "./review.js";
+/** Why a dead/stalled active task's agent session stopped. */
+export type DeadAgentReason = "never-started" | "crashed" | "exited-without-handoff";
+/** The dead-session classification plus the exact transcript reason string. */
+export interface DeadAgentClassification {
+    kind: DeadAgentReason;
+    reason: string;
+}
+/**
+ * Best-effort next-step suggestion for an escalation note, matched from the
+ * captured failure reason. A generic fallback beats a wrong diagnosis.
+ */
+export declare function suggestNextStep(reason: string): string;
+/**
+ * Pure stuck-detection over a task's Activity log. True when the log has a
+ * `status →active` transition and no Activity entry after it for at least
+ * `stalenessMs` (a task with zero entries after going active is the purest
+ * stuck shape — its clock runs from the transition itself).
+ */
+export declare function isStuckActiveTask(body: string, stalenessMs: number, now: number): boolean;
+/**
+ * Pure stuck-detection over a task's Activity log for the `review` status.
+ * Mirrors `isStuckActiveTask` but bounds the episode by the most recent
+ * `status →review` transition: a review task is candidate-stuck when no
+ * Activity entry after it (or none at all) exists for at least `stalenessMs`.
+ *
+ * This is deliberately only the Activity-log staleness half of the decision.
+ * The "the review actually completed" half (a report file exists) and the
+ * "a review is genuinely in flight" half live in `isStuck`, because they need
+ * the `ReviewManager` and filesystem, not just the body string.
+ */
+export declare function isStuckReviewTask(body: string, stalenessMs: number, now: number): boolean;
+/**
+ * True when a task's worktree has a file modified within `stalenessMs` of
+ * `now` — evidence of a genuinely live agent independent of the in-memory
+ * runner registry.
+ *
+ * The registry (`AgentRunner.isRunning`) is a plain in-memory Map: it goes
+ * empty on every server restart, with no record of which PID belonged to
+ * which task (#0214). During this repo's own reload-churn-heavy sessions that
+ * makes `isRunning()` report false for a still-working agent constantly, not
+ * as a rare edge case — the exact false-positive #0203 was filed against
+ * ("the agent was never dead: it kept running... and kept writing source
+ * files"). The registry cannot be trusted alone; the worktree's own file
+ * mtimes are a signal that survives a restart because they live on disk, not
+ * in server memory.
+ */
+export declare function hasRecentWorktreeActivity(root: string, branch: string | undefined, stalenessMs: number, now: number): boolean;
+/**
+ * Classify why an active task's agent session is dead. The `task` is the
+ * freshly-parsed on-disk Task (its Activity log may carry a persisted
+ * `handoff failed · …` entry); `runner.output(id)` reveals whether the task
+ * ever had a session (in-memory or persisted) at all.
+ */
+export declare function classifyDeadAgentReason(task: Task, runner: AgentRunner): DeadAgentClassification;
+/**
+ * Where a stuck task lands when surfaced: `review` whenever its worktree holds
+ * any work (committed branch commits OR uncommitted changes — either way it is
+ * reviewable, and moving it to `ready` could discard it on a clean restart),
+ * else `ready` to go back in the pile. Without a branch/worktree there is no
+ * work to look at, so `ready`.
+ */
+export declare function autoTransitionTarget(config: RepoOSConfig, task: Task): "ready" | "review";
+export interface TaskWatchdogOptions {
+    /**
+     * Observed each scan; when it returns false the scan is skipped entirely.
+     * The server uses this to make the watchdog never fire mid-reload (#0180).
+     */
+    canRun?: () => boolean;
+    /**
+     * When true (default), a stuck task is auto-transitioned to a visible state
+     * (`review`/`ready`). When false, the #0156 fallback applies instead: the
+     * task is escalated to `needsInput` and left `active`.
+     */
+    autoTransition?: boolean;
+    /**
+     * The review manager surface, when the watchdog should also recover dead
+     * REVIEWER sessions (#0286). Without it (or when a report already exists),
+     * review tasks are left alone entirely — the review is either complete or
+     * out of scope for this watchdog.
+     */
+    reviews?: WatchdogReviewManager;
+}
+/**
+ * The minimal `ReviewManager` surface the watchdog's reviewer-recovery path
+ * depends on. Kept structural (not the concrete class) so the watchdog only
+ * couples to what it acts on and tests can substitute a fake.
+ */
+export interface WatchdogReviewManager {
+    /** Whether a reviewer run is currently in flight for the task. */
+    isRunning(taskId: string): boolean;
+    /** The stored review report for the task, or null when none ever completed. */
+    read(taskId: string): ReviewReport | null;
+    /** Kick off a fresh review run (the same action the human's "Review again" does). */
+    run(task: Task): Promise<ReviewRunResult>;
+}
+export declare class TaskWatchdog {
+    private config;
+    private index;
+    private runner;
+    private readonly autoTransition;
+    private readonly canRun?;
+    private readonly reviews?;
+    private timer;
+    private stalenessThresholdMs;
+    /** Re-entry guard: a scan already in flight is skipped by the next tick. */
+    private scanning;
+    constructor(config: RepoOSConfig, index: LiveIndex, runner: AgentRunner, stalenessThresholdMs?: number, opts?: TaskWatchdogOptions);
+    start(): void;
+    stop(): void;
+    /** Run one full scan now (used by the timer and by tests). */
+    checkNow(): Promise<void>;
+    private isStuck;
+    /**
+     * The `review`-status half of stuck detection. A review task is stuck when
+     * its reviewer session ended without ever producing a report for THIS round
+     * and no review is in flight — the silent-death shape (#0286). A report that
+     * EXISTS for the current episode (written after the current `→review`
+     * transition) means the review already completed and surfaced itself, so it
+     * is not stuck even if it "failed"; only a round that produced nothing at all
+     * needs the watchdog.
+     */
+    private isStuckReview;
+    private handleStuck;
+    /**
+     * Recover a task whose REVIEWER session died silently mid-review (#0286).
+     *
+     * Unlike the `active` path (which resumes/restarts the ENGINEER), a dead
+     * reviewer is recovered by kicking off a FRESH reviewer run — the same
+     * action the human takes manually via "Review again". It never touches
+     * engineer state: the task stays in `review` for a human to sign off.
+     *
+     * Bounded the same way the `active` path is bounded: one automatic retry per
+     * review episode (persisted Activity marker, scoped to the current
+     * `→review` transition). If the retry is exhausted and the task is still
+     * stuck — no report, no running review — it is escalated to `needsInput`
+     * for a human instead of looping forever on a genuinely broken reviewer.
+     */
+    private handleStuckReview;
+    /**
+     * Move a stuck task out of the silent `active` state: write the status +
+     * reason in one Activity entry, then commit so main stays mergeable and the
+     * indexing write surfaces the change to the board + ntfy notification.
+     */
+    private surfaceTask;
+    /**
+     * Escalate a stuck task (#0156 fallback): set `needsInput: true` (which
+     * surfaces on the board and fires the existing `notifyNeedsInput`
+     * notification) and append an Activity entry with the failure reason and a
+     * suggested next step. The task stays `active` — visible, not silent.
+     */
+    private escalateToNeedsInput;
+    private readCurrent;
+    private writeTask;
+}