@nutteen/conductor-ui 0.1.0

package/README.md

@@ -0,0 +1,383 @@
+# Conductor Control Room
+
+A desktop viewer for Conductor: per ticket, **the graph**, **live state on that graph**, and
+**the audit log**.
+
+`conductor control-tower` prints a one-shot table and `conductor logs -f` prints raw JSONL.
+This is the same data, drawn.
+
+```bash
+npm run build --workspace apps/conductor-ui
+npm run dev   --workspace apps/conductor-ui       # electron-vite dev server
+
+# Options (all optional)
+electron apps/conductor-ui \
+  --config conductor-runner/flows.yaml \  # which flows to start/stop; remembered between launches
+  --runtime-dir ~/.conductor \      # defaults to CONDUCTOR_RUNTIME_DIR, then ~/.conductor
+  --ticket IST-128 \                # open straight to a ticket instead of the config view
+  --tab graph|state|audit|config \  # which panel that deep link lands on
+  --capture shot.png                # render, save a PNG, exit
+```
+
+## The CLI does not depend on this
+
+The app **reads** files the daemon writes, and **starts and stops the daemon by running the
+same CLI you would run yourself** — `conductor start <flow>` / `conductor stop <flow>`, as a
+detached subprocess. It never reaches *into* a running daemon: no socket, no control file, no
+new flag on `run`. The only signal it sends is the `SIGTERM` that `conductor stop` already
+sends, and a daemon started from the app keeps running after you quit it.
+
+That distinction is the whole of it. Spawning `conductor start` is exactly what a terminal
+does and the daemon cannot tell the difference; a socket or a signal protocol would be a new
+process contract, and *that* is what these guarantees protect.
+
+| Guarantee | How it is held |
+|---|---|
+| `apps/conductor` gains no runtime deps | still `js-yaml` + `liquidjs`; `src/lib.ts` is re-export only |
+| The published CLI package is unchanged in shape | `files: ["dist/src", "README.md"]` and `bin` untouched |
+| No IPC *into* a running daemon | no socket, no control file, no hooks, no new flags on `run`; `lib.ts` exports no lifecycle symbol and `tests/lib.test.ts` fails the build if one appears |
+| Every UI action has a CLI equivalent | Start/Stop/Restart shell out to `conductor start\|stop`; the app adds no capability the terminal lacks — notably no `SIGKILL` escalation |
+| The app never writes to the runtime dir | records and pid files are still written by the CLI; the app's own remembered config path lives in Electron `userData` |
+| The daemon outlives the app | it is spawned detached and `unref`'d, so `tail.ts`'s "stopping the app stops a reader, nothing else" stays literally true |
+| The CLI's own output is unchanged | `buildRunSnapshotsFromLogLines` and `control-tower` still emit one row per `(ticket, attempt)`; nothing in the CLI's runtime path imports `replay.ts` |
+| Deleting this workspace breaks nothing | nothing in `apps/conductor` imports it |
+| It works with **no daemon running** | it reads historical JSONL; liveness is `isProcessRunning`, never a requirement |
+
+`scripts/check.sh architecture` machine-checks the read/write split: `src/main/sources.ts` may
+not import `child_process`, signal a pid or write a file — all of that lives in
+`src/main/daemon.ts`, which is also why `sources.ts` can keep its header rule literally true.
+
+`scripts/check.sh conductor` is deliberately a separate scope from
+`scripts/check.sh conductor-ui`, so the first keeps passing with this directory deleted.
+
+**Where the app and the CLI differ, precisely.** Both read the same log through the same
+library, and every number still comes from the CLI's own functions. What differs is grouping:
+`conductor control-tower` prints one row per `(ticket, attempt)`, whereas the sidebar here is
+**ticket-level** — one row, badged `N runs` — and the detail panels are **dispatch-level**,
+with earlier dispatches behind the run switcher. That is a presentation choice on top of
+shared data, not a second parser.
+
+The one real risk was the `exports` map: `apps/conductor/package.json` had no `main` or
+`exports`, so deep paths resolved freely, and adding `exports` *restricts* resolution. It
+therefore ships a `"./dist/src/*"` wildcard alongside `"."` and `"./lib"`, and
+`apps/conductor/tests/lib.test.ts` asserts that.
+
+## Starting and stopping a flow
+
+Start, Stop and Restart sit in the topbar. Each is a shell-out:
+
+| Button | What it runs |
+|---|---|
+| `Start…` | `conductor --config <flows.yaml> start <flow>` |
+| `Stop` | `conductor --config <flows.yaml> stop <flow>` |
+| `Restart…` | `stop`, then wait for the pid to be gone, then `start` |
+
+**Start and Restart confirm first, and the preflight runs inside the dialog.** Starting a flow
+is not free: it sweeps workspaces, then autonomously dispatches tickets, spends tokens and
+opens pull requests. The dialog names the resolved workspace root, how many directories are
+under it, and the owner-scoped rule the sweep uses — Conductor reads each directory's
+`.conductor-owner` marker and only removes ones owned by that flow or unmarked. (It is
+*Symphony's* cleanup that is unscoped; that is what `flows.yaml`'s longest comment is about.)
+It does not say which directories will go: that needs a tracker query, and opening a dialog
+should not make one.
+
+The checks are split by who can actually see the answer. **The CLI owns config and graph
+correctness** — `preflightFlows` in `apps/conductor` is the same function `conductor start`
+gates its spawn on, so a second copy cannot drift from it. **The app owns the host
+environment**, which the CLI cannot see because it inherits a terminal's.
+
+The session probe is `ist auth whoami`, not `ist auth status`. `status` is a **local** check:
+it reads the token file and reports `expired` from its own `expiresAt`, so a token the server
+has since rejected still passes it. Observed on a real machine: `status` printed
+`"authenticated": true, "expired": false` while `whoami` returned *"Your session has
+expired"* — and `startOrchestrator` calls `whoami` and refuses to start without it. A
+preflight that passes where the daemon fails is worse than no preflight.
+
+### The host environment is the whole risk
+
+A GUI-launched Electron app never sourced `~/.zprofile`. Its `PATH` is the bare
+`/usr/bin:/bin:/usr/sbin:/sbin` macOS hands a double-clicked app, and none of `ist`, `claude`,
+`git`, `gh` or `uv` is on it. That matters more than it sounds, because **an `ist auth` failure
+is not fatal in the daemon**: `orchestrator.ts` logs `Dispatch skipped: ist auth check failed`
+and keeps polling forever, doing nothing. A daemon spawned with a stripped PATH looks perfectly
+healthy and accomplishes nothing at all.
+
+So `host-env.ts` asks the login shell for its PATH once — `$SHELL -lc` with the value wrapped
+in sentinel markers, because login shells emit MOTDs, nvm banners and `direnv` chatter, and
+`-lc` rather than `-ilc` because interactive mode can block on a prompt. PATH only, not the
+whole environment: every version manager works by putting real directories on PATH, and
+importing a stale login env over Electron's own is a far larger surface than the problem.
+Every failure path — no `$SHELL`, non-zero exit, timeout, no markers — falls back to the
+inherited PATH and says so in the dialog; none of them throws.
+
+The same capture answers the other hazard for free. `process.execPath` inside Electron is the
+**Electron binary**, so spawning the CLI with it would fork Electron rather than node; the
+`node` on the login PATH is both simpler and more faithful than `ELECTRON_RUN_AS_NODE=1`,
+which is kept only as the fallback. When a real `node` is used, every `ELECTRON_*` key is
+stripped from the daemon's environment — it lives for days and spreads its env into every
+`claude`, `git`, `gh` and `npm` it spawns, and a stray `ELECTRON_RUN_AS_NODE=1` reaching a
+subprocess that happens to be an Electron app makes it start in node mode and silently do
+nothing.
+
+### Why the dot is never driven by `stopped_at`
+
+`conductor stop` sends one `SIGTERM`, writes `stopped_at` and removes the pid file
+**synchronously and unconditionally** — while the daemon's `shutdown()` aborts in-flight graphs
+and *awaits* them, which can take minutes. So a record that says stopped is routinely a record
+whose process is still alive and still holding a workspace.
+
+Liveness is therefore `isProcessRunning(pid)` and nothing else. `stopped_at` is used for one
+thing: telling a clean stop apart from a crash, which is the **`stale`** state — a pid, no
+`stopped_at`, and no process. The topbar used to hide that behind "no daemon running".
+
+`renderer/lifecycle.ts` holds the rule as a pure function of `(flow, pending, now, draining)`,
+so it unit-tests with a fake clock. Transitional states are overlays with a ~15 s deadline that
+clear the moment a `FlowInfo` disagrees; the deadline is what stops a spinner spinning forever
+when a spawn dies before writing a record, and when it lapses it says where to look — the
+daemon detaches and logs to JSONL, so its own startup failure never reaches the spawn's stderr.
+
+**A restart that times out starts nothing.** This is the subtlest trap in the feature: calling
+`start` while the old daemon is still alive makes `startManaged` print `IST already running
+(PID …)` and exit **0**, so a naive restart reports success having done nothing but SIGTERM a
+daemon. Instead the flow holds a distinct **draining** state — a `SIGTERM` has been sent to a
+pid that is still alive — which a plain Stop also enters, and which clears itself the moment
+that pid is gone.
+
+**Draining offers the log and nothing else, and that is a safety property.** `runForeground`
+registers `process.once("SIGTERM", …)`, so after the first signal the handler is removed and
+Node restores default termination: a **second** `conductor stop` during a drain does not hurry
+the daemon, it hard-kills it, orphaning an agent mid-`git push`. So Stop and Restart are both
+off the screen while draining, and the button opens the log — which is where the wait explains
+itself (`Shutdown: waiting for N in-flight run(s) to complete`). There is no `SIGKILL`
+escalation anywhere; if force-stop is ever wanted it belongs in the CLI as
+`conductor stop --force`, where it can shut down cleanly rather than from outside.
+
+`pid: 0` gets its own guard, because `isProcessRunning(0)` returns **true** —
+`process.kill(0, sig)` signals the entire process group, which from this app includes the app
+itself. Every liveness question goes through `isLivePid`, which requires a positive integer
+first.
+
+## Editing `flows.yaml`
+
+The Config tab shows every declared flow, what it declares and what that resolves to, and can
+edit it. **Edits are line-level splices with a diff preview and an explicit confirmation, never
+`yaml.dump`.**
+
+Nothing in this repo writes YAML — every use is `yaml.load` — and `conductor-runner/flows.yaml`
+is 18 lines of which **10 are comments**, one of them the reason a Symphony restart does not
+`rm -rf` Conductor's working trees. A `load` → mutate → `dump` round trip deletes all ten on
+the first save.
+
+So `flows-file.ts` is pure string → string: it parses the file into line spans, plans splices,
+and copies **every line the plan does not name by reference**. "Untouched bytes are identical"
+holds by construction. The diff is derived from the same splices that perform the write, which
+makes a preview that differs from the write structurally impossible — which is why it is
+hand-rolled rather than a re-diff of two texts.
+
+Comments are attributed by walking *up* from a field while the line is a comment at the same
+indent, stopping at a blank line. That is what binds the Symphony warning to `workspace_root`:
+removing that field removes its comment, visibly, in the diff, and editing a different field
+leaves it alone.
+
+It **refuses** rather than guesses, naming the offending lines, for block sequences, block
+scalars, multi-document files, mixed line endings, and especially anchors / aliases / merge
+keys — with a merge key the effective config is not the lines you can see, so a line edit would
+be a *silent* lie rather than a visible one.
+
+`flows-config.ts` supplies the filesystem half. Validation writes the candidate to
+`<configPath>.preview.<pid>` — a **sibling**, not `tmpdir()`, because `loadManagedConfig`
+resolves `./workflows/IST.md` against the config file's own directory and a copy elsewhere
+reports a bogus "workflow not found". The write is tmp + rename with a `.bak`, preserving the
+file mode, then re-reads and asserts it still loads, restoring from the backup if not. Preview
+and commit are two round trips, so the commit token pins the *before* text and is re-checked
+against disk: an edit made in vim in between is refused, not clobbered.
+
+**One thing the checker cannot see.** `flowCollisions` compares flows *within one config file*.
+Symphony's `workspace_root` lives in `symphony-runner/`, which this loader never reads — so the
+editor validates Conductor-vs-Conductor collisions and is blind to the Conductor-vs-Symphony
+one. That comment in `flows.yaml` is not made redundant by this panel.
+
+`runtime_dir` is deliberately read-only here: changing it orphans every record, log, pid file
+and checkpoint under the old directory, with no migration.
+
+## Why the JSONL is the source, not the checkpoint
+
+**Live graph state is deleted the moment a run ends.** `~/.conductor/graph/<flow>/<TICKET>.json`
+is the only place holding `cursor`, `state`, `node_history` and `traversals`, and
+`orchestrator.ts` removes it at `__end__` — keeping it would make the next dispatch resume
+into a completed run.
+
+So a per-ticket view built on the checkpoint alone is **blank for every finished ticket** and
+only works mid-run. It looks fine right up until the run ends.
+
+The log is the durable record. `node_started`, `node_completed`, `node_failed` and
+`edge_taken` are enough to reconstruct the walk, which is what
+`@nutteen/conductor/lib`'s `replayWalks` does — using the same bookkeeping rules
+`graph/executor.ts` uses live.
+
+They do *not* produce identical numbers, and the difference matters: a **checkpoint**
+belongs to a ticket and its `node_history` spans every resume, while a **replayed run**
+covers one dispatch. The checkpoint is also live state, so it is attached to the ticket's
+most recent run only — hanging it off an older one would draw a run's graph with another
+run's values on it.
+
+That also collapses two of the four asks into one pipeline: **the audit log and the graph
+state are the same events, rendered differently.**
+
+The checkpoint is still read, for one thing the log does not have: **state values**.
+`node_completed.writes` is a list of key *names*, so the log can say the reviewer set
+`review_verdict` and can never say what it set it to. The State panel says so rather than
+rendering a blank that reads as "unset".
+
+### What a "run" is
+
+**One `graph run starting` line — one per `dispatchIssue` — begins exactly one graph walk.**
+Not one attempt. `state.retry_attempts` lives in memory in the daemon and is rebuilt on every
+start, so the counter resets on restart and is not a run identity: in the real IST log,
+IST-116 was **dispatched 15 times under 3 distinct attempt numbers**, 10 of those dispatches
+sharing attempt 1 — and the numbers are not even monotonic in time, since attempt 1 was still
+logging at 02:41 after attempts 2 and 3 ended at 02:35 and 02:28.
+
+Two things followed from keying on attempt, and both are fixed here: "the highest attempt is
+the current run" returned a run that had finished *before* two others, and ten dispatches
+concatenated into one walk produced a history with 24 node entries but only 16 edges — with
+`checks -> checks -> checks` runs that no edge ever connected.
+
+| | |
+|---|---|
+| Detection | `run_started: true`, or `started_at` as the structural fallback. Never `phase` prose. |
+| Run id | `` `${identifier}#${startedAtIso}` `` — stable across re-reads, because the log window slides and a positional index would not. |
+| Resumed dispatch | Its own run, *labelled* `resumed_at`, so each run's `node_history` lines up with its own edges. |
+| Window opened mid-run | Kept as `partial: true` under `` `${identifier}#~${firstEventTs}` ``, rather than dropped. |
+
+Ordinals — "run 12 of 15" — are display only.
+
+### `run_event`
+
+Every graph event line now carries `run_event: "<kind>"`, so a reader recovers the event kind
+by reading a field instead of pattern-matching `phase` prose. Logs written before it are read
+by `inferRunEventKind`, which keys off field shape — with one exact-match exclusion list,
+because several whole-run lifecycle lines carry `nodes_visited` exactly as
+`worker_exited_normal` does, and field shape alone reports a budget halt as a clean exit.
+
+## Two modes, one renderer
+
+`GraphView` is a pure function of `GraphSpec` plus an optional overlay, so ticket state stays
+out of the component and it is testable against a fixture with no daemon and no runtime data.
+
+**Config mode** (`overlay === null`) — a workflow's declared graph, no ticket. Shows what is
+otherwise only readable as YAML: node kinds, which `agents:` profile *and model* each node
+binds to, edge predicates, loop budgets, back edges, `on_error` behaviour, and
+`on_enter.tracker_status` transitions. Works with no daemon and no ticket ever dispatched.
+
+It also **surfaces validation inline**. A workflow that fails to load is a rendered
+diagnostic, not a crash — and where the message names a node or an edge, it is drawn there.
+This is the view that would have made `unknown builtin 'record_validation'` obvious
+immediately, instead of leaving a daemon walking an older graph for three hours behind one
+warning line.
+
+**Ticket mode** — the same drawing, restyled: current node, visited path, and loop pressure
+(traversals against each edge's `max_traversals`).
+
+Layout is computed once per `GraphSpec` and only CSS classes change as events stream in.
+Not mermaid: it re-renders the whole SVG from a text source on every change, which flickers
+and drops pan position on a live graph. Not dagre either — the graph is small and strictly
+layered apart from its back edges, which want to be drawn as arcs rather than reversed, and
+keeping the dependency tree small matters for something that must never become load-bearing.
+
+### Reading the drawing
+
+**It runs left to right.** Layers advance along x; nodes sharing a layer stack along y.
+Top-down, IST's nine-stage pipeline was a 460×1448 ribbon inside a ~1130px panel — 40% of
+the width used, vertical scrolling, and `__end__` off-screen. Sideways it is ~2850×392,
+because the widest layer is two nodes (`check_plan`/`land`, `plan`/`merge_pr`). The layering
+passes are unchanged; only the axis the result lands on is.
+
+**An edge into `__end__` may be drawn as a stub** — a short drop out of the bottom of its
+source ending in a bar, rather than a line across the whole picture. That happens when the
+source *also* has a way to carry on, which is every `on_error` edge plus `__start__ -> __end__`
+(the ticket is already handled) and `checks -> __end__` (the gate gave up): seven of IST's
+edges, and most of its former crossing clutter. `handoff -> __end__` and `merge_pr -> __end__`
+stay real lines, because ending is all those nodes have left to do — both pipelines still
+visibly terminate somewhere. A stub carries the same label, the same tooltip and the same
+`id`/`from`/`to`, so `traversals` still keys on it and a failed run reads *better* than it
+did: the taken edge is next to the node that failed. Stubs are excluded from the layering
+pass exactly as back edges are, so a failure edge cannot stretch the layer of a sink it no
+longer reaches.
+
+**Anything that would cut across the row is routed under it**: back-edge loops, and forward
+edges spanning more than two layers (`merge_pr -> __end__`). Each gets its own depth lane,
+and they label themselves on a row below the deepest of them.
+
+**The gap between two columns is label space.** A forward edge's predicate is anchored in
+the corridor immediately right of its source — the one place with no node boxes in it — and
+the corridor is widened to fit the widest label anchored there. Predicates truncate at 40
+characters on the canvas and are complete in the `<title>`.
+
+**It has its own contrast rules.** The shared palette — mirrored from `apps/web` so
+the two read as one product — draws borders at about 2:1 against their background,
+which is right where text carries the meaning and a loud rule would only shout. A
+node-link diagram is the one place in this app where the boxes and the lines *are*
+the content, and at those values a node box measured 1.05:1 against the canvas and an
+edge 1.79:1. The `--graph-*` variables in `styles.css` are the exception: 3.5:1 and
+5.3:1 in dark, 5.2:1 and 8.6:1 in light, against a canvas dropped to `--color-shell`.
+`tests/theme.test.ts` parses the stylesheet and asserts the ratios, because the
+failure mode here is a number being wrong, not anything throwing.
+
+**It fits the panel, with a floor.** The canvas scales down to 75% and then the panel
+scrolls horizontally, because scaling a nine-stage pipeline into ~1130px puts node text at
+about 5px. Selecting a ticket scrolls its current node to the middle, which is the "where is
+my run" question the panel exists to answer.
+
+## Dark and light
+
+Dark by default, light by `data-theme="light"` on `<html>` — the same mechanism and
+the same token values as `apps/web`, minus its plumbing, which round-trips the choice
+to the tracker API against an authenticated user. With no explicit choice the viewer
+follows the OS, which is the fix for the original complaint: it used to force dark on
+a light desktop.
+
+An explicit choice is persisted **by main**, in `preferences.json` under
+`app.getPath("userData")`. Not `localStorage`, which is the obvious answer and does
+not work: the renderer is loaded with `loadFile`, so it is a `file://` document, and
+Chromium gives one of those an opaque storage bucket — writing succeeds, reading back
+in the same window succeeds, and the value is gone on the next launch. Verified by
+launching the app twice, not assumed.
+
+It comes back to the renderer through the preload's `additionalArguments` as
+`window.conductor.storedTheme`, a plain value rather than a promise, because it has
+to be known *before* the first paint; an awaited answer is one frame of the other
+theme on every launch. `BrowserWindow`'s `backgroundColor` is chosen from the same
+value, since that is painted before any HTML exists at all.
+
+## Architecture
+
+```
+Electron main (Node)                        Electron renderer (React, sandboxed)
+────────────────────                        ────────────────────────────────────
+imports @nutteen/conductor/lib               Tickets  ← RunSnapshot[]
+  buildControlTowerReport()  ─── IPC ──►     Graph    ← SerializableGraphSpec + overlay
+  loadWorkflow() → GraphSpec                 State    ← checkpoint.state / replayed writes
+  readGraphCheckpoint()                      Audit    ← RunEventRecord[]
+  replayWalks()
+tail on IST.jsonl ───── IPC push ──────►     (live updates)
+watchWorkflow() ─────── IPC push ──────►     (redraw on save)
+```
+
+No HTTP server and no SSE: in Electron the main process is already Node, so it tails the
+JSONL and pushes over IPC. The renderer runs with `contextIsolation` and no Node, which is
+also why it cannot read `~/.conductor` itself — everything it shows crosses the typed surface
+in `src/shared/contract.ts`.
+
+Everything crossing that boundary must survive `structuredClone`: no `Map`, no `Set`, no
+compiled predicate. `EdgeSpec.when_expr` is stripped by `serializableGraphSpec`; the `when`
+source text is what gets rendered.
+
+Every rendered string passes through `redactSensitive` in the main process first.
+
+## Known limitation
+
+The graph drawn is the workflow **as it is now**, with a historical walk overlaid. A ticket
+that ran under an earlier revision can therefore reference nodes the current graph no longer
+declares — they simply do not appear. The audit log still shows them, because it is the raw
+event stream.

package/bin/conductor-ui.js

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+/* eslint-disable no-undef */
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { spawn } from "node:child_process";
+
+const require = createRequire(import.meta.url);
+const electron = require("electron");
+const appDir = join(dirname(fileURLToPath(import.meta.url)), "..");
+
+const child = spawn(String(electron), [appDir, ...process.argv.slice(2)], {
+  stdio: "inherit",
+  windowsHide: false,
+});
+
+child.on("close", (code) => process.exit(code ?? 0));