Record who starts, kills and decides workflow runs and review loops

[alex-clickhouse]

What

Nerve records who starts, kills and decides workflow runs and review loops. The session of a run, and of each loop leg, is created for the person who started the work, so its model requests name that person.

How

• Migration v056:

  • adds four nullable foreign keys to actor_refs on both workflow_runs and review_loops: created_by_actor_id, caused_by_actor_id, killed_by_actor_id and killed_caused_by_actor_id;
  • adds the append-only table review_loop_decisions, with one row for each decision on a parked loop.

  Old rows stay empty. The attribution column registry lists the new columns.

• These actions record the person:

  • starting or killing a run or a loop through the REST API;
  • creating a loop with its session;
  • deciding on a parked loop through REST or its card in the web UI;
  • a Stop from the web UI on a run's session.

  The workflow and review-loop tools record the system actor for the cause of the session that called them. A cron job's run is the system actor's own work.

• A run's session is created with the run's cause, so everything the agent does in it, including its model requests in external mode, names that cause. Each loop leg is a run that Nerve creates for the loop's cause.

• A decision and its record are one transaction. A card reminder is recorded after the card is snoozed, and as not applied when the card was no longer pending.

• GET /api/review-loops/{id} returns the decisions. The workflow runs page shows "created by Alice" (or "Nerve for Alice") and who killed a run.

• workflow_runs.created_by keeps its format, because the sidebar reads it to nest a run under the session that started it.

Why

Workflow runs and review loops are the most expensive work an agent does. Recording the person, and creating the legs' sessions for that person, lets the model usage of this work be attributed to the person who caused it.

Approximation

A run that the agent starts in a shared session is attributed to the person who started that session.

Behaviour changes

• The session of a run that a person started is created with that person as its cause.
• POST /api/review-loops/{id}/decision:
  • refuses remind_4h with 400; the reminder exists only on the card;
  • returns 200 with ok false, instead of 409, when the decision was applied but its resumed leg did not start.
• A decision whose record cannot be written fails and changes nothing.
• Approval dispatchers can return the new optional DispatchResult.after_snooze callback.

Testing

• New tests for every path, including the decision and snooze race, and an external-mode test of the principal on leg turns. Every commit passes its tests.
• Full suite on this branch: 5907 passed, 39 skipped. Web: build ok, 737 tests passed.

Stack

1. Record each session's cause and who changes a task #515 Actor and cause plumbing; task attribution (base main)
2. Name the session's cause on each model request in external mode #516 Model requests name the session's cause
3. Record who changes a session, and who deletes it #517 Session change attribution
4. Record who answers notifications and reviews plans #518 Notification answers, plan reviews and approval decisions
5. Record who starts, kills and decides workflow runs and review loops #519 (this PR): Workflow runs and review loops
6. Record who schedules wakeups and starts cron runs, and run them for that person #520 Schedules: run-now, run-later and wakeups

🤖 Generated with Claude Code