@repo-os/repoos 0.5.45

package/dist/commands/status.js

@@ -0,0 +1,569 @@
+/**
+ * `repoos status` — one-screen health/orientation snapshot for the
+ * repo-as-OS (#0324). Think `git status`: server, build freshness, board,
+ * worktrees, tunnel, git — collapsed into one screen so "what is off right
+ * now?" never requires knowing which of five commands to run.
+ *
+ * Must work with the server STOPPED: the serve lockfile, the build marker,
+ * `work/*.md` (via buildIndex), and git are read directly. When the server IS
+ * up, the picture is enriched from `/api/health` and `/api/tunnel/readiness`
+ * — but those calls are best-effort with tight timeouts, never required, and
+ * can never make this command hang.
+ *
+ * `--json` prints the same snapshot machine-readably (shape documented in
+ * docs/architecture.md, "repoos status"). Zero new runtime dependencies.
+ */
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { basename, join } from "node:path";
+import { execFileSync } from "node:child_process";
+import { boardRoot, loadConfig, resolveServePort } from "../core/config.js";
+import { buildIndex } from "../core/indexer.js";
+import { checkBuildForRoot, readBuildStamp } from "../core/build.js";
+import { readTunnelConfig } from "../core/tunnel.js";
+import { readRegistry, reconcileIdentity, syncFromRepo, unionApps, } from "../core/tunnel-registry.js";
+import { currentBranch, runGit } from "../core/git.js";
+import { countWorktrees, sweepStaleWorktrees } from "../core/worktree-gc.js";
+import { isOrphanServeCommand, isPortListening } from "../server/serve-reaper.js";
+import { STATUSES } from "../core/types.js";
+import { c } from "../cli/colors.js";
+/** EPERM means "alive but not ours" — still alive. */
+function pidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+    }
+    catch (e) {
+        return e.code === "EPERM";
+    }
+    // kill -0 only proves SOME process owns the PID — after OS PID recycling it
+    // may be an unrelated process that has nothing to do with this repo's
+    // server. Verify the command line has the repoos serve shape (the same
+    // matcher ServeReaper's orphan sweep uses) before trusting it. If `ps`
+    // itself fails, keep the existence verdict: collectStatus independently
+    // cross-checks the port before believing "running".
+    if (process.platform === "win32")
+        return true;
+    try {
+        const cmdline = execFileSync("ps", ["-p", String(pid), "-o", "command="], {
+            encoding: "utf8",
+            timeout: 2000,
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+        if (!cmdline)
+            return false; // gone between kill(0) and ps
+        return isOrphanServeCommand(cmdline);
+    }
+    catch {
+        return true;
+    }
+}
+/** startedAt as a comparable number (missing/unparsable sorts oldest). */
+function lockStartedMs(l) {
+    const t = Date.parse(l.startedAt ?? "");
+    return Number.isFinite(t) ? t : 0;
+}
+/**
+ * Read every `.repoos/serve[-<port>].lock`. Locks are scoped per port (see
+ * ServeReaper), so there can legitimately be more than one; they are ordered
+ * live-first, then newest-first by `startedAt`, so the primary is the one
+ * that matters. Exported for tests.
+ */
+export function readServeLocks(root, cacheDir) {
+    let files;
+    try {
+        files = readdirSync(join(root, cacheDir)).filter((f) => /^serve(?:-\d+)?\.lock$/.test(f));
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const file of files) {
+        try {
+            const raw = JSON.parse(readFileSync(join(root, cacheDir, file), "utf8"));
+            const pid = typeof raw.pid === "number" && Number.isInteger(raw.pid) ? raw.pid : 0;
+            const alive = pid > 0 && pid !== process.pid && pidAlive(pid);
+            out.push({
+                file,
+                pid,
+                port: typeof raw.port === "number" ? raw.port : null,
+                host: typeof raw.host === "string" ? raw.host : null,
+                startedAt: typeof raw.startedAt === "string" ? raw.startedAt : null,
+                alive,
+            });
+        }
+        catch {
+            /* corrupt lockfile — ignore; `repoos serve`'s reaper will clean it up */
+        }
+    }
+    out.sort((a, b) => Number(b.alive) - Number(a.alive) || lockStartedMs(b) - lockStartedMs(a));
+    return out;
+}
+async function probeHealth(port, root, timeoutMs) {
+    const miss = {
+        state: "unreachable",
+        root: null,
+        version: null,
+        serverStartedAt: null,
+    };
+    try {
+        const res = await fetch(`http://127.0.0.1:${port}/api/health`, {
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        if (!res.ok)
+            return miss;
+        const body = (await res.json());
+        if (body.ok !== true || typeof body.root !== "string")
+            return miss;
+        return {
+            state: body.root === root ? "ok" : "foreign",
+            root: body.root,
+            version: typeof body.version === "string" ? body.version : null,
+            serverStartedAt: typeof body.serverStartedAt === "string" ? body.serverStartedAt : null,
+        };
+    }
+    catch {
+        return miss;
+    }
+}
+/** pgrep for a running cloudflared tunnel process — same shape tunnel status uses. */
+function tunnelProcessRunning() {
+    try {
+        return (execFileSync("pgrep", ["-f", "cloudflared.*tunnel.*run"], {
+            encoding: "utf8",
+            timeout: 2000,
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim() !== "");
+    }
+    catch {
+        return false;
+    }
+}
+/** launchd/systemd service state for cloudflared — same shape tunnel status uses. */
+function tunnelServiceRunning() {
+    try {
+        if (process.platform === "darwin") {
+            const out = execFileSync("launchctl", ["list"], {
+                encoding: "utf8",
+                timeout: 2000,
+                stdio: ["ignore", "pipe", "ignore"],
+            });
+            return out
+                .split("\n")
+                .some((line) => line.includes("com.cloudflare.cloudflared") && /^\s*\d+\s+/.test(line));
+        }
+        if (process.platform === "linux") {
+            return (execFileSync("systemctl", ["is-active", "cloudflared"], {
+                encoding: "utf8",
+                timeout: 2000,
+                stdio: ["ignore", "pipe", "ignore"],
+            }).trim() === "active");
+        }
+    }
+    catch {
+        /* service manager unavailable */
+    }
+    return false;
+}
+function readVersionFromMarker(root) {
+    try {
+        const info = JSON.parse(readFileSync(join(root, "dist", ".build-info.json"), "utf8"));
+        return typeof info.version === "string" && info.version ? info.version : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Build the full snapshot. Everything is fail-soft: a missing lockfile, a dead
+ * server, an unreadable marker, or absent git degrade the matching section —
+ * never crash the command.
+ */
+export async function collectStatus(config, opts = {}) {
+    const now = opts.now ?? new Date();
+    const root = config.root;
+    const timeoutMs = opts.probeTimeoutMs ?? 800;
+    // ── server ──
+    const locks = readServeLocks(root, config.cacheDir);
+    // The primary lock is live-first, then most recent — its facts are reported
+    // even when dead, because "lockfile names pid X, which is gone" is exactly
+    // the diagnostic a stopped-but-should-be-running repo needs.
+    const primary = locks[0] ?? null;
+    const primaryAlive = primary?.alive ?? false;
+    // Probe the live lock's port; else a stale lock's port (the "lock is dead —
+    // is anything still on it?" diagnostic); else this repo's default port.
+    const probePort = opts.probePort ?? primary?.port ?? resolveServePort(root, config);
+    const health = await probeHealth(probePort, root, timeoutMs);
+    // Ground "running" in the port: when /api/health is unreachable, check
+    // whether anything is actually listening before trusting the lock's
+    // (possibly recycled) live PID.
+    const portActive = health.state !== "unreachable" || (await isPortListening(probePort, "127.0.0.1"));
+    const running = primaryAlive ? portActive : health.state === "ok";
+    let startedAt = primary?.startedAt ?? null;
+    let startedAtSource = startedAt ? "lockfile" : null;
+    if (!startedAt && health.state === "ok" && health.serverStartedAt) {
+        // Thin lockfile — fall back to /api/health, as the spec asks.
+        startedAt = health.serverStartedAt;
+        startedAtSource = "health";
+    }
+    const uptimeMs = startedAt !== null ? Math.max(0, now.getTime() - Date.parse(startedAt)) : null;
+    const server = {
+        running,
+        port: primary?.port ?? probePort,
+        pid: primary?.pid ?? null,
+        host: primary?.host ?? null,
+        startedAt,
+        startedAtSource,
+        uptimeSeconds: uptimeMs !== null && Number.isFinite(uptimeMs) ? uptimeMs / 1000 : null,
+        health: health.state,
+        healthRoot: health.root,
+        locks: locks.length,
+    };
+    // ── build ──
+    const check = checkBuildForRoot(root);
+    const build = {
+        code: check.code,
+        stale: check.stale,
+        applicable: check.applicable,
+        message: check.message,
+        version: readVersionFromMarker(root) ?? health.version,
+        buildAt: readBuildStamp(root),
+    };
+    // ── board ──
+    const idx = buildIndex(config);
+    const active = idx.tasks
+        .filter((t) => t.status === "active")
+        .map((t) => {
+        const wt = t.git.worktreePath;
+        const missing = !!t.branch && (!wt || !existsSync(wt));
+        return {
+            id: t.id,
+            title: t.title,
+            branch: t.branch,
+            worktreePath: wt,
+            worktreeMissing: missing,
+            updatedAt: t.updated_at,
+            needsInput: t.needsInput,
+        };
+    });
+    // ── worktrees ──
+    // Same sweep `repoos gc --dry-run` runs, fed the index we already built so
+    // the board is only walked once. The counts therefore match gc by
+    // construction, not by coincidence.
+    const gc = sweepStaleWorktrees(config, { mode: "full", dryRun: true, tasks: idx.tasks });
+    const worktrees = {
+        count: countWorktrees(root),
+        warnThreshold: config.worktreeWarnThreshold ?? 20,
+        leaked: gc.removedWorktrees.map((w) => ({ branch: w.branch, path: w.path })),
+        kept: gc.keptDirty.map((k) => ({ branch: k.branch, path: k.path, reason: k.reason })),
+    };
+    // ── tunnel ──
+    const tunnelCfg = readTunnelConfig(root);
+    const configured = !!tunnelCfg.tunnelId;
+    let tunnelRunning = false;
+    // Machine-wide view (any repo's apps, from the registry), same merge
+    // `/api/tunnel/readiness` does — falls back to this repo's own apps when
+    // the registry hasn't been seeded yet.
+    const registry = readRegistry();
+    reconcileIdentity(registry, tunnelCfg);
+    syncFromRepo(registry, tunnelCfg, root);
+    let hostnames = Object.values({ ...tunnelCfg.apps, ...unionApps(registry) })
+        .map((a) => a.hostname)
+        .sort();
+    if (configured) {
+        tunnelRunning = tunnelProcessRunning() || tunnelServiceRunning();
+        if (health.state === "ok") {
+            // Server is up — prefer its readiness view (same data, live). Best
+            // effort only: on auth-protected servers this endpoint 401s (the CLI
+            // has no session), and the local answer below is identical to what
+            // `repoos tunnel status` computes, so nothing is lost.
+            try {
+                const res = await fetch(`http://127.0.0.1:${probePort}/api/tunnel/readiness`, {
+                    signal: AbortSignal.timeout(Math.max(timeoutMs, 2000)),
+                });
+                if (res.ok) {
+                    const body = (await res.json());
+                    if (typeof body.running === "boolean")
+                        tunnelRunning = body.running;
+                    if (Array.isArray(body.publishedHostnames)) {
+                        hostnames = body.publishedHostnames
+                            .filter((h) => typeof h === "string")
+                            .sort();
+                    }
+                }
+            }
+            catch {
+                /* readiness is enrichment only — local answer stands */
+            }
+        }
+    }
+    // ── git (the main checkout — the repo-as-OS itself) ──
+    const branch = currentBranch(root);
+    let clean = true;
+    let dirtyFiles = 0;
+    let ahead = null;
+    let behind = null;
+    if (branch) {
+        const st = await runGit(root, ["status", "--porcelain"], 4000);
+        if (st.status === 0) {
+            dirtyFiles = st.stdout.split("\n").filter((l) => l.trim() !== "").length;
+            clean = dirtyFiles === 0;
+        }
+        if (branch !== "main") {
+            const [a, b] = await Promise.all([
+                runGit(root, ["rev-list", "--count", `main..${branch}`], 4000),
+                runGit(root, ["rev-list", "--count", `${branch}..main`], 4000),
+            ]);
+            ahead = a.status === 0 ? Number(a.stdout.trim()) || 0 : null;
+            behind = b.status === 0 ? Number(b.stdout.trim()) || 0 : null;
+        }
+    }
+    return {
+        generatedAt: now.toISOString(),
+        root,
+        server,
+        build,
+        board: {
+            taskCount: idx.taskCount,
+            counts: idx.counts,
+            active,
+        },
+        worktrees,
+        tunnel: {
+            configured,
+            tunnelName: configured ? tunnelCfg.name : null,
+            running: tunnelRunning,
+            hostnames,
+        },
+        git: {
+            branch,
+            clean,
+            dirtyFiles,
+            isMainBranch: branch === "main",
+            ahead,
+            behind,
+        },
+    };
+}
+// ── Formatting helpers ───────────────────────────────────────────────────────
+/** "42s" | "5m 07s" | "3h 42m" | "2d 4h" */
+export function formatUptime(ms) {
+    const s = Math.max(0, Math.floor(ms / 1000));
+    if (s < 60)
+        return `${s}s`;
+    const m = Math.floor(s / 60);
+    if (m < 60)
+        return `${m}m ${String(s % 60).padStart(2, "0")}s`;
+    const h = Math.floor(m / 60);
+    if (h < 24)
+        return `${h}h ${String(m % 60).padStart(2, "0")}m`;
+    return `${Math.floor(h / 24)}d ${h % 24}h`;
+}
+const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
+/** Local "14:02" on the same day, else "Sep 2 14:02". */
+export function formatSince(iso, now) {
+    const d = new Date(iso);
+    if (Number.isNaN(d.getTime()))
+        return "?";
+    const hm = `${String(d.getHours()).padStart(2, "0")}:${String(d.getMinutes()).padStart(2, "0")}`;
+    const sameDay = d.getFullYear() === now.getFullYear() &&
+        d.getMonth() === now.getMonth() &&
+        d.getDate() === now.getDate();
+    return sameDay ? hm : `${MONTHS[d.getMonth()]} ${d.getDate()} ${hm}`;
+}
+/** "41s ago" | "5m ago" | "3h 02m ago" | "2d ago" — for last-activity stamps. */
+export function formatRel(iso, now) {
+    if (!iso)
+        return "?";
+    const ms = now.getTime() - Date.parse(iso);
+    if (!Number.isFinite(ms))
+        return "?";
+    const s = Math.max(0, Math.floor(ms / 1000));
+    if (s < 60)
+        return `${s}s ago`;
+    const m = Math.floor(s / 60);
+    if (m < 60)
+        return `${m}m ago`;
+    const h = Math.floor(m / 60);
+    if (h < 24)
+        return `${h}h ${String(m % 60).padStart(2, "0")}m ago`;
+    return `${Math.floor(h / 24)}d ago`;
+}
+function truncate(s, n) {
+    return s.length <= n ? s : s.slice(0, n - 1) + "…";
+}
+// ── Rendering ────────────────────────────────────────────────────────────────
+const LABEL = 10;
+function row(label, text) {
+    console.log("  " + c.dim(label.padEnd(LABEL)) + text);
+}
+function sub(text) {
+    console.log("  " + " ".repeat(LABEL) + text);
+}
+export function renderStatus(s, now = new Date()) {
+    console.log("");
+    console.log("  " + c.bold(c.cyan("RepoOS status")) + c.dim(" — " + basename(s.root)));
+    console.log(c.dim("  " + s.root));
+    // Stale build FIRST and loud — per AGENTS.md it is the #1 time-waster in
+    // this repo; it must never read as a quiet footnote.
+    // Only when the RepoOS build contract applies: no dist/ or no marker means
+    // this checkout isn't using our build pipeline, so the "skip" message isn't a
+    // warning (#0349).
+    const buildCheckApplicable = s.build.code !== "no-build" && s.build.code !== "no-marker";
+    if (s.build.stale && buildCheckApplicable && s.build.message) {
+        console.log("");
+        for (const line of s.build.message.split("\n")) {
+            console.log(c.bold(c.yellow("  ⚠ " + line.trim())));
+        }
+    }
+    console.log("");
+    // server
+    const sv = s.server;
+    if (sv.running) {
+        const bits = [];
+        if (sv.port !== null)
+            bits.push(`port ${sv.port}`);
+        if (sv.pid !== null)
+            bits.push(`pid ${sv.pid}`);
+        if (sv.startedAt) {
+            bits.push(`up ${formatUptime((sv.uptimeSeconds ?? 0) * 1000)} (since ${formatSince(sv.startedAt, now)})`);
+        }
+        else {
+            bits.push("start time unknown");
+        }
+        row("server", c.green("● running") + c.dim(" · ") + bits.join(c.dim(" · ")));
+        if (sv.health === "foreign") {
+            sub(c.yellow(`⚠ port ${sv.port} answers, but it serves ${sv.healthRoot ?? "a different repo"} — wrong port?`));
+        }
+        else if (sv.health === "unreachable") {
+            sub(c.yellow(`⚠ port ${sv.port} is listening but /api/health is not answering — the server may be hung`));
+        }
+        else if (sv.pid === null) {
+            sub(c.dim("no serve lockfile — live via /api/health; restart `repoos serve` to restore it"));
+        }
+        if (sv.locks > 1)
+            sub(c.dim(`+ ${sv.locks - 1} more serve lock(s) — check other ports`));
+    }
+    else {
+        let line = c.red("○ stopped") + c.dim(" — no live serve process for this repo");
+        if (sv.pid !== null) {
+            line +=
+                "\n" +
+                    " ".repeat(LABEL) +
+                    c.dim(`last lock: pid ${sv.pid}` +
+                        (sv.port !== null ? ` · port ${sv.port}` : "") +
+                        (sv.startedAt ? ` · started ${formatSince(sv.startedAt, now)}` : ""));
+        }
+        if (sv.health === "foreign") {
+            line +=
+                "\n" +
+                    " ".repeat(LABEL) +
+                    c.yellow(`⚠ but port ${sv.port} is answering for ${sv.healthRoot ?? "another repo"} — wrong port?`);
+        }
+        row("server", line);
+    }
+    // build
+    const buildBits = [
+        s.build.stale ? c.yellow("● stale") : c.green("● fresh"),
+        s.build.version ? c.dim("repoos v" + s.build.version) : c.dim("version unknown"),
+        s.build.buildAt
+            ? c.dim("built " + formatSince(s.build.buildAt, now))
+            : c.dim("build time unknown"),
+    ];
+    row("build", buildBits.join(c.dim(" · ")));
+    if (s.build.code === "no-build" || s.build.code === "published") {
+        sub(c.dim("(no dist build — source checkout)"));
+    }
+    // board
+    const counts = STATUSES.map((st) => `${st} ${s.board.counts[st] ?? 0}`).join(c.dim(" · "));
+    row("board", c.bold(String(s.board.taskCount)) + c.dim(" tasks · ") + counts);
+    for (const t of s.board.active) {
+        const flags = [];
+        if (t.needsInput)
+            flags.push(c.yellow("waiting for you"));
+        if (t.worktreeMissing)
+            flags.push(c.red("⚠ worktree missing"));
+        console.log("\n" +
+            "    " +
+            c.dim("#" + t.id) +
+            "  " +
+            truncate(t.title, 60) +
+            c.dim("  · updated " + formatRel(t.updatedAt, now)) +
+            (flags.length ? "  " + flags.join(c.dim(" · ")) : ""));
+        sub(c.dim("branch   ") + (t.branch ? c.cyan(truncate(t.branch, 80)) : c.dim("— none yet")));
+        sub(c.dim("worktree ") +
+            (t.worktreePath && !t.worktreeMissing
+                ? c.dim(truncate(t.worktreePath, 100))
+                : t.worktreeMissing
+                    ? c.red("missing")
+                    : c.dim("none")));
+    }
+    if (s.board.active.length === 0)
+        sub(c.dim("nothing active"));
+    // worktrees
+    const threshold = s.worktrees.warnThreshold;
+    const wtBits = [`${s.worktrees.count} registered`];
+    if (threshold > 0)
+        wtBits.push(`advisory ceiling ${threshold}`);
+    const leaked = s.worktrees.leaked;
+    const leakText = leaked.length === 0
+        ? c.dim("no leaks")
+        : c.yellow(`${leaked.length} leaked — run `) + c.cyan("repoos gc --dry-run");
+    row("worktrees", wtBits.join(c.dim(" · ")) + c.dim(" · ") + leakText);
+    for (const w of leaked)
+        sub(c.yellow("leaked ") + c.cyan(w.branch || "(detached)") + c.dim("  " + w.path));
+    for (const k of s.worktrees.kept) {
+        sub(c.dim("kept    ") + c.cyan(k.branch || "(detached)") + c.dim(`  — ${k.reason}`));
+    }
+    // tunnel
+    if (!s.tunnel.configured) {
+        row("tunnel", c.dim("not configured") + c.dim("  (") + c.cyan("repoos tunnel setup") + c.dim(")"));
+    }
+    else {
+        const state = s.tunnel.running ? c.green("running") : c.yellow("not running");
+        const hosts = s.tunnel.hostnames.length
+            ? `${s.tunnel.hostnames.length} published: ${s.tunnel.hostnames.join(", ")}`
+            : "no hostnames published";
+        row("tunnel", c.cyan(s.tunnel.tunnelName ?? "tunnel") + c.dim(" · ") + state + c.dim(" · " + hosts));
+    }
+    // git
+    if (!s.git.branch) {
+        row("git", c.dim("not a git repository"));
+    }
+    else {
+        const bits = [c.cyan(s.git.branch)];
+        bits.push(s.git.clean
+            ? c.green("clean")
+            : c.yellow(`dirty (${s.git.dirtyFiles} file${s.git.dirtyFiles === 1 ? "" : "s"})`));
+        if (!s.git.isMainBranch && (s.git.ahead !== null || s.git.behind !== null)) {
+            bits.push(c.dim(`↑${s.git.ahead ?? "?"} ↓${s.git.behind ?? "?"} vs main`));
+        }
+        row("git", bits.join(c.dim(" · ")));
+    }
+    console.log("");
+}
+// ── Command entry ────────────────────────────────────────────────────────────
+/** `repoos status [--json]` */
+export async function cmdStatus(argv) {
+    const asJson = argv.includes("--json");
+    try {
+        const { root, fromWorktree } = boardRoot();
+        if (fromWorktree) {
+            // stderr so `--json` stdout stays machine-clean — same note list/gc print.
+            console.error(c.yellow("  ⚠ ") +
+                c.dim("running from inside a linked worktree — reporting the MAIN checkout (") +
+                c.cyan(root) +
+                c.dim(")"));
+        }
+        const config = loadConfig(root);
+        const snapshot = await collectStatus(config);
+        if (asJson) {
+            console.log(JSON.stringify(snapshot, null, 2));
+        }
+        else {
+            renderStatus(snapshot);
+        }
+    }
+    catch (e) {
+        console.error(c.red("  repoos status failed: ") + e.message);
+        process.exitCode = 1;
+    }
+}

package/dist/commands/stop.d.ts

@@ -0,0 +1 @@
+export declare function cmdStop(argv: string[]): void;

package/dist/commands/stop.js

@@ -0,0 +1,59 @@
+/**
+ * `repoos stop [--port N]` — stop THIS repo's running `repoos serve`
+ * process(es), by the PID recorded in its own `.repoos/serve-<port>.lock`.
+ *
+ * Replaces the machine-wide `pkill -f "dist/cli/index.js serve"` that also
+ * killed every other repo's server (and any preview) — a `repoos init` repo
+ * runs the same linked CLI, so the pattern is not repo-scoped.
+ */
+import { readdirSync, readFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { boardRoot } from "../core/config.js";
+import { createRepoOS } from "../core/repoos.js";
+import { c } from "../cli/colors.js";
+export function cmdStop(argv) {
+    let portFilter;
+    for (let i = 0; i < argv.length; i++) {
+        if (argv[i] === "--port" || argv[i] === "-p")
+            portFilter = Number(argv[++i]);
+    }
+    const { root } = boardRoot();
+    const { config } = createRepoOS(root);
+    const lockDir = join(root, config.cacheDir);
+    let files;
+    try {
+        files = readdirSync(lockDir).filter((f) => /^serve(?:-\d+)?\.lock$/.test(f));
+    }
+    catch {
+        files = [];
+    }
+    if (portFilter)
+        files = files.filter((f) => f === `serve-${portFilter}.lock`);
+    let stopped = 0;
+    for (const file of files) {
+        const path = join(lockDir, file);
+        let info = null;
+        try {
+            info = JSON.parse(readFileSync(path, "utf8"));
+        }
+        catch {
+            rmSync(path, { force: true });
+            continue;
+        }
+        const pid = info?.pid;
+        if (typeof pid === "number" && pid > 0 && pid !== process.pid) {
+            try {
+                process.kill(pid, 0); // existence probe — throws when gone
+                process.kill(pid, "SIGTERM");
+                stopped++;
+                console.log(c.dim(`  stopped repoos serve (pid ${pid}, port ${info.port ?? "?"})`));
+            }
+            catch {
+                /* already exited */
+            }
+        }
+        rmSync(path, { force: true });
+    }
+    if (stopped === 0)
+        console.log(c.dim("  no running repoos serve for this repo"));
+}

package/dist/commands/tasks.d.ts

@@ -0,0 +1,47 @@
+/** `repoos list [status]` — board overview or a single column. */
+export declare function cmdList(statusArg?: string): void;
+/** `repoos show <id>` — full task detail. */
+export declare function cmdShow(id?: string): void;
+/**
+ * `repoos mv <id> <status>` — change status (frontmatter edit).
+ *
+ * Deliberately does NOT run this transition through `guardReviewTransition`
+ * (#0263), even for a move into `review`. That gate lives in the HTTP PATCH
+ * path because it operates on the task's OWN branch worktree — staging and
+ * committing pending implementation changes there and rejecting a vacuous
+ * (zero-source-change) transition — which is an agent-handoff guarantee, not
+ * a board-write guarantee. `repoos mv` is the low-level, generic "edit this
+ * frontmatter field" tool (a human or script can move ANY task to ANY status,
+ * with or without a branch or worktree at all); forcing every review move
+ * through worktree resolution would turn a one-line status edit into a hard
+ * dependency on handoff plumbing that plenty of legitimate `mv` calls don't
+ * have. The bug this task fixes is narrower and applies to every status
+ * change here regardless of target: `updateStatus` (via `rewrite()` in
+ * core/repoos.ts) now always commits the task file in the main checkout, so
+ * the write itself is never left as an untrusted dirty file. Agents that want
+ * the full handoff guarantee (implementation committed + non-vacuous) should
+ * go through the trusted handoff/PATCH path, not this CLI shortcut.
+ */
+export declare function cmdMv(id?: string, status?: string, note?: string): void;
+/**
+ * `repoos note <id> "<text>"` — append a short, free-form note to a task's
+ * activity log, so a PM/reviewer can send guidance back to the developer (or
+ * record any free-form note) without rewriting the task body. The note is
+ * recorded as its own activity entry and surfaces wherever the task's
+ * history is shown. Board-rooted, not cwd-rooted (#0202) — see cmdMv.
+ */
+export declare function cmdNote(args: string[]): void;
+/**
+ * `repoos update <id> [--title ...] [--area ...] [--priority ...] [--type ...]
+ *   [--body ... | --body -] [--branch ...] [--assigned-to ai|human]`
+ *
+ * Writes directly via patchTaskFile (same path the server's PATCH route uses),
+ * so it works with no HTTP round-trip and no session auth — this is the path
+ * agents/scripts should use to edit task metadata instead of hitting the API.
+ * `--body -` reads the new body from stdin, for large/multiline bodies.
+ */
+export declare function cmdUpdate(args: string[]): void;
+/** `repoos new <title> [--ai] [--type t] [--area a] [--priority p] [--body "..."|-]` */
+export declare function cmdNew(args: string[]): void;
+/** `repoos index [--json]` — rebuild cache; optionally print machine-readable JSON. */
+export declare function cmdIndex(args: string[]): void;