@repo-os/repoos 0.5.45

package/dist/server/supervisor.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Agent Supervisor: periodic reconciliation of active tasks against runner state,
+ * worktree progress, and process health. Emits heartbeat reports to the Control page.
+ *
+ * Responsibilities:
+ * - Classify tasks into health states (healthy, quiet-but-alive, stalled, orphaned, etc.)
+ * - Detect low-progress loops and resource constraints
+ * - Invoke diagnostic AI for ambiguous cases (bounded and rate-limited)
+ * - Apply safe recovery actions only within configured policy
+ * - Persist audit log in cache directory
+ * - Emit SSE events and UI feedback
+ */
+import type { RepoOSConfig, SupervisorConfig, TaskHealthStatus } from "../core/types.js";
+import type { RepoEvent } from "./live-index.js";
+import type { LiveIndex } from "./live-index.js";
+/** Default supervisor configuration. */
+export declare const DEFAULT_SUPERVISOR_CONFIG: SupervisorConfig;
+/** Validated and normalized supervisor configuration. */
+export declare class SupervisorConfig_ {
+    readonly enabled: boolean;
+    readonly interval: number;
+    readonly mode: "observe" | "recover";
+    readonly quietThreshold: number;
+    readonly stallThreshold: number;
+    readonly maxRestarts: number;
+    readonly cooldownSeconds: number;
+    readonly diagnosticAgent: string | null;
+    readonly fallbacks: Array<{
+        agent?: string;
+        model?: string;
+    }>;
+    constructor(cfg?: SupervisorConfig);
+}
+/** Task health state with evidence. */
+export interface TaskHealthReport {
+    id: string;
+    title: string;
+    status: TaskHealthStatus;
+    evidence: string[];
+    lastOutput?: string;
+    action?: string;
+    warning?: string;
+}
+/** Supervisor cycle result. */
+export interface SupervisorCycleResult {
+    id: string;
+    startedAt: string;
+    completedAt: string;
+    nextCheckAt: string;
+    mode: "observe" | "recover";
+    totalActive: number;
+    healthy: number;
+    warnings: number;
+    tasks: TaskHealthReport[];
+}
+/** The agent supervisor. */
+export declare class AgentSupervisor {
+    readonly config: SupervisorConfig_;
+    private repoosCfg;
+    private index;
+    private emitEvent;
+    private timer;
+    private running;
+    private lastCycleId;
+    private auditLog;
+    /** Own logger, same pattern as ReviewManager (0187): the supervisor was the
+     *  one agent in the system with no logging at all — its JSON audit log in
+     *  the cache dir is a separate, UI-facing thing, not the NDJSON pipeline. */
+    private readonly logger;
+    constructor(cfg: RepoOSConfig, index: LiveIndex, emitEvent: (e: RepoEvent) => void);
+    /** Start the supervisor loop. */
+    start(): void;
+    /** Stop the supervisor loop. */
+    stop(): void;
+    /** Run one supervision cycle immediately. */
+    runCycle(): Promise<SupervisorCycleResult | null>;
+    private executeCycle;
+    /** Classify a task's health status. */
+    private classifyTask;
+    /** Get the most recent heartbeat. */
+    getLatestHeartbeat(): SupervisorCycleResult | null;
+    /** Get recent heartbeats. */
+    getRecentHeartbeats(limit?: number): SupervisorCycleResult[];
+    private emitHeartbeat;
+    private loadAuditLog;
+    private saveAuditLog;
+    private trimAuditLog;
+    private auditLogPath;
+}

package/dist/server/supervisor.js

@@ -0,0 +1,231 @@
+/**
+ * Agent Supervisor: periodic reconciliation of active tasks against runner state,
+ * worktree progress, and process health. Emits heartbeat reports to the Control page.
+ *
+ * Responsibilities:
+ * - Classify tasks into health states (healthy, quiet-but-alive, stalled, orphaned, etc.)
+ * - Detect low-progress loops and resource constraints
+ * - Invoke diagnostic AI for ambiguous cases (bounded and rate-limited)
+ * - Apply safe recovery actions only within configured policy
+ * - Persist audit log in cache directory
+ * - Emit SSE events and UI feedback
+ */
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { createLogger } from "../core/logger.js";
+/** Default supervisor configuration. */
+export const DEFAULT_SUPERVISOR_CONFIG = {
+    enabled: false,
+    interval: 300,
+    mode: "observe",
+    quietThreshold: 600,
+    stallThreshold: 3,
+    maxRestarts: 2,
+    cooldownSeconds: 60,
+};
+/** Validated and normalized supervisor configuration. */
+export class SupervisorConfig_ {
+    enabled;
+    interval;
+    mode;
+    quietThreshold;
+    stallThreshold;
+    maxRestarts;
+    cooldownSeconds;
+    diagnosticAgent;
+    fallbacks;
+    constructor(cfg) {
+        const defaults = DEFAULT_SUPERVISOR_CONFIG;
+        this.enabled = cfg?.enabled ?? defaults.enabled ?? false;
+        this.interval = Math.max(60, cfg?.interval ?? defaults.interval ?? 300);
+        this.mode = cfg?.mode ?? defaults.mode ?? "observe";
+        this.quietThreshold = Math.max(60, cfg?.quietThreshold ?? defaults.quietThreshold ?? 600);
+        this.stallThreshold = Math.max(1, cfg?.stallThreshold ?? defaults.stallThreshold ?? 3);
+        this.maxRestarts = Math.max(0, cfg?.maxRestarts ?? defaults.maxRestarts ?? 2);
+        this.cooldownSeconds = Math.max(30, cfg?.cooldownSeconds ?? defaults.cooldownSeconds ?? 60);
+        this.diagnosticAgent = cfg?.diagnosticAgent ?? null;
+        this.fallbacks = cfg?.fallbacks ?? [];
+    }
+}
+/** The agent supervisor. */
+export class AgentSupervisor {
+    config;
+    repoosCfg;
+    index;
+    emitEvent;
+    timer = null;
+    running = false;
+    lastCycleId = 0;
+    auditLog = [];
+    /** Own logger, same pattern as ReviewManager (0187): the supervisor was the
+     *  one agent in the system with no logging at all — its JSON audit log in
+     *  the cache dir is a separate, UI-facing thing, not the NDJSON pipeline. */
+    logger;
+    constructor(cfg, index, emitEvent) {
+        this.repoosCfg = cfg;
+        this.config = new SupervisorConfig_(cfg.supervisor);
+        this.index = index;
+        this.emitEvent = emitEvent;
+        this.logger = createLogger(cfg.root);
+        this.loadAuditLog();
+    }
+    /** Start the supervisor loop. */
+    start() {
+        if (!this.config.enabled || this.timer !== null)
+            return;
+        this.timer = setInterval(() => this.runCycle(), this.config.interval * 1000);
+        void this.runCycle();
+    }
+    /** Stop the supervisor loop. */
+    stop() {
+        if (this.timer !== null) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+    }
+    /** Run one supervision cycle immediately. */
+    async runCycle() {
+        if (this.running)
+            return null;
+        this.running = true;
+        try {
+            return await this.executeCycle();
+        }
+        finally {
+            this.running = false;
+        }
+    }
+    async executeCycle() {
+        const cycleId = `cycle-${++this.lastCycleId}`;
+        const startedAt = new Date().toISOString();
+        const tasks = this.index.getTasks().filter((t) => t.status === "active");
+        const reports = [];
+        for (const task of tasks) {
+            const report = this.classifyTask(task);
+            reports.push(report);
+        }
+        const completedAt = new Date().toISOString();
+        const nextCheckAt = new Date(Date.now() + this.config.interval * 1000).toISOString();
+        const healthy = reports.filter((r) => r.status === "healthy").length;
+        const warnings = reports.filter((r) => r.warning || r.action).length;
+        const result = {
+            id: cycleId,
+            startedAt,
+            completedAt,
+            nextCheckAt,
+            mode: this.config.mode,
+            totalActive: tasks.length,
+            healthy,
+            warnings,
+            tasks: reports,
+        };
+        this.auditLog.push(result);
+        this.trimAuditLog();
+        this.saveAuditLog();
+        this.logger.agent("supervisor", warnings > 0 ? "warn" : "info", "supervision cycle complete", {
+            cycleId,
+            mode: result.mode,
+            totalActive: result.totalActive,
+            healthy,
+            warnings,
+            flagged: reports
+                .filter((r) => r.warning || r.action)
+                .map((r) => ({ id: r.id, status: r.status, warning: r.warning, action: r.action })),
+        });
+        this.emitHeartbeat(result);
+        return result;
+    }
+    /** Classify a task's health status. */
+    classifyTask(task) {
+        const evidence = [];
+        if (task.needsInput) {
+            return {
+                id: task.id,
+                title: task.title,
+                status: "waiting-for-human",
+                evidence: ["Task flagged needs_input; awaiting human decision."],
+                warning: "Waiting for human action",
+            };
+        }
+        if (task.needsMerge) {
+            return {
+                id: task.id,
+                title: task.title,
+                status: "blocked-on-merge",
+                evidence: ["Task branch has drifted from main; needs manual merge."],
+                warning: "Branch needs merge",
+            };
+        }
+        return {
+            id: task.id,
+            title: task.title,
+            status: "healthy",
+            evidence: ["Task is active with no known issues."],
+        };
+    }
+    /** Get the most recent heartbeat. */
+    getLatestHeartbeat() {
+        return this.auditLog[this.auditLog.length - 1] ?? null;
+    }
+    /** Get recent heartbeats. */
+    getRecentHeartbeats(limit = 10) {
+        return this.auditLog.slice(-limit);
+    }
+    emitHeartbeat(result) {
+        const heartbeat = {
+            id: result.id,
+            startedAt: result.startedAt,
+            completedAt: result.completedAt,
+            nextCheckAt: result.nextCheckAt,
+            mode: result.mode,
+            totalActive: result.totalActive,
+            healthy: result.healthy,
+            warnings: result.warnings,
+            tasks: result.tasks.map((t) => ({
+                id: t.id,
+                title: t.title,
+                status: t.status,
+                lastOutput: t.lastOutput,
+                evidence: t.evidence.join(" "),
+                action: t.action || t.warning,
+            })),
+        };
+        this.emitEvent({
+            type: "supervisor.heartbeat",
+            heartbeat,
+            at: new Date().toISOString(),
+        });
+    }
+    loadAuditLog() {
+        try {
+            const logPath = this.auditLogPath();
+            if (!existsSync(logPath)) {
+                this.auditLog = [];
+                return;
+            }
+            const data = JSON.parse(readFileSync(logPath, "utf8"));
+            this.auditLog = Array.isArray(data) ? data : [];
+        }
+        catch {
+            this.auditLog = [];
+        }
+    }
+    saveAuditLog() {
+        try {
+            const logPath = this.auditLogPath();
+            mkdirSync(this.repoosCfg.cacheDir, { recursive: true });
+            writeFileSync(logPath, JSON.stringify(this.auditLog, null, 2), "utf8");
+        }
+        catch {
+            /* fail soft */
+        }
+    }
+    trimAuditLog() {
+        if (this.auditLog.length > 100) {
+            this.auditLog = this.auditLog.slice(-50);
+        }
+    }
+    auditLogPath() {
+        return join(this.repoosCfg.root, this.repoosCfg.cacheDir, "supervisor-audit.json");
+    }
+}

package/dist/server/system.d.ts

@@ -0,0 +1,198 @@
+import type { RunningAgentInfo } from "./agents.js";
+export interface MachineInfo {
+    cpuCount: number;
+    totalMem: number;
+    /** Truly-free pages only (`os.freemem()`). On macOS this is always tiny — the
+     *  OS parks everything it can in cache — so it is a poor "headroom" signal. */
+    freeMem: number;
+    /** Memory the OS can hand back on demand without swapping: free + inactive +
+     *  speculative + purgeable (macOS) or `MemAvailable` (Linux). Falls back to
+     *  `freeMem` on other platforms or if the probe fails. This is the number to
+     *  reason about for "is there room to run a build". */
+    availableMem: number;
+    loadavg: number[];
+    platform: string;
+}
+export interface ProcessInfo {
+    pid: number;
+    taskId: string | null;
+    cpuPercent: number;
+    memBytes: number;
+    elapsed: string;
+    orphaned: boolean;
+    /** True when attributed by command-name match only, not by registry. */
+    unverified: boolean;
+}
+/** A live `repoos serve` process found on the machine. */
+export interface ServeProcessInfo {
+    pid: number;
+    ppid: number;
+    port: number | null;
+    /** Repo root the process is serving, parsed from its argv. */
+    root: string | null;
+    /** False when the root directory is gone — the process is definitively garbage. */
+    rootExists: boolean;
+    /**
+     * `in-flight` is the one that stops this from crying wolf: the close-out
+     * gate's own test suite spawns fixture servers constantly, and while their
+     * spawning process is still alive they are doing legitimate work. Only a
+     * process whose parent has died (reparented to PID 1) is abandoned.
+     *
+     * `foreign` is a detached serve process for a DIFFERENT, still-present repo
+     * root — another repo's control plane started via `just serve` / `nohup`
+     * (so its ppid is also 1). It is not this server's to reap; never SIGTERMed,
+     * never counted as an abandoned stray.
+     */
+    kind: "control-plane" | "known-preview" | "in-flight" | "stray" | "foreign";
+}
+/**
+ * Machine-wide census of `repoos serve` processes (#0216). Preview and fixture
+ * servers that outlive their owning task or test accumulate silently, and the
+ * load they generate makes the close-out gate fail on timing-sensitive tests
+ * that pass fine in isolation — a false failure that is indistinguishable from
+ * a real regression. Surfacing the count makes the accumulation visible before
+ * it starts costing close-outs.
+ */
+export interface ServeScan {
+    total: number;
+    /** Abandoned: unattributable AND the spawning process is gone. */
+    strays: number;
+    /** Unattributable but still supervised by a live parent — a running test or gate. */
+    inFlight: number;
+    /** Strays whose root directory no longer exists. */
+    deadRoot: number;
+    level: "ok" | "notice" | "warn";
+    processes: ServeProcessInfo[];
+}
+/**
+ * Cheap "size of the codebase" facts for the Control page. Derived from git, so
+ * gitignored files (dist/, node_modules/, screenshots/) are excluded for free.
+ * Sampled behind a TTL cache — the numbers barely move between 5s polls.
+ */
+export interface RepoStats {
+    /** Registered git worktrees, including the main checkout. */
+    worktrees: number;
+    /** Files tracked by git on the checked-out branch. */
+    trackedFiles: number;
+    /** Total lines across tracked text files (binary files skipped). */
+    linesOfCode: number;
+    /**
+     * Advisory ceiling from config (`worktreeWarnThreshold`, default 20). The UI
+     * turns the worktree count amber when `worktrees` exceeds this. 0 disables.
+     */
+    worktreeWarnThreshold: number;
+}
+export interface SystemStats {
+    machine: MachineInfo;
+    totals: {
+        cpuPercent: number;
+        memBytes: number;
+        memPercent: number;
+    };
+    processes: ProcessInfo[];
+    serve: ServeScan | null;
+    /** Codebase size facts, or null when the root is not a git repo / git is missing. */
+    repo: RepoStats | null;
+    serverPid: number;
+    at: string;
+}
+interface PsRecord {
+    pid: number;
+    ppid: number;
+    cpuPercent: number;
+    memPercent: number;
+    rssKB: number;
+    elapsed: string;
+}
+export interface OwnershipRecord {
+    pid: number;
+    taskId: string;
+    startedAt: string;
+    executable: string;
+    workdir: string;
+}
+/**
+ * Parse `ps -o pid=,ppid=,%cpu=,%mem=,rss=,etime=` output into records.
+ * One `ps` call covers all PIDs at once. Export for testing.
+ */
+export declare function parsePsOutput(output: string): PsRecord[];
+/**
+ * git-derived codebase size: worktree count, tracked-file count, and total
+ * lines across tracked text files. Three `git` spawns, so memoised for 30s —
+ * the SSE loop calls this every 5s and these numbers change on the order of
+ * commits, not seconds. Returns the last good value (or null) on git failure.
+ */
+export declare function sampleRepoStats(root: string, worktreeWarnThreshold?: number): RepoStats | null;
+/** Extract the repo root a serve process is running from, or null. */
+export declare function parseServeRoot(command: string): string | null;
+/** Extract `--port N` from a serve command line, or null. */
+export declare function parseServePort(command: string): number | null;
+/**
+ * Parse `ps ax -o pid=,ppid=,command=` output into serve-process records.
+ *
+ * Classification order matters. The control plane is checked first because the
+ * reload handoff deliberately detaches it, so it also runs with `ppid` 1 and
+ * would otherwise look abandoned. Everything else that RepoOS did not start is
+ * abandoned only if its parent is gone — a fixture server with a live vitest
+ * worker above it is the gate doing its job, not a leak.
+ *
+ * Exported for testing so classification can be exercised without spawning servers.
+ */
+export declare function parseServeScan(output: string, serverPid: number, knownPids: Set<number>, rootExists: (root: string | null) => boolean, ownRoot?: string): ServeScan;
+/**
+ * Census live `repoos serve` processes. Cached — `ps ax` lists every process on
+ * the machine, which is much heavier than the targeted per-PID sample.
+ */
+export declare function scanServeProcesses(serverPid: number, knownPids: Set<number>, ownRoot?: string): ServeScan | null;
+/** Drop the cached census. Exported for tests. */
+export declare function resetServeScanCache(): void;
+/**
+ * Reap every `stray` process the census finds — a process whose spawning
+ * parent is confirmed dead (reparented to PID 1). This is safe by
+ * construction: `in-flight` processes (a live parent still supervising them,
+ * e.g. the close-out gate's own test suite mid-run) are never included, and
+ * neither is the control plane or a known preview. Killing a stray destroys
+ * no live work — nothing will ever come back to claim it.
+ *
+ * Root cause this offsets (#0216): a failed reload-replacement handoff kills
+ * only the direct child process (`ReloadManager.killChild`, plain SIGTERM,
+ * not a process-group kill), so anything that child spawned before failing
+ * its readiness check survives as an orphan. Under repeated failed reload
+ * attempts this accumulates fast enough to strain the whole machine, not just
+ * starve the close-out gate. This periodic sweep is the general safety net;
+ * the process-group fix in reload.ts is the more targeted root-cause fix,
+ * tracked separately.
+ */
+export declare function reapStrayServeProcesses(serverPid: number, knownPids: Set<number>, kill?: (pid: number, signal: string) => void, scan?: (serverPid: number, knownPids: Set<number>) => ServeScan | null, ownRoot?: string): number;
+/**
+ * Kill a single process by PID: SIGTERM first, escalating to SIGKILL after a
+ * grace period if it hasn't exited. Same sequence AgentRunner.stop() and the
+ * stray-serve reaper already use elsewhere. Backs the manual "Kill" action in
+ * the System Resources panel — callers must verify the PID is one RepoOS
+ * itself is tracking (a fresh sampleSystem()/scanServeProcesses() result)
+ * before calling this; it does not re-check.
+ */
+export declare function killTrackedProcess(pid: number, kill?: (pid: number, signal: NodeJS.Signals) => void): boolean;
+export interface SampleSystemOptions {
+    serverPid: number;
+    cacheDir: string;
+    runningAgents: RunningAgentInfo[];
+    /** PIDs of preview servers RepoOS knows it started — never counted as strays. */
+    knownServePids?: number[];
+    /** Repo root — enables the git-derived `repo` codebase-size stats. */
+    root?: string;
+    /** Advisory worktree ceiling surfaced in `repo.worktreeWarnThreshold`. */
+    worktreeWarnThreshold?: number;
+}
+/**
+ * Sample the system: machine facts, RepoOS process totals, and a per-process
+ * breakdown with orphan detection. One `ps` call covers all tracked + agent PIDs.
+ */
+export declare function sampleSystem(opts: SampleSystemOptions): SystemStats;
+/**
+ * True when the current platform can run the `ps` command with the expected
+ * flags (pid=,ppid=,%cpu=,%mem=,rss=,etime=). Windows `ps` (PowerShell alias)
+ * does not support these flags, so per-process stats are unavailable there.
+ */
+export declare function psAvailable(): boolean;
+export {};