@ianwremmel/dispatch 0.32.1-bootstrap.0

package/src/lib/watch/cadence.mts

@@ -0,0 +1,45 @@
+import type {PrSnapshot} from './snapshot.mts';
+
+/**
+ * How long to wait before reading a PR again, derived from where the PR
+ * actually is rather than from a reason the worker declared.
+ *
+ * A worker cannot reliably say what it is waiting for — it may be waiting for
+ * several things at once, and whatever it declared goes stale the moment the
+ * PR moves. The PR's own state is the better signal and the server already
+ * has it, which is also what makes the interval data-driven rather than a
+ * constant table.
+ */
+export const CADENCE_SECONDS = {
+  /** Checks are running: the next transition is close. */
+  ciActive: 60,
+  /** Checks have reported and someone must look: a person's timescale. */
+  awaitingReview: 300,
+  /** Nothing is pending; watch only for an out-of-band change. */
+  idle: 900,
+} as const;
+
+export function cadenceFor(snapshot: PrSnapshot | null): number {
+  if (snapshot === null) return CADENCE_SECONDS.ciActive;
+  if (snapshot.checks.some((check) => check.conclusion === null)) {
+    return CADENCE_SECONDS.ciActive;
+  }
+  // Out of draft with the forge still asking for review, or a reviewer who
+  // has not returned a verdict.
+  const awaiting =
+    !snapshot.draft &&
+    (snapshot.reviewDecision === 'REVIEW_REQUIRED' ||
+      snapshot.reviews.some((review) => review.state === 'PENDING'));
+  return awaiting ? CADENCE_SECONDS.awaitingReview : CADENCE_SECONDS.idle;
+}
+
+/**
+ * How long a watch runs before firing regardless of the diff. The snapshot
+ * sees only the forge, so an approval given on the ticket or a reaction never
+ * reaches it; expiry sends the worker to look for itself.
+ *
+ * Measured from arming, never from the last poll: a deadline a poll can push
+ * out is one a quiet PR never reaches, and a quiet PR is the only kind that
+ * needs it. The price is a wasted look at every unchanged PR once a window.
+ */
+export const EXPIRY_SECONDS = 21_600;

package/src/lib/watch/diff.mts

@@ -0,0 +1,274 @@
+import type {PrSnapshot} from './snapshot.mts';
+
+/**
+ * Event kinds, four of them the channel-server event catalog's PR/CI triggers.
+ *
+ * `pr_conflicted` and `pr_head_changed` are additions: the catalog has no
+ * event for "the base moved and this no longer merges" or "someone else
+ * pushed to the branch", and a worker waiting on merge must react to both.
+ * Adding kinds is allowed; renaming the catalog's four would be breaking.
+ */
+export const OBSERVATION_KINDS = [
+  'ci_finished',
+  'pr_review',
+  'pr_comment',
+  'pr_state_change',
+  'pr_conflicted',
+  'pr_head_changed',
+  // Not a PR observation: written by `ticket set` when a tracker write
+  // reveals a status transition. Same queue, same delivery.
+  'ticket_changed',
+  // Also not a diff: written when a watch reaches its deadline. It reports
+  // that nothing the snapshot can see changed, which is the one thing a diff
+  // can never say — and the signal it stands in for (an approval on the
+  // ticket, a reaction, a go-ahead out of band) is outside the forge.
+  'watch_expired',
+] as const;
+export type ObservationKind = (typeof OBSERVATION_KINDS)[number];
+
+export interface Observation {
+  readonly kind: ObservationKind;
+  /**
+   * Per-kind channel meta, beyond the `repo`/`pr` the pusher adds. Values are
+   * stringified at push time; the runner drops a non-string.
+   */
+  readonly meta: Readonly<Record<string, string>>;
+  /** One line for a human reading the log. The pushed body is `pr-status`. */
+  readonly summary: string;
+}
+
+/**
+ * Check conclusions that mean "this check is OK". Anything terminal and not
+ * in this set counts as a failure, so a conclusion GitHub adds later reads as
+ * failing rather than silently passing.
+ */
+const PASSING = new Set(['SUCCESS', 'NEUTRAL', 'SKIPPED']);
+
+function failing(snapshot: PrSnapshot): string[] {
+  return snapshot.checks
+    .filter(
+      (check) => check.conclusion !== null && !PASSING.has(check.conclusion)
+    )
+    .map((check) => check.name);
+}
+
+function settled(snapshot: PrSnapshot): boolean {
+  return (
+    snapshot.checks.length > 0 &&
+    snapshot.checks.every((check) => check.conclusion !== null)
+  );
+}
+
+/** The forge's word for "this no longer merges cleanly". */
+const CONFLICTED = 'DIRTY';
+
+/**
+ * What changed between two observations of one PR.
+ *
+ * Authorship is judged by this agent's machine marker, never by the account:
+ * under shared credentials the agent posts as the operator, so filtering by
+ * login would suppress the operator's own review — the one signal a waiting
+ * worker most needs. The marker says "this agent wrote it" whatever account
+ * carried it. Waking a worker to report its own comment is the noise that
+ * would make server-side waiting worse than the polling it replaces.
+ *
+ * A null `previous` is the first observation after arming, and yields
+ * nothing. The wait's own condition is evaluated separately by the caller,
+ * which is what catches a change that landed before the baseline was taken.
+ */
+export function diffSnapshots(
+  previous: PrSnapshot | null,
+  next: PrSnapshot
+): Observation[] {
+  if (previous === null) return [];
+  const events: Observation[] = [];
+
+  if (next.merged && !previous.merged) {
+    return [
+      {
+        kind: 'pr_state_change',
+        meta: {state: 'merged'},
+        summary: 'The PR merged.',
+      },
+    ];
+  }
+
+  if (next.state === 'CLOSED' && previous.state !== 'CLOSED') {
+    // Whether a closed-unmerged PR actually shipped is `pr-status`'s call — a
+    // squash or rebase can land the content without setting `merged`. The
+    // event says the lifecycle moved; the body tells the worker which way.
+    return [
+      {
+        kind: 'pr_state_change',
+        meta: {state: 'closed'},
+        summary: 'The PR closed.',
+      },
+    ];
+  }
+
+  if (next.draft !== previous.draft) {
+    events.push({
+      kind: 'pr_state_change',
+      meta: {state: next.draft ? 'draft' : 'ready'},
+      summary: next.draft
+        ? 'The PR went back to draft.'
+        : 'The PR left draft and is ready for review.',
+    });
+  }
+
+  if (next.head !== previous.head && next.head !== null) {
+    events.push({
+      kind: 'pr_head_changed',
+      meta: {head: next.head},
+      summary: `The head commit moved to ${next.head.slice(0, 8)}.`,
+    });
+  }
+
+  // CI is reported per rollup, not per check: `ci_finished` fires when the
+  // rollup reaches a terminal state. Naming the failures in meta is the
+  // detail the rollup verdict alone cannot carry. Comparing the failing set
+  // (not just settled-ness) is what catches a rerun that goes straight from
+  // failing to green between two polls.
+  const nowFailing = failing(next);
+  const rollupChanged =
+    settled(next) &&
+    (!settled(previous) ||
+      failing(previous).join(',') !== nowFailing.join(',') ||
+      previous.head !== next.head);
+  if (rollupChanged) {
+    events.push({
+      kind: 'ci_finished',
+      meta: {
+        rollup: nowFailing.length > 0 ? 'failure' : 'success',
+        ...(nowFailing.length > 0 ? {failing: nowFailing.join(',')} : {}),
+      },
+      summary:
+        nowFailing.length > 0
+          ? `CI finished with failures: ${nowFailing.join(', ')}.`
+          : 'CI finished green.',
+    });
+  }
+
+  // A review is identified by (author, state, submittedAt): a reviewer walks
+  // pending -> verdict, and a re-request pushes them back to pending, so the
+  // author alone cannot tell a new verdict from an old one.
+  const seenReviews = new Set(
+    previous.reviews.map(
+      (review) => `${review.author} ${review.state} ${review.submittedAt ?? ''}`
+    )
+  );
+  for (const review of next.reviews) {
+    const key = `${review.author} ${review.state} ${review.submittedAt ?? ''}`;
+    if (seenReviews.has(key)) continue;
+    if (review.state === 'PENDING' || review.mine) continue;
+    events.push({
+      kind: 'pr_review',
+      meta: {state: reviewState(review.state), reviewer: review.author},
+      summary: `${review.author} left a ${reviewState(review.state)} review.`,
+    });
+  }
+
+  const before = new Map(previous.threads.map((thread) => [thread.id, thread]));
+  for (const thread of next.threads) {
+    const prior = before.get(thread.id);
+    const moved =
+      prior?.lastAt !== thread.lastAt || prior.resolved !== thread.resolved;
+    if (!moved || thread.resolved || thread.mine) continue;
+    events.push({
+      kind: 'pr_comment',
+      meta: {thread: thread.id},
+      summary:
+        prior === undefined
+          ? `${thread.lastAuthor ?? 'someone'} opened a review thread.`
+          : `${thread.lastAuthor ?? 'someone'} replied on a review thread.`,
+    });
+  }
+
+  // An id absent from the previous window is only new when that window held
+  // every comment. Past the cap the older entries fall out, and treating
+  // their reappearance as new would fire on comments from last week.
+  const windowComplete = previous.totals.comments <= previous.comments.length;
+  const known = new Set(previous.comments.map((comment) => comment.id));
+  for (const comment of next.comments) {
+    if (known.has(comment.id) || comment.mine) continue;
+    // Strictly older only. Timestamps are not a unique key, so a comment
+    // sharing the newest one's second would otherwise be dropped for good —
+    // the snapshot advances past it and no later tick can rediscover it.
+    if (!windowComplete && comment.createdAt < newestOf(previous.comments)) {
+      continue;
+    }
+    events.push({
+      kind: 'pr_comment',
+      meta: {thread: comment.id},
+      summary: `${comment.author} commented on the PR.`,
+    });
+  }
+
+  if (next.mergeState === CONFLICTED && previous.mergeState !== CONFLICTED) {
+    events.push({
+      kind: 'pr_conflicted',
+      meta: {mergeState: next.mergeState},
+      summary: 'The PR now conflicts with its base branch.',
+    });
+  }
+
+  return coalesce(events);
+}
+
+function newestOf(comments: PrSnapshot['comments']): string {
+  return comments.reduce(
+    (newest, comment) =>
+      comment.createdAt > newest ? comment.createdAt : newest,
+    ''
+  );
+}
+
+function reviewState(state: string): string {
+  if (state === 'APPROVED') return 'approved';
+  if (state === 'CHANGES_REQUESTED') return 'changes';
+  return 'comment';
+}
+
+/**
+ * Everything one tick saw about one PR, as a single event.
+ *
+ * The alternative — one event per change — interrupts a worker mid-reaction:
+ * it is told CI failed, starts fixing, and is then told a reviewer replied,
+ * which it must handle as a second turn without the first one's context. The
+ * worker already reads one `pr-status` blob per tick and reacts to everything
+ * in it at once; the channel should not be worse than that.
+ *
+ * So the kind is a routing hint — the most significant thing that moved —
+ * `changed` lists every kind that fired, and the per-kind specifics ride
+ * along in meta. The body carries the state the worker acts on.
+ */
+const PRIORITY: readonly ObservationKind[] = [
+  'pr_state_change',
+  'pr_conflicted',
+  'ci_finished',
+  'pr_review',
+  'pr_head_changed',
+  'pr_comment',
+];
+
+function coalesce(events: readonly Observation[]): Observation[] {
+  if (events.length <= 1) return [...events];
+  const ranked = [...events].sort(
+    (a, b) => PRIORITY.indexOf(a.kind) - PRIORITY.indexOf(b.kind)
+  );
+  const [lead] = ranked;
+  if (lead === undefined) return [];
+  const meta: Record<string, string> = {};
+  // Least significant first, so the lead event's own keys win a collision.
+  for (const event of [...ranked].reverse()) {
+    for (const [key, value] of Object.entries(event.meta)) meta[key] = value;
+  }
+  meta.changed = [...new Set(ranked.map((event) => event.kind))].join(',');
+  return [
+    {
+      kind: lead.kind,
+      meta,
+      summary: ranked.map((event) => event.summary).join(' '),
+    },
+  ];
+}

package/src/lib/watch/index.mts

@@ -0,0 +1,11 @@
+export {armWatch} from './arm.mts';
+export {diffSnapshots, OBSERVATION_KINDS} from './diff.mts';
+export type {Observation, ObservationKind} from './diff.mts';
+export {pollWatches} from './poll.mts';
+export {githubSnapshot, SNAPSHOT_QUERY} from './snapshot.mts';
+export type {PrSnapshot, Snapshotter} from './snapshot.mts';
+export {AGENT_ID, writtenByThisAgent} from './marker.mts';
+export {prStatusPayload, prStatusScript} from './payload.mts';
+export {cadenceFor, CADENCE_SECONDS, EXPIRY_SECONDS} from './cadence.mts';
+export {renderSnapshot} from './render.mts';
+export {adoptOrphans, githubLister} from './adopt.mts';

package/src/lib/watch/marker.mts

@@ -0,0 +1,24 @@
+/**
+ * The agent id this plugin writes into its machine markers. The wire format
+ * is `<!-- agent-reply:<agent-id> -->` on a post's first line.
+ */
+export const AGENT_ID = 'dispatch';
+
+const MARKER = new RegExp(`^\\s*<!--\\s*agent-reply:${AGENT_ID}\\s*-->`, 'iu');
+
+/**
+ * Whether this agent wrote a post, judged by its own marker rather than by
+ * the authoring account.
+ *
+ * The account is the wrong test. Under shared credentials the agent posts as
+ * the operator, so filtering by login would suppress the operator's own
+ * review — the one signal a waiting worker most needs. The marker is written
+ * by this agent and by nothing else, so it identifies authorship regardless
+ * of which account carried it.
+ *
+ * Matching the agent id specifically, not a bare `agent-reply`, keeps another
+ * tool's marked post actionable.
+ */
+export function writtenByThisAgent(body: string | null | undefined): boolean {
+  return typeof body === 'string' && MARKER.test(body);
+}

package/src/lib/watch/payload.mts

@@ -0,0 +1,56 @@
+import {execFile} from 'node:child_process';
+import {promisify} from 'node:util';
+
+import type {Logger} from '../logger/index.mts';
+
+const run = promisify(execFile);
+
+/**
+ * How long one payload read may take before the tick moves on without it.
+ *
+ * This bounds a heartbeat, not just a read. Payload reads happen inside the
+ * tick, and a session whose heartbeat stops for the staleness window is swept
+ * — its claims cascade and its work is re-dispatched underneath it. The
+ * budget below keeps the worst case an order of magnitude short of that.
+ */
+const TIMEOUT_MS = 20_000;
+
+/**
+ * The `pr-status` payload for a PR, which is what a PR/CI event body must
+ * carry: the worker then reacts to everything the tick saw in one turn, from
+ * the same document it would have read itself.
+ *
+ * `--repo` is what makes this reachable from the server, which stands in one
+ * directory and watches PRs across repos.
+ *
+ * A failed read returns null rather than failing the tick. The event still
+ * goes out with its summary, and the worker reads `pr-status` itself — a
+ * degraded wake-up beats a silent one.
+ */
+export async function prStatusPayload(
+  repo: string,
+  prNumber: number,
+  opts: {script: string; log?: Logger | undefined}
+): Promise<string | null> {
+  try {
+    const {stdout} = await run(
+      opts.script,
+      ['--repo', repo, String(prNumber)],
+      {timeout: TIMEOUT_MS, maxBuffer: 8 * 1024 * 1024}
+    );
+    const payload = stdout.trim();
+    return payload === '' ? null : payload;
+  } catch (error) {
+    opts.log?.warn('could not read the pr-status payload', {
+      repo,
+      pr: prNumber,
+      error: error instanceof Error ? error.message : String(error),
+    });
+    return null;
+  }
+}
+
+/** The bundled `pr-status`, resolved against this file rather than the cwd. */
+export function prStatusScript(): string {
+  return new URL('../../../bin/pr-status', import.meta.url).pathname;
+}

package/src/lib/watch/poll.mts

@@ -0,0 +1,87 @@
+import {nowIso} from '../db/time.mts';
+import {withDatabase} from '../db/index.mts';
+import type {Logger} from '../logger/index.mts';
+import {WatchStore} from '../stores/index.mts';
+import {cadenceFor, EXPIRY_SECONDS} from './cadence.mts';
+import {diffSnapshots} from './diff.mts';
+import type {Snapshotter} from './snapshot.mts';
+
+/** Snapshot calls one pass will make; keeps a tick short. */
+const MAX_POLLS_PER_PASS = 10;
+
+/**
+ * One polling pass over the due watches: fire the expired ones outright,
+ * snapshot the rest, and record what changed as events.
+ *
+ * Short of its deadline, a watch fires only when the diff produced something
+ * — an unchanged PR, or one that changed in a way only the agent itself
+ * caused, leaves the row watching. That is the whole point of diffing
+ * structurally rather than hashing: a worker is woken for a reason it can be
+ * told. Expiry is the one wake with no reason to give, and says so.
+ *
+ * A parked item never reads as expired (`due`), so for it the diff is the
+ * only thing that fires: it is waiting on a person, and "your six hours are
+ * up" is not an answer.
+ *
+ * A failed snapshot costs only that row's interval: `touch` pushes the retry
+ * out so a broken PR is not hammered every tick, and the error goes to the
+ * log rather than failing the pass.
+ */
+export async function pollWatches(
+  env: NodeJS.ProcessEnv,
+  opts: {
+    snapshot: Snapshotter;
+    dbPath?: string | undefined;
+    now?: () => string;
+    log?: Logger | undefined;
+  }
+): Promise<{fired: string[]}> {
+  const now = opts.now ?? nowIso;
+  return withDatabase(opts.dbPath, env, async (db) => {
+    const watches = new WatchStore(db);
+    // Every unconcluded PR item is watched — including one parked on an
+    // operator — whether or not a worker ever asked. A PR moves whether
+    // anyone is waiting on it, and an item nobody armed is exactly the one
+    // whose change would otherwise be missed.
+    await watches.ensureForLiveItems(now(), EXPIRY_SECONDS);
+    const fired: string[] = [];
+
+    for (const due of await watches.due(now(), MAX_POLLS_PER_PASS)) {
+      if (due.expired) {
+        if ((await watches.fire(due.node, now(), due.createdAt)) === 'fired') {
+          fired.push(due.node);
+        }
+        continue;
+      }
+      try {
+        const taken = await opts.snapshot(due.repo, due.prNumber);
+        const observed = diffSnapshots(due.snapshot, taken);
+        // Changed or not changed is the only question. There is no predicate
+        // for "has the thing you were waiting for happened", because a worker
+        // cannot say what it is waiting for and any such predicate tests a
+        // persistent state — which fires again the moment the worker returns.
+        //
+        // One transaction: recording events and firing the watch must not be
+        // separable, or a crash between them re-emits the same events on the
+        // next tick against the same unchanged snapshot.
+        const outcome = await watches.observe({
+          node: due.node,
+          snapshot: taken,
+          at: now(),
+          createdAt: due.createdAt,
+          fire: observed.length > 0,
+          intervalSeconds: cadenceFor(taken),
+          events: observed,
+        });
+        if (outcome === 'fired') fired.push(due.node);
+      } catch (error) {
+        await watches.touch(due.node, now(), due.createdAt);
+        opts.log?.error('watch poll failed', {
+          node: due.node,
+          error: error instanceof Error ? error.message : String(error),
+        });
+      }
+    }
+    return {fired};
+  });
+}

package/src/lib/watch/render.mts

@@ -0,0 +1,61 @@
+import type {PrSnapshot} from './snapshot.mts';
+
+/**
+ * Render an event body from the snapshot the server already holds.
+ *
+ * This replaced shelling out to `pr-status` per event. That script makes
+ * several `gh` calls, writes cache files, and invokes `claude` to summarize —
+ * a deep read a worker runs for itself when it needs actionability and cached
+ * bodies. The event body's job is smaller: say where the PR stands, in the
+ * same XML vocabulary the worker already reads, so one wakeup carries
+ * everything one tick saw without costing a subprocess per event.
+ */
+export function renderSnapshot(
+  repo: string,
+  prNumber: number,
+  snapshot: PrSnapshot
+): string {
+  const lines: string[] = [];
+  const esc = (value: string): string =>
+    value
+      .replaceAll('&', '&')
+      .replaceAll('<', '&lt;')
+      .replaceAll('"', '&quot;');
+
+  lines.push(
+    `<pr-event repo="${esc(repo)}" pr="${String(prNumber)}" head="${esc(snapshot.head ?? '')}" state="${esc(snapshot.state ?? '')}" draft="${String(snapshot.draft)}" merged="${String(snapshot.merged)}">`
+  );
+  const rollup = snapshot.rollup ?? 'NONE';
+  lines.push(`  <checks state="${esc(rollup)}">`);
+  for (const check of snapshot.checks) {
+    lines.push(
+      `    <check name="${esc(check.name)}" conclusion="${esc(check.conclusion ?? 'PENDING')}"${check.url === null ? '' : ` url="${esc(check.url)}"`}/>`
+    );
+  }
+  lines.push('  </checks>');
+  lines.push(
+    `  <merge-conflicts present="${String(snapshot.mergeState === 'DIRTY')}"/>`
+  );
+  lines.push(
+    `  <review-decision>${esc(snapshot.reviewDecision ?? 'NONE')}</review-decision>`
+  );
+  lines.push('  <reviews>');
+  for (const review of snapshot.reviews) {
+    lines.push(
+      `    <review author="${esc(review.author)}" state="${esc(review.state)}" mine="${String(review.mine)}"/>`
+    );
+  }
+  lines.push('  </reviews>');
+  lines.push('  <threads>');
+  for (const thread of snapshot.threads) {
+    lines.push(
+      `    <thread id="${esc(thread.id)}" resolved="${String(thread.resolved)}" lastAuthor="${esc(thread.lastAuthor ?? '')}" mine="${String(thread.mine)}"/>`
+    );
+  }
+  lines.push('  </threads>');
+  lines.push(
+    `  <note>Snapshot rendered by the server. For actionability classification and cached bodies, run pr-status --repo ${esc(repo)} ${String(prNumber)} yourself.</note>`
+  );
+  lines.push('</pr-event>');
+  return lines.join('\n');
+}