fleet/fleetd
3
0
Fork 0
Code Issues 73 Pull Requests Actions Packages Projects Releases 1 Wiki Activity

CB-622: rename the MCP tool namespace bridge_* -> fleet_*, with one dual-name release #126

New Issue
Closed
opened 2026-08-22 21:34:29 +02:00 by ltms · 1 comment
ltms commented 2026-08-22 21:34:29 +02:00
Owner
Copy Link
Copy Source

Part of CB-621 (#125). Do this first, before the repo moves. It is least disruptive while the repo is still at its old path.

Why

The product is now called fleet. Tools called bridge_* would make the code and the docs disagree permanently.

The surface, measured

Eleven registered tool names, taken from mcp/ as the source of truth:

bridge_ack  bridge_ask  bridge_list  bridge_poll  bridge_profiles  bridge_reply
bridge_send  bridge_spawn  bridge_status  bridge_stop  bridge_whoami

Occurrences of bridge_* by file type, excluding the wiki/ submodule:

type count
.md 541
.java 260
.py 35
.yaml 13
.sh 2

Three more surfaces the tool names do not cover:

  1. The mount name bridged in .mcp.json, opencode.json, plugin/.mcp.json, plugin/skills/setup/SKILL.md, .claude/settings.local.json, .claude/skills/port-to-opencode/SKILL.md.
  2. The fallback ladder mcp__bridge__* in CLAUDE.md:29 and CLAUDE.md:274. This one decides how a member works out its own role, so getting it wrong makes a member act as the wrong role.
  3. REPLY_CHARTER in HerdrPeerLauncher.java:119-127, which names bridge_reply three times. This is the one rule that reaches a member with no repo checkout.

Env markers to decide on as well: BRIDGED_API_TOKEN, BRIDGED_MCP_URL, BRIDGED_MEMBER, BRIDGED_WORKER_TOKEN.

Scope

Ship one release that answers BOTH names. A member spawned during the migration must not break. Register each tool twice, with the bridge_* name marked deprecated in its description. Log a WARN, once per name per process, when an old name is called. Drop the old names at 3.0.

Order inside this ticket:

  1. Register both names; fleet_* is the documented one.
  2. Update REPLY_CHARTER to say fleet_reply. Members launched by the new daemon get the new word.
  3. Update the mcp__bridge__* fallback ladder to accept either prefix, because a member may be launched by an old or a new daemon during the change.
  4. Update .java, then .py, then .yaml/.sh, then .md.
  5. Update the portable CLAUDE.md block, and re-run the byte-identical check against the wiki template. That check is in CLAUDE.md under "The prompt is part of the product".
  6. Rename the mount from bridged to fleetd in the plugin and the skills. Leave the operator's local .mcp.json alone: it is flagged --skip-worktree and is not ours to rewrite.

Acceptance criteria

  • A live fleet_whoami call returns primary from this session.
  • A live bridge_whoami call still works and logs exactly one deprecation WARN.
  • A member spawned by the new daemon ends its turn with fleet_reply and the lead receives it.
  • A member spawned with the OLD charter still delivers its reply. This is the migration case; test it, do not assume it.
  • mvn clean install green.
  • The CLAUDE.md-vs-wiki byte-identical check prints in sync: True.

The trap this ticket must avoid

Every test here will assert on strings this codebase builds. That proves nothing about what the MCP client and the Claude Code binary actually accept - the exact mistake that made CB-618 ship green with 874 tests and break every role spawn. Run one real spawn and one real tool call before calling this done.

Part of CB-621 (#125). **Do this first, before the repo moves.** It is least disruptive while the repo is still at its old path. ## Why The product is now called fleet. Tools called `bridge_*` would make the code and the docs disagree permanently. ## The surface, measured Eleven registered tool names, taken from `mcp/` as the source of truth: ``` bridge_ack bridge_ask bridge_list bridge_poll bridge_profiles bridge_reply bridge_send bridge_spawn bridge_status bridge_stop bridge_whoami ``` Occurrences of `bridge_*` by file type, excluding the `wiki/` submodule: | type | count | |---|---| | `.md` | 541 | | `.java` | 260 | | `.py` | 35 | | `.yaml` | 13 | | `.sh` | 2 | Three more surfaces the tool names do not cover: 1. **The mount name `bridged`** in `.mcp.json`, `opencode.json`, `plugin/.mcp.json`, `plugin/skills/setup/SKILL.md`, `.claude/settings.local.json`, `.claude/skills/port-to-opencode/SKILL.md`. 2. **The fallback ladder `mcp__bridge__*`** in `CLAUDE.md:29` and `CLAUDE.md:274`. This one decides how a member works out its own role, so getting it wrong makes a member act as the wrong role. 3. **`REPLY_CHARTER`** in `HerdrPeerLauncher.java:119-127`, which names `bridge_reply` three times. This is the one rule that reaches a member with no repo checkout. Env markers to decide on as well: `BRIDGED_API_TOKEN`, `BRIDGED_MCP_URL`, `BRIDGED_MEMBER`, `BRIDGED_WORKER_TOKEN`. ## Scope **Ship one release that answers BOTH names.** A member spawned during the migration must not break. Register each tool twice, with the `bridge_*` name marked deprecated in its description. Log a WARN, once per name per process, when an old name is called. Drop the old names at 3.0. Order inside this ticket: 1. Register both names; `fleet_*` is the documented one. 2. Update `REPLY_CHARTER` to say `fleet_reply`. Members launched by the new daemon get the new word. 3. Update the `mcp__bridge__*` fallback ladder to accept **either** prefix, because a member may be launched by an old or a new daemon during the change. 4. Update `.java`, then `.py`, then `.yaml`/`.sh`, then `.md`. 5. Update the portable `CLAUDE.md` block, and re-run the byte-identical check against the wiki template. That check is in `CLAUDE.md` under "The prompt is part of the product". 6. Rename the mount from `bridged` to `fleetd` in the plugin and the skills. Leave the operator's local `.mcp.json` alone: it is flagged `--skip-worktree` and is not ours to rewrite. ## Acceptance criteria - A live `fleet_whoami` call returns `primary` from this session. - A live `bridge_whoami` call still works and logs exactly one deprecation WARN. - A member spawned by the new daemon ends its turn with `fleet_reply` and the lead receives it. - **A member spawned with the OLD charter still delivers its reply.** This is the migration case; test it, do not assume it. - `mvn clean install` green. - The `CLAUDE.md`-vs-wiki byte-identical check prints `in sync: True`. ## The trap this ticket must avoid Every test here will assert on strings this codebase builds. That proves nothing about what the MCP client and the Claude Code binary actually accept - the exact mistake that made CB-618 ship green with 874 tests and break every role spawn. **Run one real spawn and one real tool call before calling this done.**
ltms added this to the 2.0 — one operation centre, many hosts milestone 2026-08-22 21:34:29 +02:00
ltms commented 2026-08-31 09:00:08 +02:00
Author
Owner
Copy Link
Copy Source

Done, and the dual-name window has already closed. Closing.

Checked against main at 4ac688b:

$ grep -rn "bridge_" fleetd/src/main/java --include='*.java' | wc -l
0

The fleet_* namespace is the only one in the code — the bridge_* aliases were added and then dropped, so the one-release dual-name plan in this ticket ran to completion. The 11 tools are registered as fleet_* in FleetMcp, and PeerLauncher.MCP_MOUNT_NAME is "fleet".

Confirmed live, not just in source: fleet_whoami and fleet_list both answer on the running daemon (pid 85305, jar 59f0d10a8fff) after today's redeploy.

The remaining bridged strings in the tree are unrelated to the tool namespace — they are the bridged.yaml config fallback, the BRIDGED_MEMBER marker and the .bridged-worktrees directory. All three are deliberate; they are tracked on #145, where I have posted the exact list.

Done, and the dual-name window has already closed. Closing. Checked against `main` at `4ac688b`: ``` $ grep -rn "bridge_" fleetd/src/main/java --include='*.java' | wc -l 0 ``` The `fleet_*` namespace is the only one in the code — the `bridge_*` aliases were added and then dropped, so the one-release dual-name plan in this ticket ran to completion. The 11 tools are registered as `fleet_*` in `FleetMcp`, and `PeerLauncher.MCP_MOUNT_NAME` is `"fleet"`. Confirmed live, not just in source: `fleet_whoami` and `fleet_list` both answer on the running daemon (pid 85305, jar `59f0d10a8fff`) after today's redeploy. The remaining `bridged` strings in the tree are unrelated to the tool namespace — they are the `bridged.yaml` config fallback, the `BRIDGED_MEMBER` marker and the `.bridged-worktrees` directory. All three are deliberate; they are tracked on #145, where I have posted the exact list.
ltms closed this issue 2026-08-31 09:00:14 +02:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
blocked
Cannot start until something else lands. The body says what.
 needs-live-proof
Merged and green, but never shown working on the running daemon. Not the same as done.
 ready-to-delegate
Scope, files and acceptance criteria are written. A worker can be briefed from the body alone.
 silent-default
A feature that compiles, passes tests, and ships turned off. Nine recurrences and counting.
No Label
Milestone
No items
No Milestone 2.0 — one operation centre, many hosts
Projects
Clear projects
No project
Assignees
Clear assignees
agent kevin ltms
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: fleet/fleetd#126
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?