@dsdenes/devboard 0.1.559 → 0.1.562

package/issues/lock.ts

@@ -0,0 +1,305 @@
+import { randomUUID } from "node:crypto";
+import {
+  closeSync,
+  fstatSync,
+  linkSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  renameSync,
+  unlinkSync,
+  writeSync,
+} from "node:fs";
+import { dirname } from "node:path";
+import { isInteger, isRecord } from "./guards";
+
+/**
+ * One repository-anchored lock serialises every worker start for a checkout,
+ * whichever dashboard and state directory asked for it. It records the owner
+ * pid and start time, so a killed worker cannot wedge the repository forever
+ * and a recycled pid is not mistaken for the owner.
+ */
+
+export interface LockOwner {
+  pid: number;
+  /** ISO 8601 start time of the owning process, from its own clock. */
+  startedAt: string;
+  repo: string;
+  stateDir: string;
+  harnessVersion: string | null;
+  argv: string[];
+}
+
+export type LockResult =
+  | { acquired: true; owner: LockOwner; release: () => void }
+  | { acquired: false; owner?: LockOwner };
+
+/**
+ * Linux reports the process start in `/proc/<pid>/stat` as ticks of USER_HZ,
+ * which is 100 on every supported Linux build.
+ */
+const CLOCK_TICKS_PER_SECOND = 100;
+
+/**
+ * Slack between a recorded start and the same process's start read back from
+ * `/proc`. Locks written before the start time was recorded carry the
+ * acquisition instant instead, which trails the process start by startup time.
+ */
+const START_TIME_TOLERANCE_MS = 2_000;
+
+export function pidAlive(pid: number): boolean {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code === "EPERM";
+  }
+}
+
+/**
+ * The instant a live process started, in epoch milliseconds, derived from
+ * `/proc/<pid>/stat` and the kernel's own uptime. Undefined when the platform
+ * has no `/proc` or the process start cannot be read.
+ */
+function processStartedAt(pid: number): number | undefined {
+  if (process.platform !== "linux") return undefined;
+  try {
+    const stat = readFileSync(`/proc/${pid}/stat`, "utf8");
+    // The command name may contain spaces and parentheses; fields resume after
+    // the last ")". That suffix starts at field 3 (state), so starttime, field
+    // 22, is index 19.
+    const close = stat.lastIndexOf(")");
+    if (close < 0) return undefined;
+    const startTicks = Number(stat.slice(close + 2).split(" ")[19]);
+    // Measured after the stat read, so process start = now - uptime + ticks.
+    const uptimeSeconds = Number(readFileSync("/proc/uptime", "utf8").split(" ")[0]);
+    if (!Number.isFinite(startTicks) || !Number.isFinite(uptimeSeconds)) return undefined;
+    return Date.now() - uptimeSeconds * 1000 + (startTicks * 1000) / CLOCK_TICKS_PER_SECOND;
+  } catch {
+    return undefined;
+  }
+}
+
+/** The instant this process started, for the lock it writes. */
+function ownStartedAt(): string {
+  const started = processStartedAt(process.pid) ?? Date.now() - process.uptime() * 1000;
+  return new Date(started).toISOString();
+}
+
+/**
+ * True when the live process with `owner.pid` is the lock's own owner, not a
+ * recycled pid. A live pid whose start does not match the recorded instant is
+ * stale: the owner died and the OS reused its pid. Without an identity source
+ * (no `/proc` on this platform) a live pid is the only available proof.
+ */
+function ownerAlive(owner: LockOwner): boolean {
+  if (!pidAlive(owner.pid)) return false;
+  const recorded = Date.parse(owner.startedAt);
+  if (!Number.isFinite(recorded)) return false;
+  const actual = processStartedAt(owner.pid);
+  if (actual === undefined) return process.platform !== "linux";
+  return Math.abs(actual - recorded) <= START_TIME_TOLERANCE_MS;
+}
+
+interface ParsedLock {
+  owner: LockOwner | undefined;
+  /** Per-acquisition identity; absent on locks written by older harnesses. */
+  token: string | undefined;
+}
+
+function parseLock(content: string): ParsedLock {
+  try {
+    const parsed: unknown = JSON.parse(content);
+    if (!isRecord(parsed)) return { owner: undefined, token: undefined };
+    if (!isInteger(parsed.pid) || typeof parsed.startedAt !== "string") {
+      return { owner: undefined, token: undefined };
+    }
+    return {
+      owner: {
+        pid: parsed.pid,
+        startedAt: parsed.startedAt,
+        repo: typeof parsed.repo === "string" ? parsed.repo : "",
+        stateDir: typeof parsed.stateDir === "string" ? parsed.stateDir : "",
+        harnessVersion: typeof parsed.harnessVersion === "string" ? parsed.harnessVersion : null,
+        argv: Array.isArray(parsed.argv)
+          ? parsed.argv.filter((entry): entry is string => typeof entry === "string")
+          : [],
+      },
+      token: typeof parsed.token === "string" ? parsed.token : undefined,
+    };
+  } catch {
+    return { owner: undefined, token: undefined };
+  }
+}
+
+/** The lock's owner, if the file is present and readable. */
+export function readLock(path: string): LockOwner | undefined {
+  try {
+    return parseLock(readFileSync(path, "utf8")).owner;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * A lock file's owner together with the identity of the file that carried it.
+ * The token distinguishes two lock files with the same owner fields, which is
+ * exactly what a stale lock and a freshly created one by the same process look
+ * like; the inode covers locks written before tokens existed.
+ */
+interface LockSnapshot {
+  owner: LockOwner | undefined;
+  token: string | undefined;
+  device: number;
+  inode: number;
+}
+
+/** Reads one lock file through a single descriptor, so content and identity agree. */
+function readSnapshot(path: string): LockSnapshot | undefined {
+  let descriptor: number;
+  try {
+    descriptor = openSync(path, "r");
+  } catch {
+    return undefined;
+  }
+  try {
+    const stats = fstatSync(descriptor);
+    const parsed = parseLock(readFileSync(descriptor, "utf8"));
+    return {
+      owner: parsed.owner,
+      token: parsed.token,
+      device: stats.dev,
+      inode: stats.ino,
+    };
+  } catch {
+    return undefined;
+  } finally {
+    closeSync(descriptor);
+  }
+}
+
+/**
+ * True when two snapshots are the same lock file. The written token is the
+ * primary identity because the filesystem can reuse a freed inode for the
+ * very lock that won the race; locks from older harnesses fall back to the
+ * inode.
+ */
+function sameLockFile(left: LockSnapshot, right: LockSnapshot): boolean {
+  if (left.token !== undefined || right.token !== undefined) {
+    return left.token !== undefined && left.token === right.token;
+  }
+  return left.device === right.device && left.inode === right.inode;
+}
+
+/**
+ * Reclaims `inspected` without ever deleting whatever currently sits at
+ * `path` by guess. The path is moved aside atomically; only a file that is
+ * still the inspected lock is discarded. A newer lock that arrived after the
+ * inspection is moved back instead of being destroyed.
+ */
+function reclaimStaleLock(path: string, inspected: LockSnapshot): void {
+  const aside = `${path}.reclaim-${process.pid}-${randomUUID()}`;
+  try {
+    renameSync(path, aside);
+  } catch {
+    // A concurrent starter already removed or replaced it; retry the create.
+    return;
+  }
+  const moved = readSnapshot(aside);
+  if (moved === undefined || !sameLockFile(inspected, moved)) {
+    try {
+      linkSync(aside, path);
+    } catch {
+      // The path holds a still newer lock; leave the moved file untouched
+      // rather than deleting a lock some live owner believes it holds.
+      return;
+    }
+    try {
+      unlinkSync(aside);
+    } catch {
+      // The restore already linked it back; the orphaned name is harmless.
+    }
+    return;
+  }
+  try {
+    unlinkSync(aside);
+  } catch {
+    // Another reclaimer observed the same stale inode and removed it.
+  }
+}
+
+/** The live owner of a lock, or undefined when it is missing or stale. */
+export function liveLockOwner(path: string): LockOwner | undefined {
+  const owner = readLock(path);
+  if (owner === undefined || !ownerAlive(owner)) return undefined;
+  return owner;
+}
+
+export interface AcquireLockOptions {
+  /**
+   * Test seam: called with the stale holder after inspection and before
+   * reclamation, so an interleaving starter can be driven deterministically.
+   */
+  onStaleLock?: (owner: LockOwner | undefined) => void;
+}
+
+/**
+ * Takes the lock, or reports the live owner. A lock whose owner is gone or
+ * whose pid was recycled is reclaimed once; a second failure means a
+ * concurrent start won the race.
+ */
+export function acquireLock(
+  path: string,
+  details: Omit<LockOwner, "pid" | "startedAt">,
+  options: AcquireLockOptions = {},
+): LockResult {
+  mkdirSync(dirname(path), { recursive: true });
+  const owner: LockOwner = { ...details, pid: process.pid, startedAt: ownStartedAt() };
+  const token = randomUUID();
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    try {
+      // Publish a complete lock atomically: a reader that inspects the path
+      // must never see the empty or half-written window of a live lock.
+      const staged = `${path}.new-${process.pid}-${randomUUID()}`;
+      try {
+        const descriptor = openSync(staged, "wx");
+        try {
+          writeSync(descriptor, `${JSON.stringify({ ...owner, token })}\n`);
+        } finally {
+          closeSync(descriptor);
+        }
+        linkSync(staged, path);
+      } finally {
+        try {
+          unlinkSync(staged);
+        } catch {
+          // The staged name is removed whether the link won or lost.
+        }
+      }
+      return {
+        acquired: true,
+        owner,
+        release() {
+          const current = readSnapshot(path);
+          if (current !== undefined && current.token !== token) return;
+          try {
+            unlinkSync(path);
+          } catch {
+            // Another invocation, or the operator, already removed it.
+          }
+        },
+      };
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+      const snapshot = readSnapshot(path);
+      if (snapshot === undefined) continue;
+      if (snapshot.owner !== undefined && ownerAlive(snapshot.owner)) {
+        return { acquired: false, owner: snapshot.owner };
+      }
+      options.onStaleLock?.(snapshot.owner);
+      reclaimStaleLock(path, snapshot);
+    }
+  }
+  return { acquired: false };
+}

package/issues/paths.ts

@@ -0,0 +1,76 @@
+import { join, resolve } from "node:path";
+import { journalKey } from "../server/journal";
+
+/**
+ * Every path one repository's issues worker owns. State lives under the
+ * dashboard's `STATE_DIR`, keyed by the repository path exactly like the
+ * dashboard journal, so two checkouts sharing one state directory never read
+ * each other's records. The lock deliberately lives in the checkout instead:
+ * one repository can have only one worker, whichever state directory a
+ * dashboard was configured with.
+ */
+
+export const ISSUES_DIRECTORY = "issues";
+export const STATE_VERSION = 2;
+export const LEDGER_VERSION = 1;
+export const RUN_HISTORY_LIMIT = 50;
+export const ACTIVITY_MAX_ENTRIES = 1000;
+export const ACTIVITY_MAX_BYTES = 1024 * 1024;
+export const ACTIVITY_TRIMMED_MARKER = "Earlier activity was trimmed.";
+
+/** `<STATE_DIR>/issues`: every repository's records below one dashboard. */
+export function issuesRoot(stateDir: string): string {
+  return join(stateDir, ISSUES_DIRECTORY);
+}
+
+/** `<STATE_DIR>/issues/<journalKey(repoDir)>`. */
+export function repoStateDirectory(stateDir: string, repoDir: string): string {
+  return join(issuesRoot(stateDir), journalKey(resolve(repoDir)));
+}
+
+export function statePath(stateDir: string, repoDir: string): string {
+  return join(repoStateDirectory(stateDir, repoDir), "state.json");
+}
+
+export function ledgerPath(stateDir: string, repoDir: string): string {
+  return join(repoStateDirectory(stateDir, repoDir), "ledger.json");
+}
+
+export function runsDirectory(stateDir: string, repoDir: string): string {
+  return join(repoStateDirectory(stateDir, repoDir), "runs");
+}
+
+export function runDirectory(stateDir: string, repoDir: string, runId: string): string {
+  return join(runsDirectory(stateDir, repoDir), runId);
+}
+
+/** Command files the dashboard writes and the worker consumes in order. */
+export function controlDirectory(stateDir: string, repoDir: string): string {
+  return join(repoStateDirectory(stateDir, repoDir), "control");
+}
+
+/**
+ * The repository-anchored lock: `<REPO_DIR>/.devboard/.tmp/issues/lock`.
+ * A checkout cannot host two workers even when their dashboards disagree
+ * about the state directory.
+ */
+export function lockPath(repoDir: string): string {
+  return join(resolve(repoDir), ".devboard", ".tmp", ISSUES_DIRECTORY, "lock");
+}
+
+/** The removed systemd orchestrator's records, read only for migration. */
+export function legacyDirectory(stateDir: string): string {
+  return join(stateDir, "orchestrator");
+}
+
+export function legacyStatePath(stateDir: string): string {
+  return join(legacyDirectory(stateDir), "state.json");
+}
+
+export function legacyLedgerPath(stateDir: string): string {
+  return join(legacyDirectory(stateDir), "ledger.json");
+}
+
+export function legacyLockPath(stateDir: string): string {
+  return join(legacyDirectory(stateDir), "lock");
+}

package/issues/preflight.ts

@@ -0,0 +1,189 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import {
+  findOnPath,
+  ompCommandPaths,
+  ompExtensionPaths,
+  originForge,
+  rootProblem,
+} from "./repository";
+import {
+  configuredGiteaToken,
+  giteaBaseUrl,
+  type ForgeRemote,
+} from "../lib/forge";
+import { giteaRepository, type FetchLike } from "../lib/gitea";
+import { legacyLiveLock, legacyLockRefusal } from "./legacy";
+import type { GhOutcome } from "./tracker";
+
+/**
+ * Everything Start must prove before it spawns a worker: the checkout is the
+ * canonical root of a GitHub origin, the agent tools exist, the command is
+ * installed, the credential can push, and no legacy orchestrator still owns
+ * the tracker. A refusal names the missing fact and writes no ACP peer.
+ */
+
+export type PreflightResult = { ok: true; repository: string } | { ok: false; message: string };
+
+export interface PreflightOptions {
+  repoDir: string;
+  stateDir: string;
+  environment?: Record<string, string | undefined>;
+  /** Injected for tests; defaults to the operator's `gh`. */
+  run?: (argv: string[]) => GhOutcome | Promise<GhOutcome>;
+  /** Injected transport for the Gitea API. */
+  giteaFetch?: FetchLike;
+}
+
+async function gh(argv: string[], environment?: Record<string, string | undefined>): Promise<GhOutcome> {
+  try {
+    const child = Bun.spawn({
+      cmd: ["gh", ...argv],
+      stdin: "ignore",
+      stdout: "pipe",
+      stderr: "pipe",
+      env: {
+        ...(environment ?? process.env),
+        GH_PROMPT_DISABLED: "1",
+        GH_NO_UPDATE_NOTIFIER: "1",
+        GIT_TERMINAL_PROMPT: "0",
+        NO_COLOR: "1",
+      },
+    });
+    const [stdout, stderr, code] = await Promise.all([
+      new Response(child.stdout).text(),
+      new Response(child.stderr).text(),
+      child.exited,
+    ]);
+    return { code, stdout: stdout.trim(), stderr: stderr.trim() };
+  } catch (error) {
+    return { code: 1, stdout: "", stderr: error instanceof Error ? error.message : String(error) };
+  }
+}
+
+function firstLine(text: string): string | undefined {
+  return text
+    .split("\n")
+    .map((line) => line.trim())
+    .find((line) => line.length > 0);
+}
+
+export async function preflightIssues(options: PreflightOptions): Promise<PreflightResult> {
+  const environment = options.environment ?? process.env;
+  const root = rootProblem(options.repoDir);
+  if (root !== undefined) return { ok: false, message: root };
+
+  const remote = originForge(options.repoDir, environment);
+  if (remote === undefined) {
+    return { ok: false, message: "the checkout's origin does not name a supported repository" };
+  }
+  if (remote.forge === "gitlab") {
+    return {
+      ok: false,
+      message: `the issues console supports a GitHub or Gitea origin, not a GitLab one: ${remote.host}`,
+    };
+  }
+  const repository = remote.project;
+
+  const legacy = legacyLiveLock(options.stateDir);
+  if (legacy !== undefined) {
+    return { ok: false, message: legacyLockRefusal(legacy, options.stateDir) };
+  }
+
+  if (findOnPath("omp", environment) === undefined) {
+    return { ok: false, message: "missing prerequisite: omp is not on PATH" };
+  }
+  if (remote.forge === "github" && findOnPath("gh", environment) === undefined) {
+    return { ok: false, message: "missing prerequisite: gh is not on PATH" };
+  }
+
+  const commands = ompCommandPaths(options.repoDir, environment).map((directory) =>
+    join(directory, "implement-issue.md"),
+  );
+  if (!commands.some((path) => existsSync(path))) {
+    return {
+      ok: false,
+      message:
+        "missing prerequisite: the /implement-issue command is not installed for omp " +
+        `(looked in ${commands.join(", ")}); install the harness wrappers with .devboard/install.sh`,
+    };
+  }
+
+  const extensions = ompExtensionPaths(options.repoDir, environment).map((directory) =>
+    join(directory, "implement-goal-issue.ts"),
+  );
+  if (!extensions.some((path) => existsSync(path))) {
+    return {
+      ok: false,
+      message:
+        "missing prerequisite: the /implement-goal-issue extension is not installed for omp " +
+        `(looked in ${extensions.join(", ")}); install the harness wrappers with .devboard/install.sh`,
+    };
+  }
+
+  if (remote.forge === "gitea") {
+    const baseUrl = giteaBaseUrl(remote, environment);
+    if (baseUrl === undefined) {
+      return {
+        ok: false,
+        message:
+          "missing prerequisite: the Gitea address is not configured " +
+          "(set DEVBOARD_GITEA_URL or use an HTTP(S) origin)",
+      };
+    }
+    const token = configuredGiteaToken(environment);
+    if (token === undefined) {
+      return { ok: false, message: "missing prerequisite: GITEA_TOKEN is not set" };
+    }
+    try {
+      const document = await giteaRepository(
+        { baseUrl, project: repository, token },
+        options.giteaFetch,
+      );
+      const permissions =
+        typeof document.permissions === "object" && document.permissions !== null
+          ? document.permissions
+          : {};
+      const writable =
+        "push" in permissions && permissions.push === true ||
+        "admin" in permissions && permissions.admin === true;
+      if (!writable) {
+        return {
+          ok: false,
+          message:
+            `missing prerequisite: the Gitea token cannot write to ${repository} on ${baseUrl}`,
+        };
+      }
+    } catch (error) {
+      return {
+        ok: false,
+        message:
+          `missing prerequisite: the Gitea repository ${repository} could not be read: ` +
+          (error instanceof Error ? error.message : String(error)),
+      };
+    }
+    return { ok: true, repository };
+  }
+
+  const execute = options.run ?? ((argv: string[]) => gh(argv, environment));
+  const permission = await execute([
+    "api",
+    `repos/${repository}`,
+    "--jq",
+    ".permissions.push",
+  ]);
+  if (permission.code !== 0 || permission.stdout.trim() !== "true") {
+    const detail =
+      firstLine(permission.stderr) ??
+      firstLine(permission.stdout) ??
+      `gh exited with code ${permission.code}`;
+    return {
+      ok: false,
+      message:
+        `missing prerequisite: 'gh api repos/${repository} --jq .permissions.push' ` +
+        `did not return true: ${detail}`,
+    };
+  }
+
+  return { ok: true, repository };
+}