Runtime: processes, topics, real-time flow

Supervision tree

flowchart LR
    subgraph fly["Phoenix app (Fly)"]
        engine["Flow engine<br/>Relay.Flows / Relay.Runs"]
        db[("Postgres<br/>flows · runs · node outcomes")]
        board["Board UI (LiveView)<br/>live run state on the card"]
        engine --- db
        engine -- "PubSub run events" --> board
    end
    subgraph dev["Developer machine (or future cloud sandbox)"]
        exec["./relay runner<br/>(thin: claim job, run, report)"]
        agent["claude -p<br/>one agent node"]
        repo["project checkout + worktrees<br/>CLAUDE.md · .claude/skills · MCP<br/>(developer-owned)"]
        exec --> agent
        agent --- repo
    end
    engine -- "node-jobs" --> exec
    exec -- "output stream + typed outcome" --> engine

One flat one_for_one supervisor (Relay.Supervisor, started by Relay.Application):

Stripe webhook (RE460)

POST /webhooks/stripe → RelayWeb.StripeWebhookController.create/2, in the :webhook pipeline (accepts JSON; no session, no CSRF — the signature is the authentication). RelayWeb.RawBodyReader, the endpoint's Plug.Parsers body_reader, keeps the raw body in conn.private[:raw_body] for this path only. Relay.Billing.verify_webhook/2 checks the Stripe-Signature (t=…,v1=…, HMAC-SHA256 of "<t>.<body>" under :stripe_webhook_secret, ±Relay.Billing.Webhook.tolerance_s/0 = 300s) — a failure is 400 invalid_signature. A verified event is acknowledged 200 {"ok":true} whatever it is; a setup-mode checkout.session.completed or a setup_intent.succeeded saves the card (Relay.Billing.complete_setup/3, the same call the Billing page's return URL makes — safe to run twice). 404 while billing is disabled. In dev/test (:dev_routes) GET /dev/billing-checkout is the Local payments' stand-in for Stripe Checkout: two links back to same-origin succeed / decline paths (anything else is 400). GET /dev/mailbox (Plug.Swoosh.MailboxPreview, also :dev_routes only) lists the billing emails (RE464) delivered to Swoosh's Local adapter in dev.

Session lifetime

The browser session is a signed cookie (_relay_key, no server-side record). Its policy is 7 days, sliding (RLY-127), and it lives in three places that must agree:

The cookie attribute is a client-side hint only — Plug.Session.COOKIE.get/3 does no age check, so a client can replay an arbitrarily old cookie. RelayWeb.Auth therefore enforces the window itself:

• fetch_current_scope/2 (the :browser and :native_user_auth pipelines) expires a session stamped past max_age/0 and re-stamps one older than refresh_after/0. The re-stamp is a session write, and Plug.Session only emits Set-Cookie on a write — that is what slides the cookie's Max-Age forward. Throttling to once a day is what keeps Set-Cookie off every response.
• mount_current_scope/2 (the on_mount hooks) expires only — a LiveView mount has no conn and cannot write a cookie. It closes the hole where a stale cookie mounts a LiveView on socket reconnect without passing through the plug pipeline.
• NativeAuthController.me/2 expires and re-stamps: it rejects a session past the window with 401 and mints no bearer token — me/2 is the only server-side check a replayed native cookie ever meets (the :native_auth pipeline does not run fetch_current_scope/2), and mint_token/1 hands back a bearer that outlives the session it came from. On success it re-stamps: the Flutter shell's launch-time verify is the native app's only touch point, and _restore() writes the refreshed cookie back to the Keychain.
• A session with no stamp (predating RLY-127) is re-stamped, never expired — expiring them would sign out every existing user on deploy.

There is no revocation: invalidating a session today means rotating SECRET_KEY_BASE, which signs out everyone everywhere. Server-side session records and "sign out of all devices" are tracked as a separate follow-up.

On-device state (mobile app)

The Flutter app keeps three Keychain items (flutter_secure_storage, first_unlock), each behind a store interface with an in-memory test double:

All three are cleared on sign-out and on a dead session (AuthController._clearSession). Switching to a different board, or clearing it, forgets the last place's stage and card but keeps its tab.

On a cold launch the router's redirect holds the splash until the board and the last place are read, then reopens the place through LaunchRestorer (flutter/lib/app/launch_restorer.dart); a pending push tap wins, and an interactive sign-in still primes push permission. A remembered card is checked with GET /api/all/cards/:ref?board=<slug> (3 s bound). If it's live, it reopens silently over its current stage. If it was archived, the board opens on the card's stage with the toast <REF> was archived; a 404 opens the remembered stage with <REF> was deleted. On a timeout or any other failure, the card opens unverified. A restored stage the board no longer has (relayStageMissing) toasts The <Stage> stage no longer exists, once, and never after a card toast. A restored card puts the board webview under the pushed card, where the pager's one-shot ?stage= scroll runs with no real layout and drifts. So BoardScreen drops relayStageChanged while a pushed route covers the board, and when the board is revealed it asks the pager to re-show the last page seen on screen (else the requested stage) with the relay:show-stage window event.

PubSub topics

Three invariants make the seam trustworthy: only contexts broadcast domain events (so LiveView and REST mutations share one path), broadcasting is fire-and-forget (a PubSub failure can never fail the mutation), and events are delivered after commit: an event broadcast inside a transaction is queued and sent once the outermost Relay.Repo transaction commits, and discarded on rollback (Relay.Repo.after_commit/1, RE386). The same holds for Relay.Runs' board:<board_id>:runs events. Every Events.broadcast/2 also bumps the board's BoardWatch version, which the CLI polls to avoid refetching unchanged boards.

RE257's three topics are the deliberate exception to "only contexts broadcast domain events": they carry presence, not mutations, and they bypass Relay.Events precisely so they never bump the board version — a cursor at 20 Hz through Events.broadcast/2 would be a write storm against the CLI's version poll.

Load-bearing sequences

A card move fanning out to every open board (same path for REST and LiveView writers):

sequenceDiagram
    participant A as Agent (REST) or BoardLive (drag)
    participant C as Relay.Cards
    participant E as Relay.Events
    participant L as every BoardLive on board:id
    A->>C: move_card(scope, card, stage)
    C->>C: validate vs ADR 0003 rules, persist
    C->>E: broadcast {:card_moved, card, from}
    E-->>L: PubSub (fire-and-forget)
    E->>E: BoardWatch.bump(board_id)
    L->>L: re-stream card into new column

The needs-input round trip (the baton passing to a human and back):

sequenceDiagram
    participant R as runner step (claude -p)
    participant API as POST /api/cards/:ref/needs-input
    participant C as Relay.Cards
    participant H as human (BoardLive drawer)
    R->>API: questions JSON
    API->>C: needs_input(card, questions)
    C->>C: status → needs_input (card blocked)
    C-->>H: {:card_upserted} via Events
    H->>C: answer (drawer stepper)
    C->>C: status cleared, answer on timeline
    Note over R: runner sees the answer on its next scan and resumes the card

A terminally failed run takes a different path — card_fail_effects/2 → Relay.Cards.mark_failed/3 → card status :failed, no question. ensure_card_blocked/2 is reserved for the genuine question above; the two never overlap (RLY-179).

Fan-out regions (RE437)

A fan_out / fan_in pair is the one place a run holds several node jobs at once. Both are control nodes (Schemas.Flow.Node.control_types/0): the run's RunServer resolves them itself, writing a node_executions row with an immediate outcome and no node_job, so no runner ever sees one. The region in between is tracked in run_branches (Schemas.RunBranch, owned by Relay.Runs): one row per branch per region entry, keyed by the fan_out execution that opened it, its state drawn from Schemas.RunBranch.states/0 (the generated table in state.md). Branch executions carry node_executions.run_branch_id.

sequenceDiagram
    participant S as RunServer (one per run)
    participant DB as runs · run_branches · node_jobs
    participant R as the run's runner (one worktree)
    S->>DB: record fan_out :succeeded (no job), one run_branches row per edge (queued)
    S->>DB: start up to max_parallel rows → running, enqueue each head node (run_branch_id set)
    DB-->>R: several node jobs of ONE run, claimed into the same checkout
    R->>S: report (per job)
    S->>S: Engine.decide/4 on that branch's history only
    alt branch reached the fan_in
        S->>DB: row → ended (outcome, detail); start the next queued row
    else branch parks on a human
        S->>DB: row → parked, run parked — siblings keep running
    end
    S->>DB: every row ended → record fan_in with Engine.join/1, route it like any node

• Scheduling. At most the fan_out's max_parallel rows are running; each ended row frees a slot for the next queued one, by position. run.current_node stays the fan_out key while the region is open, and Runs.active_jobs/1 returns one job per running branch.
• Branch-scoped budgets. max_retries, max_loops, the visit cap and the failure-signature breaker are counted on the branch's own history, so one branch's failures never spend another's. A branch's {:fail, _} ends only its row :failed; the run carries on to the join.
• The join. When every row is ended, the fan_in resolves through Relay.Runs.Engine.join/1 — wait-all, any-failed — which owns the outcome rule and the per-branch label format (don't re-derive either).
• Park with siblings. A branch that waits on a human parks its row and the run, but revokes no sibling job. While the run is parked, a report from a running branch is still accepted (Runs.report_accepted?/2) and routed inside that branch; RunServer attaches for it only when Runs.attachable_while_parked?/1 says so and stops again after each report, so a parked run holds no long-lived process. No queued branch starts and no join happens until resume.
• Re-entry and restart. Every re-entry with a region open (Runs.open_region/1) — resume, --at, a restart after a deploy (Runs.boot_mode/1 always re-enters such a run) — goes branch by branch: a running row with a live job is left alone; one without, and every parked row, gets a fresh attempt of the same visit. Re-entering at a branch node or a fan_in with no region open opens a fresh region at its fan_out (Runs.retry_run/2 maps the target the same way).
• Cancel and close. cancel_run/2 and close_run!/3 end every open row (Runs.end_open_branches!/1), so a terminal run never leaves a branch queued or running.

The card drawer timeline groups each region entry (RE440). Relay.Runs.RunDetail reads the run_branches that Runs.list_runs_for_card/1 preloads and turns each fan_out execution that opened an entry into one :region row: the fan_out as its header, a tally (RunDetail.branch_tally/1), and one lane per branch in position order — never start order — with loop rows computed within the lane. A branch held back by max_parallel shows a :queued placeholder; an in-flight branch node stays active even while a sibling parks the run. An open region is followed by a synthetic :waiting fan_in row; a joined one annotates the real fan_in with join (total / failed) and the row after it with joined_from. A region entered twice renders twice, one group per fan_out execution. RunDetail.branch_bars gives each fan_out key its latest entry's per-branch bars (RunDetail.branch_bar/1, closed set bar_states/0), and the card-face summary carries branches — the open entry's tally plus its bars, nil once it joins (Runs.open_region/1's rule, read for the whole board in one query). Runs.happy_path/1 still steps from the fan_out straight to its fan_in, so a card face reads "node N of M" against the fan_out while the region is open. The full engine rules are in runner.md; the runner side — concurrent node jobs in one worktree — is in runner.md's worktree pool.

Sources of truth: lib/relay/application.ex, lib/relay/events.ex, lib/relay/agent_log.ex, lib/relay/board_watch.ex, lib/relay_web/api_log.ex, lib/relay/runs.ex, lib/relay/runs/supervisor.ex, lib/relay/runs/listener.ex, lib/relay/runs/runner_reaper.ex, lib/relay/runs/, lib/relay/talk.ex.