relay-flow 0.2.0-alpha → 0.2.1-alpha

package/README.md

@@ -14,7 +14,7 @@ This is a ground-up rewrite. The previous per-workflow, in-memory daemon is gone
 |---|---|
 | [opencode](https://opencode.ai) | Agents run in opencode sessions (harness) |
 | [Orca](https://github.com/Necmttn/orca) CLI + app | Worktrees + terminals (runner) |
-| [acli](https://developer.atlassian.com/cloud/acli) | Jira access (task system) |
+| Jira API token | Jira REST API v3 access (task system) |
 | Go 1.24+ | Build the CLI |
 
 ### Install
@@ -32,20 +32,22 @@ OpenCode plugin: add `"relay-flow-plugin"` to the `plugin` array in your repo's
 }
 ```
 
-The plugin is the report-path half of the harness contract: it parses the agent's structured report, applies the agent/HITL nudge policy, and delivers `{runId, node, reportId, report}` via `relay-flow report` with retry.
+The plugin is the report-path half of the harness contract: it registers each emitted harness session with `{runId, node, sessionId}`, parses the agent's structured report, applies the agent/HITL nudge policy, and delivers `{runId, node, reportId, report}` via `relay-flow report` with retry. `reportId` comes from the harness session/message identity; `nodeVisitID` is internal and is never part of either plugin payload.
 
 ### One-time machine setup
 
 ```sh
 relay-flow init
+relay-flow task auth
 ```
 
-Prompts for the three plugin names (`task`, `runner`, `harness` — e.g. `jira`, `orca`, `opencode`), atomically writes `~/.relay-flow/config.yaml` (0600), and initializes `~/.relay-flow/state.db`. Refuses to overwrite existing configuration or history.
+`init` only selects the task system, runner, and harness (singleton options are automatic), writes machine config, and initializes SQLite. `task auth` delegates authentication to that selected task plug-in. Jira prompts for its site, email, and masked API token, validates `/myself`, and owns the system-wide `credentials.yaml`; for scripts, pass `task auth --site`, `--email`, and `--token`. A normal init rerun refuses existing state. `relay-flow init --force` updates safe stopped instances while preserving durable and repo state.
 
 The full machine layout is fixed under `~/.relay-flow` (0700):
 
 ```
 config.yaml           0600  machine config
+credentials.yaml      0600  selected task plug-in credentials
 state.db              0600  durable execution (SQLite)
 server.sock           0600  CLI ↔ server
 server.lock           0600  single-process flock
@@ -60,7 +62,11 @@ workflows/<name>.yaml 0644  submitted workflow definitions
 relay-flow repo register
 ```
 
-Discovers/selects a runner repo, collects the task plugin's required keys, validates runner + task connectivity, and atomically saves. Registration is rejected while another registered repo already holds the same canonical task scope (e.g. same Jira site+project+component).
+Shows a multi-select titled `Select repositories`; use Space to select Orca repos and Enter to confirm. Enter the Jira project once. Each repo is registered sequentially with its Orca name/path and a Jira component derived from that repo name. Earlier registrations remain if a later one fails.
+
+Each Jira poll uses REST v3 enhanced search and requests linked-issue status with the candidate fields. Tickets with any unfinished inward `Blocks` issue are filtered before routing; no per-ticket blocker lookup is made.
+
+For scripts, use `relay-flow repo register --name <name> --path <path> --set project=<project>`. Component is always derived from `--name` and cannot be overridden. Registration is rejected while another repo already holds the same canonical task scope.
 
 ### Submit a workflow
 
@@ -70,14 +76,19 @@ relay-flow workflow submit --file <path>
 
 Workflows live at `~/.relay-flow/workflows/<name>.yaml` after submit. Replacement and removal are rejected while any run of that workflow is active.
 
+Use [`examples/default-story-workflow.yaml`](examples/default-story-workflow.yaml) as a fully annotated starting point. Replace its repo name and uncomment only the optional fields you need.
+
 ### Run
 
 ```sh
 relay-flow serve              # normal start; requires an initialized database
+relay-flow serve --background # detached; returns after the server is ready
 relay-flow serve --recover    # explicit destructive rebuild from the task system
 relay-flow stop
 ```
 
+`--background` preserves `--debug` and `--recover`, logs to `~/.relay-flow/server.log`, and remains stoppable with `relay-flow stop`. Plain `serve` remains foreground and blocking.
+
 `serve --recover` treats ALL SQLite execution state as gone, closes surviving run-owned terminals (preserving worktrees and code), resets Jira parent+mailbox state, and starts every labeled parent in a fresh deterministic run from `start` with fresh `nodeVisitID`s. Recovery never runs automatically; database loss is never inferred.
 
 ---
@@ -165,7 +176,7 @@ FEEDBACK
 
 `None` is the literal marker for an intentionally empty section. When `NEXT STEP` is `end`, every FEEDBACK field must be `None` and no feedback comment is written.
 
-The plugin delivers the report as one JSON object via `relay-flow report` stdin with the shared backoff (initial 2s, factor 2, jitter 0.2, max 5m) until acknowledged. Duplicate/stale reports are acked safely with no repeated graph effects. Invalid agent output is nudged; invalid HITL output stays silent.
+The plugin delivers `{runId, node, reportId, report}` as one JSON object via `relay-flow report` stdin with the shared backoff (initial 2s, factor 2, jitter 0.2, max 5m) until acknowledged. It derives `reportId` from the harness session/message identity. Duplicate/stale reports are acked safely with no repeated graph effects. Invalid agent output is nudged; invalid HITL output stays silent.
 
 ---
 
@@ -183,7 +194,8 @@ The plugin delivers the report as one JSON object via `relay-flow report` stdin
 - `runID` is deterministic from `repo/workflow/ticket`.
 - `nodeVisitID` is generated once per node entry as a durable replay-safe side effect; it changes on revisit and on fresh runs after `--recover`.
 - Terminal titles are stable `<ticket>:<node>` — they never carry `nodeVisitID`, workflow, or agent.
-- Report wire keys are `runId` / `node` / `reportId`; `nodeVisitID` stays internal.
+- Runtime registration is exactly `{runId, node, sessionId}`; normal execution persists that session ID and uses it to resume the harness session.
+- Reports are exactly `{runId, node, reportId, report}`; `reportId` is derived from harness session/message identity and `nodeVisitID` stays internal.
 
 ### Poll cycle