@gethmy/harness 1.0.0

package/src/process-group.ts

@@ -0,0 +1,149 @@
+import {
+  type ChildProcess,
+  type SpawnOptions,
+  spawn,
+} from "node:child_process";
+import { log } from "./log.js";
+
+const TAG = "pgroup";
+
+/**
+ * Spawn a child in its own process group so we can reliably kill the
+ * whole subtree later. The Claude CLI shells out to git, build tools,
+ * dev servers, etc. — signalling only the direct child leaves orphans.
+ *
+ * - POSIX: `detached: true` puts the child in a new process group whose
+ *   pgid equals its pid. Killing the negative pid signals every member.
+ * - Windows: `detached: true` creates a new process group that can be
+ *   signalled via the child's pid (no negation).
+ *
+ * `stripEnvKeys` (Task 15) DELETES the named variables from the environment
+ * assembled below. A caller cannot get that by passing a smaller `options.env`:
+ * the merge starts from `process.env`, so a key the caller merely omits still
+ * survives from the parent. This is the only place a child's environment is
+ * assembled here, so it is the only place a deletion sticks. It removes exactly
+ * the named keys and nothing else.
+ */
+export function spawnInGroup(
+  command: string,
+  args: readonly string[],
+  options: SpawnOptions & { stripEnvKeys?: readonly string[] } = {},
+): ChildProcess {
+  const { stripEnvKeys, ...spawnOptions } = options;
+  const env: NodeJS.ProcessEnv = {
+    ...process.env,
+    ...options.env,
+    // When the daemon is launched from a cmux terminal, a bare `claude`
+    // resolves to cmux's wrapper script, which injects a `--settings` block
+    // with a SessionEnd hook (`cmux hooks claude session-end`). Our headless
+    // run is not a tracked cmux surface, so that hook is cancelled and Claude
+    // exits with code 1 — a *false* run failure (the work itself succeeded).
+    // `CMUX_CLAUDE_HOOKS_DISABLED=1` is the wrapper's documented passthrough
+    // escape hatch: it execs the real claude with no hook injection. Harmless
+    // for non-claude children (only the cmux wrapper reads it).
+    CMUX_CLAUDE_HOOKS_DISABLED: "1",
+  };
+  // DELETE, after the merge. Omitting a key from `options.env` would not remove
+  // it — the merge above re-supplies it from `process.env`.
+  for (const key of stripEnvKeys ?? []) delete env[key];
+
+  return spawn(command, args as string[], {
+    ...spawnOptions,
+    detached: true,
+    // Keep stdio wired up so streaming still works.
+    stdio: options.stdio ?? ["ignore", "pipe", "pipe"],
+    env,
+  });
+}
+
+/**
+ * Send a signal to every process in the group whose leader is `proc`.
+ * On POSIX, this is `process.kill(-pid, signal)`. If the group has
+ * already exited, returns silently.
+ */
+export function signalGroup(proc: ChildProcess, signal: NodeJS.Signals): void {
+  if (!proc.pid || proc.killed) return;
+  try {
+    if (process.platform === "win32") {
+      // No process groups on Windows; best effort tree kill via the child.
+      proc.kill(signal);
+      return;
+    }
+    process.kill(-proc.pid, signal);
+  } catch (err) {
+    // ESRCH means the group is already gone — that is the goal, not an error.
+    const code = (err as NodeJS.ErrnoException).code;
+    if (code !== "ESRCH") {
+      log.warn(
+        TAG,
+        `signal ${signal} to pgid ${proc.pid} failed: ${err instanceof Error ? err.message : err}`,
+      );
+    }
+  }
+}
+
+/**
+ * Force-kill every process still in group `pgid`, addressed by the RECORDED
+ * pgid rather than a live ChildProcess. Unlike {@link signalGroup} /
+ * {@link terminateGroup} — which early-return once the group LEADER has exited —
+ * this still fires after a normal run finish, so it reaps backgrounded /
+ * `disown`ed / `nohup`ed grandchildren that reparented to pid 1 but kept the
+ * pgid (card #436: an SDK/CLI run that ends on its own used to leak them).
+ *
+ * Limitation: a grandchild that calls `setsid()` itself leaves the group and is
+ * NOT reachable this way. We accept that rare, deliberate escape — attributing
+ * it would require reading other processes' environments, which is unreliable on
+ * macOS (`ps -E` is restricted there and `setsid` isn't even available).
+ *
+ * Safety: pgid 0/1 (and the caller's own pid) are refused — `kill(-1)` would
+ * signal every process the user owns, and `kill(-0)` the caller's own group.
+ */
+export function reapGroup(pgid: number | undefined): void {
+  if (!pgid || pgid <= 1 || pgid === process.pid) return;
+  if (process.platform === "win32") return; // no process groups to sweep
+  try {
+    process.kill(-pgid, "SIGKILL");
+  } catch (err) {
+    // ESRCH means the group is already empty — that is the goal, not an error.
+    const code = (err as NodeJS.ErrnoException).code;
+    if (code !== "ESRCH") {
+      log.warn(
+        TAG,
+        `reapGroup(${pgid}) failed: ${err instanceof Error ? err.message : err}`,
+      );
+    }
+  }
+}
+
+/**
+ * Escalating termination: SIGINT → wait → SIGTERM → wait → SIGKILL.
+ * Returns when the process has exited or all signals have been sent.
+ */
+export async function terminateGroup(
+  proc: ChildProcess,
+  opts: { sigintTimeoutMs: number; sigtermTimeoutMs: number },
+): Promise<void> {
+  if (!proc.pid || proc.killed) return;
+
+  // Unpause first in case the process was suspended — otherwise it
+  // can't react to signals.
+  signalGroup(proc, "SIGCONT");
+
+  const waitForExit = (timeout: number): Promise<boolean> =>
+    new Promise((resolve) => {
+      if (proc.killed || proc.exitCode !== null) return resolve(true);
+      const timer = setTimeout(() => resolve(false), timeout);
+      proc.once("exit", () => {
+        clearTimeout(timer);
+        resolve(true);
+      });
+    });
+
+  signalGroup(proc, "SIGINT");
+  if (await waitForExit(opts.sigintTimeoutMs)) return;
+
+  signalGroup(proc, "SIGTERM");
+  if (await waitForExit(opts.sigtermTimeoutMs)) return;
+
+  signalGroup(proc, "SIGKILL");
+}

package/src/project-type.ts

@@ -0,0 +1,303 @@
+import { execFileSync } from "node:child_process";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { log } from "./log.js";
+import { spawnRunArgs } from "./pm.js";
+
+const TAG = "project-type";
+
+/**
+ * Known repo toolchains the daemon can build/verify.
+ *
+ * `node` delegates the package-manager variant (bun/npm/pnpm/yarn) down to
+ * {@link pm.ts}; the Swift kinds map onto `swift build` / `xcodebuild`.
+ * `unknown` means we have no idea how to build this repo and must skip
+ * verification gracefully rather than fail the card.
+ */
+export type ProjectKind = "node" | "swift-spm" | "swift-xcode" | "unknown";
+
+export interface ProjectType {
+  kind: ProjectKind;
+  /** Absolute path to the `.xcworkspace` / `.xcodeproj` (swift-xcode only). */
+  xcodeContainer?: string;
+  /** True when {@link xcodeContainer} is a workspace (vs a bare project). */
+  xcodeIsWorkspace?: boolean;
+}
+
+/** A resolved executable + args, ready for `execFileSync` / `spawn`. */
+export interface ToolchainCommand {
+  cmd: string;
+  args: string[];
+}
+
+// Detection touches the filesystem (and `xcodebuild -list` for schemes), so
+// cache per directory. Tests reset via `_resetCache()`.
+const _cache = new Map<string, ProjectType>();
+
+/** Clear the per-directory detection cache. Test-only. */
+export function _resetCache(): void {
+  _cache.clear();
+}
+
+/**
+ * Detect the project toolchain rooted at `dir`.
+ *
+ * Priority: `package.json` (Node) → `Package.swift` (Swift SPM) →
+ * `*.xcworkspace` → `*.xcodeproj` → `unknown`. Node wins first because a
+ * Node repo may legitimately vendor Swift tooling without being a Swift app,
+ * and the Node path is what the vast majority of Harmony repos need.
+ */
+export function detect(dir: string): ProjectType {
+  const cached = _cache.get(dir);
+  if (cached) return cached;
+
+  const result = detectUncached(dir);
+  _cache.set(dir, result);
+  log.info(TAG, `Detected project type in ${dir}: ${result.kind}`);
+  return result;
+}
+
+function detectUncached(dir: string): ProjectType {
+  if (existsSync(`${dir}/package.json`)) return { kind: "node" };
+  if (existsSync(`${dir}/Package.swift`)) return { kind: "swift-spm" };
+
+  const entries = safeReaddir(dir);
+  const workspace = entries.find((e) => e.endsWith(".xcworkspace"));
+  if (workspace) {
+    return {
+      kind: "swift-xcode",
+      xcodeContainer: `${dir}/${workspace}`,
+      xcodeIsWorkspace: true,
+    };
+  }
+  const project = entries.find((e) => e.endsWith(".xcodeproj"));
+  if (project) {
+    return {
+      kind: "swift-xcode",
+      xcodeContainer: `${dir}/${project}`,
+      xcodeIsWorkspace: false,
+    };
+  }
+
+  return { kind: "unknown" };
+}
+
+function safeReaddir(dir: string): string[] {
+  try {
+    return readdirSync(dir);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Resolve the build command for the repo at `dir`, or `null` when there's no
+ * known/usable build step (caller must skip-and-warn, never fail the card).
+ */
+export function buildCommand(dir: string): ToolchainCommand | null {
+  const pt = detect(dir);
+  switch (pt.kind) {
+    case "node": {
+      const [cmd, args] = spawnRunArgs("build");
+      return { cmd, args };
+    }
+    case "swift-spm":
+      return { cmd: "swift", args: ["build"] };
+    case "swift-xcode":
+      return xcodeBuildCommand(pt);
+    case "unknown":
+      return null;
+  }
+}
+
+/**
+ * Resolve the lint command for the repo at `dir`, or `null` when the
+ * toolchain has no separate lint step (Swift verifies via the build).
+ */
+export function lintCommand(dir: string): ToolchainCommand | null {
+  const pt = detect(dir);
+  switch (pt.kind) {
+    case "node": {
+      const [cmd, args] = spawnRunArgs("lint");
+      return { cmd, args };
+    }
+    // Swift has no standard lint gate wired here — `swift build` /
+    // `xcodebuild build` already surface compile errors. SwiftLint is opt-in
+    // and absent on most machines, so skip rather than risk a false ENOENT.
+    case "swift-spm":
+    case "swift-xcode":
+    case "unknown":
+      return null;
+  }
+}
+
+/**
+ * Resolve a write-mode auto-fix command for the repo at `dir`, run *before* the
+ * lint check so deterministic formatter drift never reaches CI as a red Lint
+ * job (#691: a PR blocked purely on `biome check` formatter rules in new test
+ * files that the daemon's warn-only lint step let through). Toolchain-agnostic:
+ * it runs whatever auto-fixer the repo declares, preferring `lint:fix` (the
+ * write-mode of a `biome check` / `eslint` lint gate) over `format`. Returns
+ * `null` when the repo declares neither (or isn't Node) — the caller skips
+ * silently. Best-effort by contract: the lint *check* still runs afterwards and
+ * reports whatever the fixer left behind, so this never substitutes for lint.
+ */
+export function formatFixCommand(dir: string): ToolchainCommand | null {
+  if (detect(dir).kind !== "node") return null;
+  const script = firstNodeScript(dir, ["lint:fix", "format"]);
+  if (!script) return null;
+  const [cmd, args] = spawnRunArgs(script);
+  return { cmd, args };
+}
+
+/**
+ * Resolve the test command for the repo at `dir`, or `null` when the repo has
+ * no runnable suite (caller must skip-and-warn, never fail the card — #688).
+ *
+ * Unlike build/lint, a missing test step is the *normal* case for many repos,
+ * so Node resolution reads `package.json` and only returns a command when a
+ * real `test` script exists — running `<pm> run test` against a repo without
+ * one would fail the card on a missing script rather than on a real regression.
+ */
+export function testCommand(dir: string): ToolchainCommand | null {
+  const pt = detect(dir);
+  switch (pt.kind) {
+    case "node": {
+      if (!hasNodeTestScript(dir)) return null;
+      const [cmd, args] = spawnRunArgs("test");
+      return { cmd, args };
+    }
+    case "swift-spm":
+      return { cmd: "swift", args: ["test"] };
+    // `xcodebuild test` needs a booted simulator destination (and often
+    // signing) that a headless verify pass can't assume. Skip rather than
+    // fail the card on an environment problem — same contract as lint.
+    case "swift-xcode":
+    case "unknown":
+      return null;
+  }
+}
+
+/** The `npm init` placeholder — present but not a suite. Treat as no tests. */
+const NPM_PLACEHOLDER_TEST = /no test specified/i;
+
+function hasNodeTestScript(dir: string): boolean {
+  let script: unknown;
+  try {
+    const pkg = JSON.parse(readFileSync(`${dir}/package.json`, "utf-8")) as {
+      scripts?: Record<string, string>;
+    };
+    script = pkg.scripts?.test;
+  } catch (err) {
+    log.warn(
+      TAG,
+      `Could not read package.json in ${dir}: ${err instanceof Error ? err.message : err}`,
+    );
+    return false;
+  }
+
+  if (typeof script !== "string" || script.trim().length === 0) return false;
+  if (NPM_PLACEHOLDER_TEST.test(script)) {
+    log.info(
+      TAG,
+      `package.json 'test' is the npm placeholder — skipping tests`,
+    );
+    return false;
+  }
+  return true;
+}
+
+/**
+ * First of `candidates` that names a real, non-empty script in the repo's
+ * `package.json`. Returns `null` when none match or the manifest can't be read.
+ */
+function firstNodeScript(dir: string, candidates: string[]): string | null {
+  let scripts: Record<string, string>;
+  try {
+    const pkg = JSON.parse(readFileSync(`${dir}/package.json`, "utf-8")) as {
+      scripts?: Record<string, string>;
+    };
+    scripts = pkg.scripts ?? {};
+  } catch (err) {
+    log.warn(
+      TAG,
+      `Could not read package.json in ${dir}: ${err instanceof Error ? err.message : err}`,
+    );
+    return null;
+  }
+
+  for (const name of candidates) {
+    const script = scripts[name];
+    if (typeof script === "string" && script.trim().length > 0) return name;
+  }
+  return null;
+}
+
+/**
+ * Whether the repo supports the web dev-server deep review. Only Node repos
+ * boot a `dev` server on a port the reviewer can probe over HTTP.
+ */
+export function supportsDevServer(dir: string): boolean {
+  return detect(dir).kind === "node";
+}
+
+function xcodeBuildCommand(pt: ProjectType): ToolchainCommand | null {
+  const container = pt.xcodeContainer;
+  if (!container) return null;
+
+  const scheme = resolveXcodeScheme(pt);
+  if (!scheme) {
+    log.warn(
+      TAG,
+      "Could not resolve an Xcode scheme — skipping build (best-effort)",
+    );
+    return null;
+  }
+
+  const containerFlag = pt.xcodeIsWorkspace ? "-workspace" : "-project";
+  return {
+    cmd: "xcodebuild",
+    args: [
+      containerFlag,
+      container,
+      "-scheme",
+      scheme,
+      // Build for a generic iOS device — no simulator/signing needed for a
+      // compile-only verification pass.
+      "-destination",
+      "generic/platform=iOS",
+      "CODE_SIGNING_ALLOWED=NO",
+      "build",
+    ],
+  };
+}
+
+/**
+ * Resolve the first build scheme from `xcodebuild -list -json`. Best-effort:
+ * if xcodebuild is missing or the listing fails, return `null` so the caller
+ * skips the build instead of failing the card.
+ */
+function resolveXcodeScheme(pt: ProjectType): string | null {
+  if (!pt.xcodeContainer) return null;
+  const flag = pt.xcodeIsWorkspace ? "-workspace" : "-project";
+  try {
+    const out = execFileSync(
+      "xcodebuild",
+      ["-list", "-json", flag, pt.xcodeContainer],
+      { encoding: "utf-8", timeout: 30_000, stdio: "pipe" },
+    );
+    const parsed = JSON.parse(out) as {
+      workspace?: { schemes?: string[] };
+      project?: { schemes?: string[] };
+    };
+    const schemes = pt.xcodeIsWorkspace
+      ? (parsed.workspace?.schemes ?? [])
+      : (parsed.project?.schemes ?? []);
+    return schemes[0] ?? null;
+  } catch (err) {
+    log.warn(
+      TAG,
+      `xcodebuild -list failed: ${err instanceof Error ? err.message : err}`,
+    );
+    return null;
+  }
+}

package/src/revert-guard.ts

@@ -0,0 +1,99 @@
+import { execFileSync } from "node:child_process";
+import { log } from "./log.js";
+
+const TAG = "revert-guard";
+
+/**
+ * Pre-Review guardrail against an implement branch silently reverting
+ * already-merged work (card #408).
+ *
+ * The classic failure mode: a branch built on a stale base (or an agent that
+ * resolved a conflict by keeping its own side) drops commits that landed on
+ * main — most damagingly the regression tests those commits added. Deleting a
+ * bound test removes the very safety net that would catch the regression, so a
+ * branch that deletes a test file relative to *current* main is treated as a
+ * likely accidental revert and blocked before it reaches Review.
+ *
+ * This is intentionally conservative: it flags only DELETED test files (not
+ * reverted hunks of source), which has a near-zero legitimate rate for an agent
+ * implementing a card. Broader reverted-hunk detection is deliberately deferred
+ * (noisier; needs per-commit analysis).
+ */
+
+/** Matches test/spec files across the common JS/TS conventions. */
+const TEST_FILE = /(?:^|\/)__tests__\/|\.(?:test|spec)\.[cm]?[jt]sx?$/;
+
+/** True when a repo-relative path names a test/spec file. */
+export function isTestFile(path: string): boolean {
+  return TEST_FILE.test(path);
+}
+
+/**
+ * Filter a list of repo-relative paths down to the test/spec files. Pure
+ * helper, split out so the classification is unit-testable without git.
+ */
+export function filterTestFiles(paths: string[]): string[] {
+  return paths.filter(isTestFile);
+}
+
+/**
+ * Re-fetch the base branch so the deleted-file comparison runs against the
+ * CURRENT remote tip, not whatever was last fetched at worktree creation.
+ * Best-effort — a fetch failure here only weakens the guard, it must not crash
+ * verification (the worktree-creation fetch is the authoritative freshness gate).
+ */
+function refetchBase(worktreePath: string, baseBranch: string): void {
+  try {
+    execFileSync("git", ["fetch", "origin", baseBranch], {
+      cwd: worktreePath,
+      stdio: "pipe",
+    });
+  } catch {
+    log.warn(
+      TAG,
+      "Failed to re-fetch base for revert guard — using last fetch",
+    );
+  }
+}
+
+/**
+ * Files DELETED by the branch relative to the (re-fetched) base tip.
+ * `--diff-filter=D` selects deletions only; the three-dot range compares the
+ * branch tip against the merge-base with the base, so unrelated deletions that
+ * happened on main don't count.
+ */
+export function listDeletedFilesAgainstBase(
+  worktreePath: string,
+  baseBranch: string,
+): string[] {
+  try {
+    const out = execFileSync(
+      "git",
+      ["diff", "--diff-filter=D", "--name-only", `origin/${baseBranch}...HEAD`],
+      { cwd: worktreePath, encoding: "utf-8" },
+    );
+    return out
+      .split("\n")
+      .map((l) => l.trim())
+      .filter((l) => l.length > 0);
+  } catch (err) {
+    log.warn(
+      TAG,
+      `Failed to list deleted files: ${err instanceof Error ? err.message : err}`,
+    );
+    return [];
+  }
+}
+
+/**
+ * Returns the test files the branch deletes relative to current main. A
+ * non-empty result means the branch likely reverted merged work and should be
+ * blocked before Review. Re-fetches the base first so the comparison is fresh.
+ */
+export function findDeletedTestFiles(
+  worktreePath: string,
+  baseBranch: string,
+): string[] {
+  refetchBase(worktreePath, baseBranch);
+  return filterTestFiles(listDeletedFilesAgainstBase(worktreePath, baseBranch));
+}

package/src/review-types.ts

@@ -0,0 +1,52 @@
+/**
+ * The `ReviewResult` family — pure data shapes for a code-review verdict.
+ *
+ * These types are produced by the daemon's `review-completion.ts` (which parses a
+ * review run's structured output) and consumed by the motor's `gate-collectors.ts`
+ * (which reads a `ReviewResult` to build `review_passed` gate evidence). Moving
+ * `review-completion.ts` itself into the motor is not possible — it also imports
+ * `board-helpers`, `completion`, `episode-writer`, `git-pr`, `state-store`, `types`,
+ * and `worktree`, all daemon-only, and the dependency direction is
+ * agent → harness → shared. So the type declarations move here (pure data, no
+ * daemon dependency) and the daemon's `review-completion.ts` imports them back
+ * from `@gethmy/harness` — same pattern used for `PlaybookMetricDef` in
+ * `exec-types.ts`: one definition, the daemon imports it, no duplication.
+ */
+
+export interface ReviewFinding {
+  severity: "critical" | "major" | "minor";
+  title: string;
+  description: string;
+  category?: string;
+  location?: string;
+  /**
+   * Whether the change under review introduced/exposed this issue (true) or it
+   * is a pre-existing issue the reviewer happened to notice (false). Only
+   * diff-caused findings gate the verdict (#478). Absent ⇒ treated as true (the
+   * verdict-leaning default).
+   */
+  relatedToDiff?: boolean;
+}
+
+export interface ScopeCheck {
+  status: "clean" | "drift" | "missing";
+  notes?: string;
+}
+
+/**
+ * One verified acceptance criterion: a requirement or subtask the reviewer
+ * checked against the diff. `fail`/`partial` are hard verdict gates (#478).
+ */
+export interface AcceptanceCheck {
+  criterion: string;
+  status: "pass" | "partial" | "fail" | "unverifiable";
+  evidence?: string;
+}
+
+export interface ReviewResult {
+  verdict: "approved" | "rejected" | "error";
+  summary: string;
+  scopeCheck?: ScopeCheck;
+  acceptanceChecks?: AcceptanceCheck[];
+  findings: ReviewFinding[];
+}