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

[Frank Li (franklixuefei)]

Fixes#384.

The problem

There is no read-only way to see which background workflows are running. The only command that lists them is conductor stop — which stops one when exactly one is running:

With no arguments, lists running background workflows. If exactly one is found, stops it automatically.

So the natural "what's running?" reflex is destructive precisely when there is a single run to lose. I killed a healthy 40-minute workflow this way: I ran conductor stop to check status, having read that as "lists, and if unambiguous, offers to stop".

The behaviour is documented, so this is not a correctness bug. But the documentation is the only thing standing between the user and data loss, and the destructive path is the shortest one to type. The asymmetry is what makes it sting — with two runs it prints a table and does nothing; with one it terminates. The safe outcome is the one that requires more runs to be active.

The change

conductor status
conductor status --json

Lists and never terminates. It reuses read_pid_files() and _print_running_list(), so this is mostly wiring existing pieces to a command that does not kill anything.

It also shows the dashboard URL, which is the field I most often actually want and which currently has no supported way to be recovered once the launching terminal is gone:

┏━━━━━━┳━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Port ┃ PID ┃ Workflow ┃ Started ┃ Dashboard ┃
┡━━━━━━╇━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━┩
│ 8080 │ 4242 │ implement│ 2026-03-03T00:00:00 │ http://127.0.0.1:8080 │
└──────┴───────┴──────────┴─────────────────────┴───────────────────────┘

--json emits pid, port, workflow, run_id, started_at, log_file, url — for the same reason stop --json exists in #383: automation should not have to parse a table.

Why a flag on stop isn't the fix

conductor stop --dry-run would work mechanically, but it keeps the hazard one typo away and leaves "list running workflows" filed under a destructive verb. Discovery is a read operation and wants a read verb.

Tests

The property under test is absolute — status must never terminate anything, in any configuration — so it is asserted directly rather than inferred from output:

test	asserts
single run listed, not stopped	_stop_process and os.kill never called — the exact scenario that costs a workflow
PID files left in place	the file is still there afterwards
multiple runs all listed	no partial listing
nothing running	exit 0, not an error
dashboard URL shown	the discovery case
--json shape	pid/port/run_id/url present
--json ASCII-safe	see below

The ASCII test is there because workflow paths are user data and can contain non-ASCII — exactly what crashed a completed run in #342. status --json is a new JSON sink, so it passes ensure_ascii=True from the start rather than inheriting that bug.

Deliberately not in this PR

Narrowing conductor stop. Now that discovery has its own home, requiring --port or --all there is defensible — but it is a breaking change to a documented behaviour and wants its own decision. Happy to follow up if you want it.

Validation

tests/test_cli matches the pre-existing baseline exactly — 22 failures before and after, measured by stashing the change rather than assumed. (Sandbox has no PyPI access so pytest-asyncio is unavailable; those async tests error identically either way.) ruff check and ruff format --check clean. Also exercised the command end-to-end against a real PID directory.

Related

#344 / #383 — conductor stop could delete the PID file without stopping the process. Once that lands, a run can survive stopand stay registered, which makes a read-only listing more valuable: it becomes the way you find the survivor. The --json payload here is deliberately shaped to line up with stop --json from that PR.

[Codecov Comments Bot (codecov-commenter)]

Codecov Report

❌ Patch coverage is 95.23810% with 2 lines in your changes missing coverage. Please review.
⚠️ Please upload report for BASE (main@17a8e12). Learn more about missing BASE report.

Files with missing lines	Patch %	Lines
src/conductor/cli/pid.py	90.47%	2 Missing ⚠️

Additional details and impacted files

@@ Coverage Diff @@## main #389 +/- ##
=======================================
Coverage ? 91.32% =======================================
Files ? 108 Lines ? 17507 Branches ? 0 =======================================
Hits ? 15989 Misses ? 1518 Partials ? 0 

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[Jason Robert (jrob5756)]

The concept is right and the scoping is disciplined, great work. Most of what follows is about closing the gap between what the command promises and what it currently does.

Everything below is reproduced against the branch rather than inferred.

The main one: status is not read-only. read_pid_files() unlinks PID files that are corrupt, missing pid, or whose process looks dead, and write_pid_file uses a non-atomic write_text. So a status that lands during a --web-bg launch reads a truncated file and deletes it. I reproduced the end state against a real background run: status printed "No background workflows are currently running", exited 0, and removed the PID file, while the process was still alive and its dashboard was still answering. stop could no longer find it either. That is issue #344's orphan, reached through the command meant to be the safe one.

The rest, briefly:

• A single malformed PID file takes down the whole listing with a traceback and exit 1, --json included, with empty stdout.
• run_id and log_file are always empty strings, because the only writer at bg_runner.py:394 never passes them.
• The Dashboard URL is cropped at 80 columns once real started_at values are involved.
• One mutation worth knowing about: changing pid.py:249 to send SIGTERM, so status kills everything it lists, passes all 8 tests.

Not anchorable to a line, so noting here: status is missing from docs/cli-reference.md, CHANGELOG.md, AGENTS.md, the help-panel map in tests/test_cli/test_help_panels.py, and plugins/conductor/skills/conductor/references/execution.md. That last one still tells agents to use conductor stop to inspect background runs, which is the habit this PR is trying to break.

Worth coordinating with #383, which rewrites this same code and introduces a tri-state Liveness. A non-destructive reader here and that refactor are the same change from two directions.

[Jason Robert (jrob5756)]

This is the sentence a user leans on to decide whether running the command is safe, and it is not accurate. read_pid_files() unlinks PID files on three paths (pid.py:150, :155, :164). Since Typer renders this as --help, the claim ships as product copy.

Suggested change

	read-onlyandalwayssafe.
	neversignalsorterminatesaprocess.

[Jason Robert (jrob5756)]

This is where the read-only property is actually lost. read_pid_files() deletes any PID file it cannot parse, and write_pid_file writes non-atomically (pid.py:127), so a status racing a --web-bg launch reads a zero-length file and removes it.

I reproduced the outcome against a live run: status reported nothing running, exited 0, deleted the file, and the workflow kept going with its dashboard still serving. After that neither status nor stop can find it.

A cleanup: bool = True parameter on read_pid_files(), called with cleanup=False here, keeps reaping in stop where deregistration is what the user asked for. Making the write atomic (os.replace) closes the other half.

[Jason Robert (jrob5756)]

port is indexed directly while the fields around it use .get(), and read_pid_files only validates pid. A PID file without port raises KeyError here, so the command exits 1 with a traceback and empty stdout. Same on the table path at line 1316.

One bad file takes out the listing for every healthy run beside it, which is the failure mode most likely to send someone relaunching. For --json consumers there is nothing on stdout to parse.

Skipping bad entries and reporting them (a sibling unreadable key in the payload, a warning on stderr for the table) keeps the good rows visible. Valid JSON that is not an object also reaches data.get("pid") at pid.py:153 and raises AttributeError outside the existing guard.

[Jason Robert (jrob5756)]

run_id and log_file are always empty in practice. The only production writer is _finalize_background_launch() at bg_runner.py:394, which calls write_pid_file(proc.pid, web_port, pid_workflow_ref) and leaves both at their "" defaults (pid.py:99-100). Confirmed on a real launch.

Automation will branch on these and take the else path every time. run_id is in scope at the call site, so threading it through is small; log_file is harder, since only the child knows its events log path, though the parent does have the bg stderr and stdout paths. Dropping them until something writes them is also fine, but shipping fields that are structurally empty is the one option I would avoid.

[Jason Robert (jrob5756)]

The URL gets cropped at the default terminal width. Production started_at is a full datetime.now(UTC).isoformat() at 32 characters, 13 wider than the 19-character value the tests write, and Rich crops rather than wraps. At 80 columns with a realistic workflow name:

| 53941 | 72319 | code-review-pipel... | 2026-08-10T14:02:... | http://127.0.0.1:... |

So the field the command exists to surface is the one that disappears. overflow="fold" on this column, or trimming sub-second precision from Started, would fix it.

Suggested change

	table.add_column("Dashboard", style="blue")
	table.add_column("Dashboard", style="blue", overflow="fold")

[Jason Robert (jrob5756)]

"On by default" reads as though the default were True; it is False, and only one of the three call sites passes True. An Args: entry describing a specific caller's policy will also drift as callers change.

Suggested change

	show_url: IncludethedashboardURLcolumn. Onbydefaultfor
	show_url: AppendaDashboardURLcolumn. DefaultstoFalse;
	``conductorstatus``passesTrue.

[Jason Robert (jrob5756)]

These two assertions cannot fail. status only calls read_pid_files() and _print_running_list(), so neither _stop_process nor conductor.cli.app.os is reachable from it. Meanwhile line 69 patches out _is_process_alive, which owns the only signal status actually sends: os.kill(pid, 0) at pid.py:249.

The practical effect is that changing pid.py:249 to send SIGTERM, which makes status terminate every workflow it lists, passes all 8 tests here plus test_stop.py and test_pid.py.

Spying the layer below pins the real property, and test_pid.py:142-160 already uses that patch target:

Suggested change

	kill.assert_not_called()
	stop_one.assert_not_called()
	kill.assert_not_called()
	deftest_liveness_probe_never_sends_a_real_signal(self, pid_tmpdir: Path) ->None:
	"""The only signal ``status`` sends must be the null probe."""
	_write_pid(pid_tmpdir, 4242, 8080)
	withpatch("conductor.cli.pid.os.kill") askill:
	runner.invoke(app, ["status"])
	assertall(call.args[1] ==0forcallinkill.call_args_list)

[Jason Robert (jrob5756)]

This helper hand-builds the PID JSON instead of calling conductor.cli.pid.write_pid_file(), and the divergence is hiding two real defects. The fixture writes a 19-character started_at where production writes 32, which is why the URL cropping above goes unnoticed. It also sets run_id, so assert entry["run_id"] == _RUN_ID at line 134 passes against a value the product never emits.

Building fixtures through the real writer couples these tests to the actual schema and catches both. #383 does this in its own tests, so it is also the direction the sibling PR is heading.

[Frank Li (franklixuefei)]

Thanks — the destructive-read finding was exactly right, and the mutation you ran (pid.py:249 → SIGTERM passing all 8 tests) is the sharpest thing in the review. Addressed in 1007086.

status was not read-only

Confirmed at source. It called read_pid_files, which prunes as it reads — unlinking anything corrupt, missing pid, or whose process merely looks dead. So the command written to be the safe alternative to stop could itself deregister a live run: #344's orphan, reached through the safe door.

Fixed by splitting the parse from the policy, rather than adding a flag. New scan_pid_files() reads and classifies without touching the disk; read_pid_files() stays the maintenance path for stop. One parser, two policies — and read-only becomes a property of which function you call, not of a boolean someone must remember to pass. A prune=False default would have been one forgotten keyword away from this bug returning.

Worth noting a liveness probe saying "dead" is not proof — an atomic-write window, a PID namespace, a transient probe failure all land there — so a reader deleting on that evidence is unsafe regardless of how the probe is implemented.

The malformed-file crash

Also confirmed, and slightly worse than described: the payload indexes e["port"] directly while the reader only guarded pid, so an entry with a pid and no port raised KeyError — exit 1, empty stdout, --json included, hiding every healthy run. scan_pid_files now skips entries without an integer pid and port, and logs which file it skipped.

Listing is filename-sorted now too, since Path.glob order is filesystem-dependent and this output is user-facing.

Why the bug survived its own test suite

Taking your mutation point seriously: test_pid_files_are_left_in_place only covered a live process — which the pruning reader would have kept anyway. It passed while status was deleting things. The property was named correctly and tested at the one input that could not fail.

Five new tests cover the paths that actually prune, each verified against the unfixed code:

Test	Without fix
test_a_pid_file_is_not_deleted_when_the_process_looks_dead	❌ fails
test_an_unreadable_pid_file_is_not_deleted	❌ fails
test_one_malformed_file_does_not_hide_the_healthy_runs	❌ fails
test_json_still_emits_the_healthy_runs	❌ fails
test_malformed_files_are_still_on_disk_afterwards	❌ fails

Docs

All five gaps closed: docs/cli-reference.md (full section + ToC), AGENTS.md, CHANGELOG.md, the help-panel map in test_help_panels.py, and plugins/.../references/execution.md. That last one mattered most — it still told agents to use conductor stop to inspect background runs, which is the habit this command exists to break.

Coordination with #383

You called these "the same change from two directions", which is right. #383 now carries the root-cause half: atomic write_pid_file (temp + os.replace, so no reader can see a partial file) and a warning before any unlink. This PR carries the reader half. They are complementary and touch different functions, so whichever lands second is a small rebase.

Still open, deliberately

• run_id and log_file are always empty. Real, and I left it — the writer at bg_runner.py:394 never passes them, so fixing it is a change to the launch path rather than to status. Happy to do it here if you would rather not split it.
• Dashboard URL cropped at 80 columns. Reproduced. It is a _print_running_list rendering concern shared with stop, so I would rather fix it in one place than widen this PR.

Gates

519 passed in tests/test_cli. ruff check unchanged at 2 pre-existing findings; ty check src unchanged at 64; my files are ruff format and ty clean.

[Frank Li (franklixuefei)]

Correction on my previous comment: CI had not actually run, and that was my doing.

The push landed on the right branch — PR head 1007086 matched the fork branch and my local commit — but only license/cla reported. It was not an approval gate: GitHub had scheduled no run at all, and nothing was sitting in the action_required queue either.

The cause: this PR was mergeable: CONFLICTING / mergeStateStatus: DIRTY. pull_request workflows run against the merge ref (refs/pull/N/merge), and for a conflicting PR that ref cannot be produced, so no run is ever created. #383 was CLEAN at the same moment and ran normally from the same fork and account, which is what made the difference visible.

The conflict was mine. I added the CHANGELOG entry without merging main first, and main had moved two commits that touched the same ### Added block (#372's output-field constraints). Merged main in 4ccfbde and kept both entries — they are independent additions.

CI now runs and is green: 10/10, including Lint, Type Check, and Test on Python 3.12 and 3.13.

Worth flagging as a general trap rather than just my mistake: a conflicting PR shows a check list that is empty rather than red, so it reads as "nothing to do" instead of "nothing ran". Thanks for pushing on it — I would otherwise have reported this as green off a stale run.

[Jason Robert (jrob5756)]

Verified the fixes — the destructive-read work holds up. Reproduced each one: dead process and truncated file are both preserved now, and a malformed entry no longer takes down the listing. I also reverted scan_pid_files back to read_pid_files and confirmed your five new tests fail without the fix, so they are pinning real behaviour.

Splitting the parser from the policy was the better call. A prune=False default really would have been one forgotten keyword from a regression.

One thing did not land, so I pushed it rather than send you round again (5ce75a8).

The mutation finding was narrower than the pruning bug. test_single_run_is_listed_not_stopped patches _is_process_alive, which removes the only reachable signal, then asserts on _stop_process and app.os.kill — neither of which status calls. So both assertions still cannot fail, and the SIGTERM mutant passes all 13 tests on the current head. I re-ran it to be sure.

The new test asserts on the signal value instead, which is the one place the property can actually break:

with (
patch("conductor.cli.pid.sys.platform", "linux"),
patch("conductor.cli.pid.os.kill") askill,
):
result=runner.invoke(app, ["status"])
assertkill.call_args_list, "the liveness probe never ran, so nothing was asserted"assertall(call.args== (4242, 0) forcallinkill.call_args_list)

sys.platform is forced the way test_pid.py does it so the POSIX probe runs anywhere, and the non-empty guard stops it passing vacuously if the probe is never reached. Checked against three mutants — SIGTERM, SIGKILL, and a forced Windows dispatch — each fails now.

Also added status to the panel-mapping dict in test_help_panels.py. It made the presence tuple but not the mapping, and the mapping is the half that catches a miscategorised command. Verified by moving status to the Environment panel. And corrected the show_url docstring, which read "On by default" for a parameter defaulting to False.

540 passed in tests/test_cli, ruff and ty check src clean.

Agreed on both deferrals. run_id/log_file are a launch-path change and the URL cropping belongs in _print_running_list where stop shares it — neither belongs here. Worth filing so they do not get lost.

Approving once CI is green.

[Jason Robert (jrob5756)]

Filed the two deferrals so they do not get lost:

• PID files always record an empty run_id and log_file, so conductor status --json ships two permanently dead fields #404 — PID files always record an empty run_id/log_file (launch path, bg_runner.py:394). Flagged the log_file wrinkle there too: the parent cannot know the events-log path, so that field needs repurposing or renaming rather than just wiring up.
• Dashboard URL is cropped out of conductor status at default terminal width — the one field the command exists to surface #405 — Dashboard URL cropped at 80 columns (_print_running_list). Included the note that the test fixture hand-builds PID JSON with a 19-char timestamp where production writes 32, which is why the existing assertion passes.

Neither blocks this PR.

[Jason Robert (jrob5756)]

LGTM. Approved!