fix(cli): stop killing the background listen child with --pid-file

[AgentRelayBot]

What

relayfile listen --background has never worked. It reports success and starts nothing.

$ relayfile listen --background
Listen started in background. Logs: ~/.relayfile/listen.log

$ cat ~/.relayfile/listen.log
error: flag provided but not defined: -pid-file

Why

spawnBackgroundListenProcess appended --daemonized --pid-file <path> to the child argv, but runListen's flagset registers only server, token, provider, path, event, run, format, background, daemonized. No pid-file.

It parses with flag.ContinueOnError and fs.SetOutput(io.Discard), so the unknown flag produced no diagnostic anywhere a user looks — and the parent had already printed "Listen started in background" and called Process.Release().

--pid-file was also pointless: nothing reads the listen pid file. There is no listen stop or listen status, and listenPIDFile() had exactly one caller — the spawn site that passed it to the child. So the fix drops the flag rather than registering it, and removes the dead helper.

(mount --background is unaffected: its flagset does register --pid-file, and waitForBackgroundMountRegistration genuinely reads that file.)

Change

• Don't send --pid-file to the listen child; delete listenPIDFile.
• Extract backgroundListenChildArgs so the child argv is testable in isolation.

Verification

Built and ran against a scratch HOME:

• before — listen --daemonized --pid-file /tmp/x → error: flag provided but not defined: -pid-file; listen --background printed success and wrote that error to the log
• after — the child parses and reaches real work, failing only on absent credentials in a bare HOME, which is correct

New test TestBackgroundListenChildArgsOnlyUseRegisteredFlags runs the produced argv through the real runListen flagset rather than pinning a literal argv, so a future flag added to the child is checked too. Mutation-tested — reintroducing --pid-file fails it:

child argv [--provider linear --daemonized --pid-file /tmp/x.pid] carries a flag
runListen does not register: flag provided but not defined: -pid-file

go vet clean, gofmt clean, and the Background|Listen|Stop suites pass.

🤖 Generated with Claude Code

---

Note

Low Risk
Narrow CLI spawn/argv change for listen background mode; mount background PID handling is unchanged.

Overview
Fixes relayfile listen --background, which previously printed success while the child exited immediately on an unregistered --pid-file flag (with no user-visible error because runListen discards flag parse output).

The spawn path no longer passes --pid-file or uses listenPIDFile() (nothing consumed that file). Child argv is built via backgroundListenChildArgs: strip --background, append --daemonized only.

Adds TestBackgroundListenChildArgsOnlyUseRegisteredFlags, which runs the produced args through real runListen flag parsing so future unknown flags regress visibly.

^{Reviewed by Cursor Bugbot for commit 6f09fc9. Bugbot is set up for automated code reviews on this repo. Configure here.}

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: 00d2cb69-b2b6-4cee-9867-3229a4e660ee

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no bugs or issues to report.

[github-actions]

Relayfile Eval Review

Run: .relayfile/evals/runs/2026-09-18T15-26-58-302Z-HEAD-provider
Mode: provider
Git SHA: 7710eb6

Passed: 4 | Needs human: 0 | Reviewable: 0 | Missing output: 0 | Failed: 0 | Skipped: 0

Human Review Cases

No reviewable human-review cases captured Relayfile output.