feat(cli): add a read-only \conductor status\ command

AGENTS.md

@@ -39,6 +39,8 @@ uv run conductor run workflow.yaml --web --input question="What is Python?"
 uv run conductor run workflow.yaml --web-bg --input question="What is Python?"
 
 # Stop a background workflow
+uv run conductor status                 # list background workflows, never stops one
+uv run conductor status --json          # machine-readable
 uv run conductor stop                  # auto-stop if one running, list if multiple
 uv run conductor stop --port 8080      # stop specific port
 uv run conductor stop --all            # stop all background workflows

CHANGELOG.md

@@ -9,6 +9,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- **`conductor status` — see what is running without stopping it** (#384).
+  `conductor stop` with no arguments lists background workflows, but stops one
+  when exactly one is running, so the natural "what's running?" reflex was
+  destructive precisely when there was a single run to lose. `status` never
+  terminates anything and never removes a PID file, so a run stays
+  discoverable even when its liveness cannot be confirmed. It prints each
+  run's dashboard URL, which is otherwise unrecoverable once the launching
+  terminal is gone, and `--json` makes it scriptable. A malformed PID file is
+  skipped with a warning rather than taking down the listing.
 - **Git-backed plugin sources** (#380). `runtime.plugins` alone resolves
   against machine state — an installed plugin name, or a path — so a workflow
   shared with a teammate still needed "first install these plugins" in a

docs/cli-reference.md

@@ -6,6 +6,7 @@ Complete command-line reference for Conductor.
 
 - [Root-Level Options](#root-level-options)
 - [`conductor run`](#conductor-run)
+- [`conductor status`](#conductor-status)
 - [`conductor stop`](#conductor-stop)
 - [`conductor gate respond`](#conductor-gate-respond)
 - [`conductor checkpoint list`](#conductor-checkpoint-list)
@@ -226,6 +227,44 @@ Line 2
 Line 3"
 ```
 
+## `conductor status`
+
+List background workflows launched with `--web-bg`, without stopping any of them.
+
+```bash
+conductor status [OPTIONS]
+```
+
+### Options
+
+| Option | Description |
+|--------|-------------|
+| `--json` | Emit machine-readable output instead of a table |
+
+### Why This Exists
+
+`conductor stop` with no arguments also lists running workflows — but it *stops* one when exactly one is running, so the natural "what's running?" reflex is destructive precisely when there is a single run to lose. `conductor status` never terminates anything.
+
+It is also read-only on disk: unlike `stop`, it never removes a PID file, so a run stays discoverable even if its liveness cannot be confirmed at that moment.
+
+The dashboard URL is included because there is otherwise no supported way to recover it once the launching terminal is gone.
+
+### Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| `0` | Listed successfully, including when nothing is running |
+
+### Examples
+
+```bash
+# What is running right now?
+conductor status
+
+# Machine-readable, for scripts
+conductor status --json
+```
+
 ## `conductor stop`
 
 Stop background workflow processes launched with `--web-bg`.

plugins/conductor/skills/conductor/references/execution.md

@@ -86,7 +86,31 @@ conductor run workflow.yaml --web-bg --input question="Hello"
 
 The `--web` flag opens a browser dashboard with a DAG visualization showing live agent status, streaming reasoning/tool calls, and an agent detail panel. The `--web-bg` flag forks a background process and exits immediately. `--web` and `--web-bg` are mutually exclusive.
 
-Background workflows can be stopped with `conductor stop` (see below) or via the stop button in the web dashboard.
+Background workflows can be listed with `conductor status` (read-only), and stopped with `conductor stop` (see below) or via the stop button in the web dashboard.
+
+### conductor status
+
+List background workflows launched with `--web-bg`, without stopping any of them:
+
+```bash
+conductor status [OPTIONS]
+```
+
+| Option | Description |
+|--------|-------------|
+| `--json` | Emit machine-readable output instead of a table. |
+
+Use this rather than a bare `conductor stop` to answer "what is running?". `conductor stop` with no arguments **stops** the workflow when exactly one is running, so the natural reflex is destructive precisely when there is a single run to lose. `status` never terminates anything, and it prints each run's dashboard URL, which is otherwise unrecoverable once the launching terminal is gone.
+
+**Examples:**
+
+```bash
+# What is running right now?
+conductor status
+
+# Machine-readable, for scripts
+conductor status --json
+```
 
 ### conductor stop
 

src/conductor/cli/app.py

@@ -1112,6 +1112,71 @@ async def _run_replay() -> None:
             console.print("\n[dim]Replay stopped.[/dim]")
 
 
+@app.command(rich_help_panel="Run & Recover")
+def status(
+    json_output: Annotated[
+        bool,
+        typer.Option(
+            "--json",
+            help="Emit machine-readable output instead of a table.",
+        ),
+    ] = False,
+) -> None:
+    """List background workflows without stopping any of them.
+
+    \b
+    `conductor stop` also lists running workflows, but it stops one when
+    exactly one is running -- so the natural "what's running?" reflex is
+    destructive precisely when there is a single run to lose. This command is
+    read-only and always safe.
+
+    The dashboard URL is included because there is otherwise no supported way
+    to recover it once the launching terminal is gone.
+
+    \b
+    Exit codes:
+        0  listed successfully (including when nothing is running)
+
+    \b
+    Examples:
+        conductor status
+        conductor status --json
+    """
+    import json
+
+    from conductor.cli.pid import scan_pid_files
+
+    # Deliberately not ``read_pid_files``: that one prunes as it reads, which
+    # would make the read-only command destructive — the exact trap this
+    # command exists to give people an alternative to.
+    running = scan_pid_files()
+
+    if json_output:
+        payload = [
+            {
+                "pid": e["pid"],
+                "port": e["port"],
+                "workflow": str(e.get("workflow", "")),
+                "run_id": e.get("run_id", ""),
+                "started_at": e.get("started_at", ""),
+                "log_file": e.get("log_file", ""),
+                "url": f"http://127.0.0.1:{e['port']}",
+            }
+            for e in running
+        ]
+        output_console.print_json(json.dumps({"running": payload}), ensure_ascii=True)
+        return
+
+    if not running:
+        console.print("[dim]No background workflows are currently running.[/dim]")
+        return
+
+    _print_running_list(running, console, show_url=True)
+    console.print(
+        f"\n[dim]{len(running)} running. Use 'conductor stop --port <PORT>' to stop one.[/dim]"
+    )
+
+
 @app.command(rich_help_panel="Run & Recover")
 def stop(
     port: Annotated[
@@ -1229,12 +1294,16 @@ def _stop_process(entry: dict, con: Console) -> None:
         )
 
 
-def _print_running_list(entries: list[dict], con: Console) -> None:
+def _print_running_list(entries: list[dict], con: Console, show_url: bool = False) -> None:
     """Print a table of running background workflows.
 
     Args:
         entries: List of PID-file dicts.
         con: Rich Console for output.
+        show_url: Append a Dashboard URL column. Defaults to False;
+            ``conductor status`` passes True, since discovery is its whole
+            purpose and the URL is otherwise unrecoverable once the launching
+            terminal is gone.
     """
     from rich.table import Table
 
@@ -1243,14 +1312,19 @@ def _print_running_list(entries: list[dict], con: Console) -> None:
     table.add_column("PID", style="yellow")
     table.add_column("Workflow", style="white")
     table.add_column("Started", style="dim")
+    if show_url:
+        table.add_column("Dashboard", style="blue")
 
     for e in entries:
-        table.add_row(
+        row = [
             str(e["port"]),
             str(e["pid"]),
             Path(e.get("workflow", "unknown")).stem,
             e.get("started_at", "?"),
-        )
+        ]
+        if show_url:
+            row.append(f"http://127.0.0.1:{e['port']}")
+        table.add_row(*row)
 
     con.print(table)
 

src/conductor/cli/pid.py

@@ -129,6 +129,54 @@ def write_pid_file(
     return filepath
 
 
+def scan_pid_files() -> list[dict]:
+    """Read every PID file **without modifying anything on disk**.
+
+    :func:`read_pid_files` is the maintenance path: it prunes as it goes, which
+    is right for ``stop`` and wrong for anything whose contract is to observe.
+    A reader that deletes turns a diagnostic command into the one that loses the
+    run it was asked about — and because ``write_pid_file`` is not atomic, a
+    scan landing inside a launch can see a half-written file and treat a live
+    workflow as garbage.
+
+    Malformed entries are skipped rather than raised on: one unparseable file in
+    the directory must not take down the listing of every other run. Entries
+    without an integer ``pid`` and ``port`` are skipped too, because every
+    caller indexes both.
+
+    Returns:
+        List of dicts for processes that are still alive, in filename order,
+        each with the PID file's contents plus ``file``.
+    """
+    d = pid_dir()
+    results: list[dict] = []
+
+    # Sorted rather than raw glob order: the listing is user-facing, and
+    # ``Path.glob`` order is filesystem-dependent.
+    for f in sorted(d.glob("*.pid")):
+        try:
+            data = json.loads(f.read_text())
+        except (json.JSONDecodeError, OSError) as exc:
+            logger.warning("Skipping unreadable PID file %s: %s", f, exc)
+            continue
+
+        if not isinstance(data, dict):
+            logger.warning("Skipping PID file whose contents are not an object: %s", f)
+            continue
+
+        pid = data.get("pid")
+        port = data.get("port")
+        if not isinstance(pid, int) or not isinstance(port, int):
+            logger.warning("Skipping PID file without an integer pid and port: %s", f)
+            continue
+
+        if _is_process_alive(pid):
+            data["file"] = str(f)
+            results.append(data)
+
+    return results
+
+
 def read_pid_files() -> list[dict]:
     """Read all PID files and return info for processes that are still alive.
 

tests/test_cli/test_help_panels.py

@@ -38,7 +38,17 @@ def test_all_panel_titles_present(self) -> None:
     def test_flat_commands_listed(self) -> None:
         result = runner.invoke(app, ["--help"], env=_WIDE)
         assert result.exit_code == 0
-        for cmd in ("run", "resume", "stop", "replay", "validate", "show", "update", "doctor"):
+        for cmd in (
+            "run",
+            "resume",
+            "status",
+            "stop",
+            "replay",
+            "validate",
+            "show",
+            "update",
+            "doctor",
+        ):
             assert cmd in result.output
 
     def test_noun_groups_listed(self) -> None:
@@ -59,6 +69,7 @@ def test_commands_mapped_to_correct_panels(self) -> None:
         expected = {
             "run": "Run & Recover",
             "resume": "Run & Recover",
+            "status": "Run & Recover",
             "stop": "Run & Recover",
             "replay": "Run & Recover",
             "validate": "Author & Inspect",