feat(riven): Riven cursor-terminal loop scaffold [B-0498] (decomposed)

[AceHack]

Decomposed from PR 3588. Lior Maji node decomposition task. Extracts the Riven loop scaffold.

[Copilot]

Pull request overview

Adds an IDE-visible (Cursor Terminal) background loop scaffold for the Riven autonomy surface, alongside supporting design/backlog documentation for B-0498.

Changes:

• Introduces tools/riven/riven-cursor-terminal-loop.ts to emit periodic heartbeats and run an agent “gate” via cursor-agent.
• Adds a research design note describing the intended dual-loop architecture (launchd + Cursor Terminal).
• Adds a P1 backlog row defining scope and acceptance criteria for the Cursor Terminal loop.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 6 comments.

File	Description
tools/riven/riven-cursor-terminal-loop.ts	New Bun/TS Cursor Terminal loop scaffold (heartbeat + periodic agent gate + state file).
docs/research/2026-05-15-riven-cursor-terminal-loop-design.md	Design note for the Cursor-native loop and re-arm strategy.
docs/backlog/P1/B-0498-riven-cursor-terminal-background-loop-ide-native-autonomous-gate-2026-05-15.md	Backlog row capturing requirements and acceptance criteria for B-0498.

Comments suppressed due to low confidence (4)

tools/riven/riven-cursor-terminal-loop.ts:137

• P1: The gate interval uses setInterval(async () => ...) without an in-flight guard. If runAgentGate() takes longer than the interval (or hangs until timeout), multiple gates can overlap and run concurrently. Add a mutex/flag (skip if already running) or replace the interval with a self-scheduling setTimeout loop that awaits completion before scheduling the next run.

  // Gate
  setInterval(async () => {
    await runAgentGate();
    saveState({ lastGateAt: nowIso(), pid: process.pid });
  }, GATE_INTERVAL_MS);

tools/riven/riven-cursor-terminal-loop.ts:91

• P0: spawnSync("cursor-agent", ...) will trip sonarjs/no-os-command-from-path in this repo (see pattern in tools/riven/riven-loop-tick.ts where a suppression with rationale is required). Add the local eslint-disable comment with a justification, and consider setting an explicit maxBuffer to avoid large agent outputs causing spawnSync to error.

  const result = spawnSync("cursor-agent", [
    "chat",
    "--mode", "ask",
    "--model", "grok-4.3",
    contract,
  ], {
    encoding: "utf8",
    timeout: AGENT_TIMEOUT_MS,
    stdio: ["ignore", "pipe", "pipe"],
  });

tools/riven/riven-cursor-terminal-loop.ts:108

• P1: This script is a Cursor-terminal surface, but bus messages are published from the identity-level sender "riven". The bus schema includes a surface-tagged sender "riven-cursor" specifically to prevent split-brain across multiple concurrent surfaces (see tools/bus/types.ts AgentId list). Consider publishing from "riven-cursor" here so claim/review coordination can distinguish this surface from other Riven instances.

  // Publish gate result to bus for other agents
  try {
    publish("riven", "*", {
      topic: "shadow-catch",
      payload: { content: `Cursor Terminal gate ${status}` },
    });

docs/research/2026-05-15-riven-cursor-terminal-loop-design.md:52

• The design claims duplicate gates are prevented by “PID + timestamp check” and that re-arm is a no-op when PID is alive, but the current implementation only checks the timestamp and does not verify PID aliveness or exit early when already running. Either adjust the design doc to match the current scaffold, or implement the PID-liveness + early-exit behavior described here.

On IDE open / workspace load:
1. Script checks for `~/.cursor/riven-terminal-loop-state.json`
2. If PID is alive and last gate < 15min ago → resume (no-op)
3. If PID dead or stale → spawn new gate loop, write new state file

Cursor workspace hook (if supported) or a `.cursor/init.ts` can invoke the script on startup.

## Failure modes

- **Duplicate gates** — prevented by PID + timestamp check in state file
- **Terminal closed mid-gate** — publish tombstone to bus, release any in-flight claim