@jaybeeuu/agent-cortex 2.6.0 → 2.8.0

package/extensions/post-merge-watch/index.ts

@@ -0,0 +1,123 @@
+/**
+ * Post-merge watch extension.
+ *
+ * A human merges the feature PR, and the CI run for the merge commit decides
+ * what happens next. Nothing tells the agent when that run concludes: the merge
+ * happens outside the session, and by the time the run settles the agent is idle.
+ * This extension makes the session wake up with the verdict.
+ *
+ * It polls the deterministic check script
+ * (`skills/workflow/ralph/scripts/post-merge-check.mjs`) on a timer and, when the
+ * script reports a verdict, sends one follow-up message — `deliverAs:
+ * "followUp"`, `triggerTurn: true` — so an idle session starts a turn with the
+ * result. The script owns the verdict; this extension runs it and forwards the
+ * exit code. It makes no model call.
+ *
+ * Opt-in per session through the `--post-merge-watch <bead>` flag. State lives
+ * under `~/.pi/agent-cortex/post-merge-watch/`, one file per project and bead,
+ * and is removed when the watch settles or the session shuts down.
+ */
+
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+import { PostMergeWatch, DEFAULT_INTERVAL_MS, DEFAULT_MAX_ATTEMPTS } from "./watch.ts";
+import type { CheckRun, CheckInvocation, WakeMessage } from "./watch.ts";
+
+/** The CLI flag that starts a watch: `--post-merge-watch <bead>`. */
+export const WATCH_FLAG = "post-merge-watch";
+
+/**
+ * Environment override for the check script path. The default resolves against
+ * this module, so the staged pi package (`extensions/` beside `skills/`) and a
+ * checkout of this repository both find the shipped script without a hardcoded
+ * absolute path.
+ */
+export const CHECK_SCRIPT_ENV = "AGENT_CORTEX_POST_MERGE_CHECK";
+
+/** The check script's location in a staged install and in this repository. */
+const DEFAULT_CHECK_SCRIPT = new URL(
+  "../../skills/workflow/ralph/scripts/post-merge-check.mjs",
+  import.meta.url,
+);
+
+/** How long one check invocation may take before pi kills it. */
+const CHECK_TIMEOUT_MS = 120_000;
+
+/** The state directory, under the agent-cortex global area, never in the project. */
+export function stateDir(): string {
+  return join(homedir(), ".pi", "agent-cortex", "post-merge-watch");
+}
+
+/** The check script this extension polls. */
+export function checkScript(): string {
+  const override = process.env[CHECK_SCRIPT_ENV];
+  return override !== undefined && override !== "" ? override : fileURLToPath(DEFAULT_CHECK_SCRIPT);
+}
+
+export default function postMergeWatchExtension(pi: ExtensionAPI): void {
+  // Registered here, in the factory: pi matches parsed CLI flags against the
+  // extensions loaded at startup, so a flag registered from `session_start` is
+  // rejected as an unknown option.
+  pi.registerFlag(WATCH_FLAG, {
+    description: "Watch the post-merge check for a bead and wake the session with the verdict",
+    type: "string",
+  });
+
+  /** One watch per bead, so a reloaded session does not start a second one. */
+  const watches = new Map<string, PostMergeWatch>();
+
+  const runCheck = async (invocation: CheckInvocation): Promise<CheckRun> => {
+    const result = await pi.exec(process.execPath, [invocation.script, ...invocation.args], {
+      cwd: invocation.cwd,
+      timeout: CHECK_TIMEOUT_MS,
+    });
+    return { code: result.code, stdout: result.stdout, stderr: result.stderr, killed: result.killed };
+  };
+
+  /**
+   * The verdict goes out as a follow-up message with `triggerTurn`, so a session
+   * that is idle starts a turn and one that is busy reads it after the turn in
+   * progress instead of interrupting it.
+   */
+  const deliver = (message: WakeMessage): void => {
+    pi.sendMessage(message, { deliverAs: "followUp", triggerTurn: true });
+  };
+
+  const watchedBead = (): string | undefined => {
+    const value = pi.getFlag(WATCH_FLAG);
+    return typeof value === "string" && value.trim() !== "" ? value.trim() : undefined;
+  };
+
+  pi.on("session_start", async (_event, ctx) => {
+    for (const [bead, watch] of watches) {
+      if (!watch.active) watches.delete(bead);
+    }
+
+    const bead = watchedBead();
+    if (bead === undefined || watches.has(bead)) return;
+
+    const watch = new PostMergeWatch({
+      bead,
+      project: ctx.cwd,
+      script: checkScript(),
+      stateDir: stateDir(),
+      runCheck,
+      deliver,
+      intervalMs: DEFAULT_INTERVAL_MS,
+      maxAttempts: DEFAULT_MAX_ATTEMPTS,
+      warn: (message) => ctx.ui.notify(message, "warning"),
+    });
+
+    watches.set(bead, watch);
+    await watch.start();
+  });
+
+  pi.on("session_shutdown", async () => {
+    const stopping = [...watches.values()].map((watch) => watch.stop());
+    watches.clear();
+    await Promise.all(stopping);
+  });
+}

package/extensions/post-merge-watch/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@agent-cortex/post-merge-watch",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "test": "node --test --import tsx/esm watch.test.ts index.test.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^1.5.2",
+    "@types/node": "^22.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.0.0"
+  }
+}

package/extensions/post-merge-watch/watch.test.ts

@@ -0,0 +1,469 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { readFile, stat } from "node:fs/promises";
+import { join } from "node:path";
+
+import { createTempRoot } from "../../test/helpers/temp-root.mjs";
+import {
+  PostMergeWatch,
+  buildWake,
+  readVerdict,
+  stateFileFor,
+  verdictOf,
+  WAKE_CUSTOM_TYPE,
+} from "./watch.ts";
+import type { CheckRun, Scheduler, WakeMessage, WatchState } from "./watch.ts";
+
+// ─── Fixtures ────────────────────────────────────────────────────────────────
+
+const tempRoot = createTempRoot("post-merge-watch-");
+
+/** The JSON the real check script prints, cut down to the fields the watch reads. */
+function report({ reason, runUrl }: { reason: string; runUrl?: string }): string {
+  return JSON.stringify({
+    outcome: reason,
+    reason,
+    runs: runUrl === undefined ? [] : [{ databaseId: 1, url: runUrl, status: "completed" }],
+  });
+}
+
+function run(code: number, stdout = ""): CheckRun {
+  return { code, stdout, stderr: "", killed: false };
+}
+
+/**
+ * A scheduler the test steps by hand: nothing fires on its own, and `fire()`
+ * awaits the poll it triggers, so no test sleeps or polls for async work.
+ */
+function createStepScheduler() {
+  let pending: Array<() => void | Promise<void>> = [];
+  let clock = Date.parse("2026-01-01T00:00:00.000Z");
+
+  const scheduler: Scheduler = {
+    now: () => new Date(clock),
+    schedule: (callback) => {
+      pending.push(callback);
+      return () => {
+        pending = pending.filter((queued) => queued !== callback);
+      };
+    },
+  };
+
+  return {
+    scheduler,
+    /** How many timers are waiting. Zero means no orphan. */
+    pending: () => pending.length,
+    /** Run the waiting timer and await the poll it starts. */
+    async fire(): Promise<void> {
+      const [next, ...rest] = pending;
+      pending = rest;
+      await next?.();
+      clock += 15_000;
+    },
+  };
+}
+
+/**
+ * A stepped scheduler that runs `onClockRead` before it returns the time.
+ *
+ * Both `start()` and `#writeState` read the clock before the file write reaches
+ * the filesystem, so a watch stopped from `onClockRead` stops with its write
+ * still to run: the remove lands inside the write window on every run, with no
+ * sleep and no dependence on I/O timing.
+ */
+function createWriteWindowScheduler(onClockRead: () => void) {
+  const step = createStepScheduler();
+  const scheduler: Scheduler = {
+    now: () => {
+      onClockRead();
+      return step.scheduler.now();
+    },
+    schedule: (callback, delayMs) => step.scheduler.schedule(callback, delayMs),
+  };
+
+  return { scheduler, step };
+}
+
+/** A watch over one project and bead, with only the values a test cares about set. */
+function createWatch(overrides: {
+  runs: CheckRun[];
+  stateDir: string;
+  project?: string;
+  bead?: string;
+  maxAttempts?: number;
+}) {
+  const step = createStepScheduler();
+  const deliveries: WakeMessage[] = [];
+  const warnings: string[] = [];
+  const scripted = [...overrides.runs];
+
+  const watch = new PostMergeWatch({
+    bead: overrides.bead ?? "agnt-ctx-86u4.2",
+    project: overrides.project ?? "/projects/one",
+    script: "/agent-cortex/skills/workflow/ralph/scripts/post-merge-check.mjs",
+    stateDir: overrides.stateDir,
+    maxAttempts: overrides.maxAttempts,
+    scheduler: step.scheduler,
+    runCheck: async () => {
+      const next = scripted.shift();
+      if (next === undefined) throw new Error("no scripted run left");
+      return next;
+    },
+    deliver: (message) => deliveries.push(message),
+    warn: (message) => warnings.push(message),
+  });
+
+  return { watch, step, deliveries, warnings };
+}
+
+/** Read a state file the watch wrote, as data. */
+async function readState(path: string): Promise<WatchState> {
+  return JSON.parse(await readFile(path, "utf-8")) as WatchState;
+}
+
+// ─── Verdict ─────────────────────────────────────────────────────────────────
+
+describe("readVerdict", () => {
+  it("takes the verdict from the exit code, not from the report body", () => {
+    const verdict = readVerdict(run(1, report({ reason: "run-failed", runUrl: "https://gh/run/9" })));
+
+    assert.equal(verdict.verdict, "failed");
+    assert.equal(verdict.exitCode, 1);
+    assert.equal(verdict.runUrl, "https://gh/run/9");
+  });
+
+  it("reads a killed run as inconclusive, whatever its partial output says", () => {
+    const verdict = readVerdict({ code: 143, stdout: "", stderr: "", killed: true });
+
+    assert.equal(verdict.verdict, "inconclusive");
+    assert.equal(verdict.reason, "check-timed-out");
+    assert.equal(verdict.runUrl, undefined);
+  });
+
+  it("reads an unreadable report as inconclusive without inventing a run", () => {
+    const verdict = readVerdict(run(2, "gh: not logged in"));
+
+    assert.deepEqual(
+      { verdict: verdict.verdict, reason: verdict.reason, runUrl: verdict.runUrl },
+      { verdict: "inconclusive", reason: "unreadable-report", runUrl: undefined },
+    );
+  });
+
+  it("maps every non-zero, non-one exit code to inconclusive", () => {
+    assert.deepEqual([0, 1, 2, 127, 143].map(verdictOf), [
+      "passed",
+      "failed",
+      "inconclusive",
+      "inconclusive",
+      "inconclusive",
+    ]);
+  });
+});
+
+// ─── Wake payload ────────────────────────────────────────────────────────────
+
+describe("buildWake", () => {
+  it("names the bead, the verdict and the run URL", () => {
+    const wake = buildWake({
+      bead: "agnt-ctx-86u4.2",
+      verdict: "failed",
+      runUrl: "https://github.com/o/r/actions/runs/9",
+      exitCode: 1,
+      reason: "run-failed",
+      attempts: 3,
+      project: "/projects/one",
+    });
+
+    assert.equal(wake.customType, WAKE_CUSTOM_TYPE);
+    assert.equal(wake.display, true);
+    assert.match(wake.content, /agnt-ctx-86u4\.2/);
+    assert.match(wake.content, /Verdict: failed/);
+    assert.match(wake.content, /https:\/\/github\.com\/o\/r\/actions\/runs\/9/);
+    assert.deepEqual(wake.details, {
+      bead: "agnt-ctx-86u4.2",
+      verdict: "failed",
+      runUrl: "https://github.com/o/r/actions/runs/9",
+      exitCode: 1,
+      reason: "run-failed",
+      attempts: 3,
+      project: "/projects/one",
+    });
+  });
+
+  it("says no run was reported rather than leaving the line empty", () => {
+    const wake = buildWake({
+      bead: "agnt-ctx-86u4.2",
+      verdict: "inconclusive",
+      runUrl: null,
+      exitCode: 2,
+      reason: "no-run",
+      attempts: 40,
+      project: "/projects/one",
+    });
+
+    assert.match(wake.content, /Run: none reported/);
+  });
+});
+
+// ─── Watch lifecycle ─────────────────────────────────────────────────────────
+
+describe("PostMergeWatch", () => {
+  it("polls while the run is in progress and wakes once when the verdict lands", async () => {
+    const stateDir = join(await tempRoot.createWorkspace(), "state");
+    const { watch, step, deliveries } = createWatch({
+      stateDir,
+      runs: [
+        run(2, report({ reason: "still-running" })),
+        run(2, report({ reason: "still-running" })),
+        run(1, report({ reason: "run-failed", runUrl: "https://gh/run/9" })),
+      ],
+    });
+
+    await watch.start();
+    await step.fire();
+    await step.fire();
+
+    assert.equal(deliveries.length, 1);
+    assert.deepEqual(deliveries[0].details, {
+      bead: "agnt-ctx-86u4.2",
+      verdict: "failed",
+      runUrl: "https://gh/run/9",
+      exitCode: 1,
+      reason: "run-failed",
+      attempts: 3,
+      project: "/projects/one",
+    });
+    assert.equal(step.pending(), 0);
+    assert.equal(watch.active, false);
+    await assert.rejects(stat(watch.stateFile), "a watch that settled on a verdict leaves no state file");
+  });
+
+  it("gives up at the attempt cap and reports an inconclusive verdict", async () => {
+    const stateDir = join(await tempRoot.createWorkspace(), "state");
+    const inProgress = run(2, report({ reason: "still-running" }));
+    const { watch, step, deliveries } = createWatch({
+      stateDir,
+      maxAttempts: 3,
+      runs: [inProgress, inProgress, inProgress, inProgress],
+    });
+
+    await watch.start();
+    await step.fire();
+    await step.fire();
+
+    assert.equal(deliveries.length, 1);
+    assert.deepEqual(
+      {
+        verdict: deliveries[0].details.verdict,
+        reason: deliveries[0].details.reason,
+        runUrl: deliveries[0].details.runUrl,
+        attempts: deliveries[0].details.attempts,
+      },
+      { verdict: "inconclusive", reason: "still-running", runUrl: null, attempts: 3 },
+    );
+    assert.equal(step.pending(), 0);
+    await assert.rejects(
+      stat(watch.stateFile),
+      "a watch that settled on the attempt cap leaves no state file",
+    );
+  });
+
+  it("keeps polling when the check script cannot run, then reports inconclusive", async () => {
+    const stateDir = join(await tempRoot.createWorkspace(), "state");
+    const step = createStepScheduler();
+    const deliveries: WakeMessage[] = [];
+    const warnings: string[] = [];
+
+    const watch = new PostMergeWatch({
+      bead: "agnt-ctx-86u4.2",
+      project: "/projects/one",
+      script: "/missing/post-merge-check.mjs",
+      stateDir,
+      maxAttempts: 2,
+      scheduler: step.scheduler,
+      runCheck: async () => {
+        throw new Error("spawn ENOENT");
+      },
+      deliver: (message) => deliveries.push(message),
+      warn: (message) => warnings.push(message),
+    });
+
+    await watch.start();
+    await step.fire();
+
+    assert.equal(deliveries.length, 1);
+    assert.equal(deliveries[0].details.verdict, "inconclusive");
+    assert.equal(deliveries[0].details.reason, "no-report");
+    assert.match(warnings.join("\n"), /spawn ENOENT/);
+  });
+
+  it("records one state file per project and bead, and removes only the stopped watch's", async () => {
+    const stateDir = join(await tempRoot.createWorkspace(), "state");
+    const inProgress = () => [run(2, report({ reason: "still-running" }))];
+    const sameBeadOtherProject = createWatch({ stateDir, project: "/projects/two", runs: inProgress() });
+    const otherBeadSameProject = createWatch({ stateDir, bead: "agnt-ctx-other.1", runs: inProgress() });
+
+    const first = createWatch({ stateDir, runs: inProgress() });
+    await first.watch.start();
+    await sameBeadOtherProject.watch.start();
+    await otherBeadSameProject.watch.start();
+
+    const paths = [
+      first.watch.stateFile,
+      sameBeadOtherProject.watch.stateFile,
+      otherBeadSameProject.watch.stateFile,
+    ];
+    assert.equal(new Set(paths).size, 3, "one file per project and bead");
+    assert.deepEqual(
+      { bead: (await readState(paths[0])).bead, project: (await readState(paths[0])).project },
+      { bead: "agnt-ctx-86u4.2", project: "/projects/one" },
+    );
+    assert.deepEqual(
+      { bead: (await readState(paths[1])).bead, project: (await readState(paths[1])).project },
+      { bead: "agnt-ctx-86u4.2", project: "/projects/two" },
+    );
+
+    await first.watch.stop();
+
+    await assert.rejects(stat(paths[0]), "a settled watch leaves no state file");
+    assert.equal((await stat(paths[1])).isFile(), true, "another project's watch is untouched");
+
+    await Promise.all([sameBeadOtherProject.watch.stop(), otherBeadSameProject.watch.stop()]);
+  });
+
+  it("stops polling and removes its state file when the session shuts down", async () => {
+    const stateDir = join(await tempRoot.createWorkspace(), "state");
+    const { watch, step, deliveries } = createWatch({
+      stateDir,
+      runs: [run(2, report({ reason: "still-running" }))],
+    });
+
+    await watch.start();
+    const stateFile = watch.stateFile;
+    assert.equal((await readState(stateFile)).attempts, 1);
+
+    await watch.stop();
+
+    await assert.rejects(stat(stateFile));
+    assert.equal(step.pending(), 0);
+    assert.equal(watch.active, false);
+    assert.deepEqual(deliveries, []);
+  });
+
+  it("removes the state file when the session stops before the first write lands", async () => {
+    const stateDir = join(await tempRoot.createWorkspace(), "state");
+    const deliveries: WakeMessage[] = [];
+    let armed = true;
+    let stopping: Promise<void> = Promise.resolve();
+    let watch: PostMergeWatch;
+
+    const { scheduler, step } = createWriteWindowScheduler(() => {
+      if (!armed) return;
+      armed = false;
+      stopping = watch.stop();
+    });
+
+    watch = new PostMergeWatch({
+      bead: "agnt-ctx-86u4.2",
+      project: "/projects/one",
+      script: "/agent-cortex/skills/workflow/ralph/scripts/post-merge-check.mjs",
+      stateDir,
+      scheduler,
+      runCheck: async () => run(2, report({ reason: "still-running" })),
+      deliver: (message) => deliveries.push(message),
+    });
+
+    const starting = watch.start();
+    await stopping; // the remove lands before the write it is racing with
+    await starting;
+
+    await assert.rejects(
+      stat(watch.stateFile),
+      "a watch stopped before its first state write lands leaves no state file",
+    );
+    assert.equal(step.pending(), 0);
+    assert.deepEqual(deliveries, []);
+  });
+
+  it("removes the state file and schedules nothing when the session stops during a poll's write", async () => {
+    const stateDir = join(await tempRoot.createWorkspace(), "state");
+    const deliveries: WakeMessage[] = [];
+    let armed = false;
+    let stopping: Promise<void> = Promise.resolve();
+    let watch: PostMergeWatch;
+
+    const { scheduler, step } = createWriteWindowScheduler(() => {
+      if (!armed) return;
+      armed = false;
+      stopping = watch.stop();
+    });
+
+    watch = new PostMergeWatch({
+      bead: "agnt-ctx-86u4.2",
+      project: "/projects/one",
+      script: "/agent-cortex/skills/workflow/ralph/scripts/post-merge-check.mjs",
+      stateDir,
+      scheduler,
+      runCheck: async () => run(2, report({ reason: "still-running" })),
+      deliver: (message) => deliveries.push(message),
+    });
+
+    await watch.start();
+    armed = true;
+    await step.fire(); // the poll's state write reads the clock, so stop() lands inside it
+    await stopping;
+
+    await assert.rejects(
+      stat(watch.stateFile),
+      "a watch stopped during a poll's state write leaves no state file",
+    );
+    assert.equal(step.pending(), 0, "a stopped watch schedules no further check");
+    assert.deepEqual(deliveries, []);
+  });
+
+  it("does not wake a session that stopped while a check was in flight", async () => {
+    const stateDir = join(await tempRoot.createWorkspace(), "state");
+    const step = createStepScheduler();
+    const deliveries: WakeMessage[] = [];
+    const gate = createDeferred<CheckRun>();
+
+    const watch = new PostMergeWatch({
+      bead: "agnt-ctx-86u4.2",
+      project: "/projects/one",
+      script: "/agent-cortex/skills/workflow/ralph/scripts/post-merge-check.mjs",
+      stateDir,
+      scheduler: step.scheduler,
+      runCheck: () => gate.promise,
+      deliver: (message) => deliveries.push(message),
+    });
+
+    const starting = watch.start();
+    await watch.stop();
+    gate.resolve(run(1, report({ reason: "run-failed", runUrl: "https://gh/run/9" })));
+    await starting;
+
+    assert.deepEqual(deliveries, []);
+    await assert.rejects(stat(watch.stateFile));
+  });
+});
+
+describe("stateFileFor", () => {
+  it("keeps two projects that share a directory name apart", () => {
+    const stateDir = "/state";
+    const left = stateFileFor(stateDir, "/work/one/project", "agnt-ctx-86u4.2");
+    const right = stateFileFor(stateDir, "/work/two/project", "agnt-ctx-86u4.2");
+
+    assert.notEqual(left, right);
+    assert.match(left, /agnt-ctx-86u4\.2/);
+    assert.equal(stateFileFor(stateDir, "/work/one/project", "agnt-ctx-86u4.2"), left);
+  });
+});
+
+/** A promise the test settles itself, so an in-flight check can be held open. */
+function createDeferred<T>() {
+  let settle: (value: T) => void = () => {};
+  const promise = new Promise<T>((resolve) => {
+    settle = resolve;
+  });
+  return { promise, resolve: settle };
+}