feat: tps pulse Phase 2 — prune + Flair publishing (ops-105) (#211)

Phase 2 additions to the PR review workflow engine:

Prune:
- pruneState(state, days) removes terminal instances (merged/closed)
  older than pruneAfterDays (default: 7)
- Called at the start of every poll cycle before pollOnce
- Returns count of pruned instances; logs if any pruned
- PulseConfig.pruneAfterDays field (configurable in config.json)

Flair publishing:
- makeFlairPublisher(config) creates FlairPublisher if flairUrl +
  flairAgentId + flairAgentKey are set in config (opt-in, no-op otherwise)
- On each state transition: publishEvent (OrgEvent) + writeMemory
  (persistent fact, stable id per PR key)
- FlairPublisher injected into handleTransition/pollOnce as optional param
- Publisher errors are caught and logged — never block the poll loop
- PulseConfig gains flairUrl/flairAgentId/flairAgentKey fields

Tests: +6 tests (3 pruneState, 3 FlairPublisher integration). 23 pulse
tests total. 631 tests pass, 0 fail.

Author: tps-anvil

packages/cli/src/commands/pulse.ts

@@ -9,6 +9,7 @@ import { spawnSync, type SpawnSyncReturns } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
+import { createFlairClient } from "../utils/flair-client.js";
 
 // ---------------------------------------------------------------------------
 // Types
@@ -49,6 +50,10 @@ export interface PulseConfig {
   pollIntervalMs: number;
   remindAfterMs: number;
   ghAgent: string;
+  pruneAfterDays: number;
+  flairUrl?: string;
+  flairAgentId?: string;
+  flairAgentKey?: string;
 }
 
 // Injectable runner type for testing
@@ -57,6 +62,14 @@ export type SyncRunner = (cmd: string, args: string[], opts?: { encoding?: Buffe
 // Injectable mail sender for testing
 export type MailSender = (to: string, body: string, agentId: string) => void;
 
+// Injectable Flair publisher for testing (null = disabled)
+export type FlairPublisher = (
+  key: string,
+  from: PrState | null,
+  to: PrState,
+  instance: PrInstance,
+) => Promise<void>;
+
 // ---------------------------------------------------------------------------
 // Defaults
 // ---------------------------------------------------------------------------
@@ -70,6 +83,7 @@ const DEFAULT_CONFIG: PulseConfig = {
   pollIntervalMs: 120000,
   remindAfterMs: 1800000,
   ghAgent: "flint",
+  pruneAfterDays: 7,
 };
 
 const PULSE_DIR = join(homedir(), ".tps", "pulse");
@@ -108,6 +122,27 @@ export function saveState(state: PulseState): void {
   writeFileSync(STATE_PATH, JSON.stringify(state, null, 2), "utf-8");
 }
 
+/**
+ * Remove terminal instances (merged/closed) older than pruneAfterDays.
+ * Returns the number of instances pruned.
+ */
+export function pruneState(state: PulseState, pruneAfterDays: number): number {
+  const cutoff = Date.now() - pruneAfterDays * 24 * 60 * 60 * 1000;
+  const terminalStates = new Set<string>(["merged", "closed"]);
+  let pruned = 0;
+  for (const key of Object.keys(state.instances)) {
+    const inst = state.instances[key];
+    if (
+      terminalStates.has(inst.state) &&
+      new Date(inst.lastTransitionAt).getTime() < cutoff
+    ) {
+      delete state.instances[key];
+      pruned++;
+    }
+  }
+  return pruned;
+}
+
 // ---------------------------------------------------------------------------
 // GitHub API
 // ---------------------------------------------------------------------------
@@ -181,6 +216,7 @@ export function handleTransition(
   newState: PrState,
   config: PulseConfig,
   sender: MailSender,
+  publisher?: FlairPublisher,
 ): void {
   const oldState = instance.state;
   if (oldState === newState) return;
@@ -193,6 +229,13 @@ export function handleTransition(
 
   console.log(`[pulse] ${key}: ${oldState} → ${newState}`);
 
+  // Publish to Flair (non-blocking, best-effort)
+  if (publisher) {
+    publisher(key, oldState, newState, instance).catch((e: unknown) => {
+      console.warn(`[pulse] Flair publish failed: ${(e as Error).message}`);
+    });
+  }
+
   // Determine mail targets based on transition
   switch (newState) {
     case "opened": {
@@ -305,6 +348,7 @@ export function pollOnce(
   state: PulseState,
   runner: SyncRunner = spawnSync as unknown as SyncRunner,
   sender: MailSender = defaultMailSender,
+  publisher?: FlairPublisher,
 ): void {
   const now = new Date().toISOString();
 
@@ -363,12 +407,12 @@ export function pollOnce(
 
         // If PR already has reviews, advance state
         if (computed !== "opened") {
-          handleTransition(key, instance, computed, config, sender);
+          handleTransition(key, instance, computed, config, sender, publisher);
         }
       } else {
         // Existing PR — check for state change
         existing.title = pr.title;
-        handleTransition(key, existing, computed, config, sender);
+        handleTransition(key, existing, computed, config, sender, publisher);
       }
     }
 
@@ -380,7 +424,7 @@ export function pollOnce(
       try {
         const prData = ghApi(`repos/${repo}/pulls/${inst.prNumber}`, config.ghAgent, runner) as GhPr;
         if (prData.merged_at) {
-          handleTransition(key, inst, "merged", config, sender);
+          handleTransition(key, inst, "merged", config, sender, publisher);
         }
       } catch (e: unknown) {
         console.warn(`[pulse] Failed to check closed PR ${key}: ${(e as Error).message}`);
@@ -398,23 +442,55 @@ export function pollOnce(
 // Poll Loop (foreground)
 // ---------------------------------------------------------------------------
 
+export function makeFlairPublisher(config: PulseConfig): FlairPublisher | undefined {
+  if (!config.flairUrl || !config.flairAgentId || !config.flairAgentKey) return undefined;
+  try {
+    const client = createFlairClient(config.flairAgentId, config.flairUrl, config.flairAgentKey);
+    return async (key: string, from: PrState | null, to: PrState, instance: PrInstance) => {
+      // Publish OrgEvent for state transition
+      await client.publishEvent({
+        kind: `pr.${to}`,
+        scope: key,
+        summary: `PR #${instance.prNumber} (${instance.repo}): ${from ?? "new"} → ${to}`,
+        detail: instance.title,
+        refId: key,
+      });
+      // Store as persistent memory (stable id per PR key — same PUT overwrites)
+      const memId = `${config.flairAgentId}-pulse-${key.replace(/[^a-z0-9]/gi, "-")}`;
+      const content = `PR ${key} state: ${to}. Title: "${instance.title}". Transition: ${from ?? "new"} → ${to} at ${instance.lastTransitionAt}.`;
+      await client.writeMemory(memId, content, {
+        durability: "persistent",
+        type: "fact",
+        tags: ["pulse", "pr-lifecycle", to],
+      });
+    };
+  } catch (e: unknown) {
+    console.warn(`[pulse] Failed to create Flair publisher: ${(e as Error).message}`);
+    return undefined;
+  }
+}
+
 export async function startPollLoop(
   config: PulseConfig,
   state: PulseState,
-  opts: { dryRun?: boolean; runner?: SyncRunner; sender?: MailSender } = {},
+  opts: { dryRun?: boolean; runner?: SyncRunner; sender?: MailSender; publisher?: FlairPublisher } = {},
 ): Promise<void> {
   const runner = opts.runner ?? (spawnSync as unknown as SyncRunner);
   const sender = opts.dryRun
     ? (to: string, body: string, _agentId: string) => {
         console.log(`[pulse/dry-run] would mail ${to}: ${body.slice(0, 80)}…`);
       }
     : (opts.sender ?? defaultMailSender);
+  const publisher = opts.dryRun ? undefined : (opts.publisher ?? makeFlairPublisher(config));
 
   console.log(`[pulse] Starting poll loop (interval=${config.pollIntervalMs}ms, repos=${config.repos.join(", ")})`);
 
   const poll = () => {
     try {
-      pollOnce(config, state, runner, sender);
+      // Prune stale terminal instances before each poll
+      const pruned = pruneState(state, config.pruneAfterDays);
+      if (pruned > 0) console.log(`[pulse] Pruned ${pruned} completed instance(s) older than ${config.pruneAfterDays} days`);
+      pollOnce(config, state, runner, sender, publisher);
       saveState(state);
     } catch (e: unknown) {
       console.error(`[pulse] Poll error: ${(e as Error).message}`);

packages/cli/test/pulse.test.ts

@@ -4,12 +4,14 @@ import {
   handleTransition,
   checkReminders,
   pollOnce,
+  pruneState,
   type PrInstance,
   type PrState,
   type PulseConfig,
   type PulseState,
   type SyncRunner,
   type MailSender,
+  type FlairPublisher,
 } from "../src/commands/pulse.js";
 
 // ---------------------------------------------------------------------------
@@ -357,3 +359,145 @@ describe("pollOnce", () => {
     expect(calls.length).toBe(2); // mail for PR #11 to both reviewers
   });
 });
+
+// ---------------------------------------------------------------------------
+// pruneState
+// ---------------------------------------------------------------------------
+
+describe("pruneState", () => {
+  function makeTerminalInstance(state: PrState, daysOld: number): PrInstance {
+    const ts = new Date(Date.now() - daysOld * 24 * 60 * 60 * 1000).toISOString();
+    return {
+      key: `pr:tpsdev-ai/cli#99`,
+      repo: "tpsdev-ai/cli",
+      prNumber: 99,
+      title: "Old PR",
+      state,
+      openedAt: ts,
+      lastTransitionAt: ts,
+      reminderSentAt: null,
+      history: [],
+    };
+  }
+
+  test("removes merged instances older than pruneAfterDays", () => {
+    const state: PulseState = {
+      version: 1,
+      lastPollAt: "",
+      instances: {
+        "pr:tpsdev-ai/cli#1": makeTerminalInstance("merged", 8),
+        "pr:tpsdev-ai/cli#2": makeTerminalInstance("merged", 3),
+      },
+    };
+    const pruned = pruneState(state, 7);
+    expect(pruned).toBe(1);
+    expect(state.instances["pr:tpsdev-ai/cli#1"]).toBeUndefined();
+    expect(state.instances["pr:tpsdev-ai/cli#2"]).toBeDefined();
+  });
+
+  test("keeps non-terminal instances regardless of age", () => {
+    const state: PulseState = {
+      version: 1,
+      lastPollAt: "",
+      instances: {
+        "pr:tpsdev-ai/cli#10": makeTerminalInstance("reviewing" as PrState, 30),
+      },
+    };
+    const pruned = pruneState(state, 7);
+    expect(pruned).toBe(0);
+    expect(state.instances["pr:tpsdev-ai/cli#10"]).toBeDefined();
+  });
+
+  test("returns 0 when nothing to prune", () => {
+    const state: PulseState = { version: 1, lastPollAt: "", instances: {} };
+    expect(pruneState(state, 7)).toBe(0);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Flair publisher (handleTransition integration)
+// ---------------------------------------------------------------------------
+
+describe("FlairPublisher integration", () => {
+  test("publisher is called on transition", async () => {
+    const calls: Array<{ key: string; from: PrState | null; to: PrState }> = [];
+    const publisher: FlairPublisher = async (key, from, to) => {
+      calls.push({ key, from, to });
+    };
+
+    const instance: PrInstance = {
+      key: "pr:tpsdev-ai/cli#42",
+      repo: "tpsdev-ai/cli",
+      prNumber: 42,
+      title: "Test PR",
+      state: "reviewing",
+      openedAt: new Date().toISOString(),
+      lastTransitionAt: new Date().toISOString(),
+      reminderSentAt: null,
+      history: [],
+    };
+    const config = makeConfig();
+    const mailCalls: string[] = [];
+    const sender: MailSender = (to) => { mailCalls.push(to); };
+
+    handleTransition("pr:tpsdev-ai/cli#42", instance, "approved", config, sender, publisher);
+
+    // Give microtask queue a tick
+    await Promise.resolve();
+
+    expect(calls).toHaveLength(1);
+    expect(calls[0].from).toBe("reviewing");
+    expect(calls[0].to).toBe("approved");
+  });
+
+  test("publisher errors are swallowed (non-fatal)", async () => {
+    const publisher: FlairPublisher = async () => {
+      throw new Error("Flair unavailable");
+    };
+
+    const instance: PrInstance = {
+      key: "pr:tpsdev-ai/cli#1",
+      repo: "tpsdev-ai/cli",
+      prNumber: 1,
+      title: "T",
+      state: "reviewing",
+      openedAt: new Date().toISOString(),
+      lastTransitionAt: new Date().toISOString(),
+      reminderSentAt: null,
+      history: [],
+    };
+    const config = makeConfig();
+    const sender: MailSender = () => {};
+
+    // Should not throw
+    expect(() => {
+      handleTransition("pr:tpsdev-ai/cli#1", instance, "approved", config, sender, publisher);
+    }).not.toThrow();
+
+    // Give microtask queue a tick — error is caught internally
+    await Promise.resolve();
+  });
+
+  test("publisher is not called when state unchanged", async () => {
+    const calls: string[] = [];
+    const publisher: FlairPublisher = async (_, _from, to) => { calls.push(to); };
+
+    const instance: PrInstance = {
+      key: "pr:tpsdev-ai/cli#5",
+      repo: "tpsdev-ai/cli",
+      prNumber: 5,
+      title: "T",
+      state: "approved",
+      openedAt: new Date().toISOString(),
+      lastTransitionAt: new Date().toISOString(),
+      reminderSentAt: null,
+      history: [],
+    };
+    const config = makeConfig();
+    const sender: MailSender = () => {};
+
+    handleTransition("pr:tpsdev-ai/cli#5", instance, "approved", config, sender, publisher);
+    await Promise.resolve();
+    expect(calls).toHaveLength(0);
+  });
+});