Skip to content

fleet: serve <role> --help (and the queue-broker/secrets-broker argv0 aliases) starts the daemon instead of printing help #5488

Closed

Description

@dezren39

fleet: serve <role> --help (and queue-broker --help / secrets-broker --help) starts the daemon instead of printing help

Evidence (verified this run, laptop primary @ eb3e71c)

pkgs/fleet/crates/fleet/src/main.rs, run_domain: the domain-help shortcut only inspects args.first():

if matches!(args.first().map(|s| s.as_str()), Some("--help") | Some("-h") | Some("help")) {
    print_domain_help(surface, d);
    return EXIT_OK;
}

For the serve domain the first argument is the role, so a help flag in position 2 is never seen. The call falls through to the broker entry points — fleet_queue::queue_broker::run() and fleet_queue::secrets_broker::run() (pkgs/fleet/crates/fleet-queue/src/queue_broker.rs:589, secrets_broker.rs:170) — which take no arguments at all and ignore argv entirely, proceeding to bind and serve.

The argv0 aliases hit the same path: main() prepends the implied arg (queue-broker → serve queue-broker), so queue-broker --help becomes args ["queue-broker", "--help"] and also starts the daemon.

Behavioral probe (real fleet binary built on the laptop, fake HOME with probe token files, QUEUE_BROKER_BIND=127.0.0.1:0, 3s timeout):

$ fleet serve queue-broker --help
queue-broker: listening on 127.0.0.1:0        # stderr; killed by timeout, exit 124
$ queue-broker --help                          # argv0 symlink
queue-broker: listening on 127.0.0.1:0        # stderr; killed by timeout, exit 124
$ fleet serve --help                           # control
fleet serve — Run a fleet daemon role …        # domain help, exit 0

Why it matters

--help is the safe, reflexive first command for any operator or agent meeting a new daemon binary. Here it silently performs the most consequential action the binary has — binding a port and serving the repo-queue / secrets brokers with whatever token files the host carries — instead of printing help. The §3 dispatch contract in the same file says domain help is "always available, even where the domain itself is not"; the role-shaped invocation defeats that contract. It is also an operational footgun for the fleet's own automation, which routinely probes <tool> --help to learn a surface.

Acceptance criteria

  • fleet serve queue-broker --help, fleet serve secrets-broker --help (and -h / help in the same position) print the serve domain help and exit 0, without binding anything.
  • The argv0 forms queue-broker --help and secrets-broker --help behave the same.
  • fleet serve <role> with no help flag still starts the role exactly as today; fleet serve --help and all other domains' help behavior are unchanged.
  • A test pins the help-after-role routing (e.g. at the dispatch level) so the implied-arg alias route cannot regress it.

Activity

  1. added
    kind/bugSomething isn't working (prefixed form of the classic bug label)
    task/small-fixQueue packet kind: bounded fix with reproduction and targeted tests
    source/creatorFiled by the new-issue-creator job
    priority/normalOrdinary priority (the default)
    work/self-assignedAn agent grabbed this item directly, outside the queue
    on Nov 4, 2026
  2. developing-today commented on Nov 4, 2026

    @developing-today
    Contributor
  3. added
    app/fleetpkgs/fleet multicall binary + platform crates
    on Nov 4, 2026
  4. dezren39 commented on Nov 4, 2026

    @dezren39
    MemberAuthor

    agent: new-issue-creator-code-a
    state: filed
    issue: #5488

    Found via: filed this run — code read of run_domain in pkgs/fleet/crates/fleet/src/main.rs (help shortcut inspects only args.first(); serve's first arg is the role) plus a behavioral probe of the real binary on the laptop: fleet serve queue-broker --help and argv0 queue-broker --help both logged "listening on 127.0.0.1:0" and had to be timeout-killed (exit 124), while the control fleet serve --help printed help with exit 0. Both broker entry points (queue_broker::run, secrets_broker::run) take no arguments, so the flag is silently ignored.

    Disposition: guarded self-solve this run (small, clearly scoped, low-risk): teach the serve-domain dispatch to honor a help flag in the role+1 position, covering both the direct and argv0-alias routes, with a pinning test.

  5. dezren39 commented on Nov 4, 2026

    @dezren39
    MemberAuthor

    agent: new-issue-creator-code-a
    state: done
    issue: #5488

    Solved this run via PR #5492, squash-merged at 31a00fb.

    • run_domain now routes through wants_domain_help(domain, args): help flag in position 0 for all domains (unchanged), plus position 1 for serve, covering fleet serve <role> --help and the argv0 aliases (queue-broker --help) whose implied arg lands in the same shape.
    • New unit tests pin both shapes; full pkgs/fleet suite green on the laptop.
    • Behavioral re-probe of the fixed binary: all three help forms print the serve domain help; bare fleet serve queue-broker still binds and serves.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    app/fleetpkgs/fleet multicall binary + platform crateskind/bugSomething isn't working (prefixed form of the classic bug label)priority/normalOrdinary priority (the default)source/creatorFiled by the new-issue-creator jobstatus:donetask/small-fixQueue packet kind: bounded fix with reproduction and targeted tests

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions