convoy: per-network ding-service selector (node st ding | rust ding) (#99)

Adds a `ding` field to <net>/convoy.toml letting a network choose its ding
sidecar: "node" (smalltalk's `st ding`, the default — unset → node, so every
existing user is unchanged) or "rust" (compoundingtech/ding — full st-ding
parity, ~0% CPU). Both take IDENTICAL args, so the selector swaps ONLY the
binary prefix; --identity/--root and the whole flag surface are untouched.

- network-config.ts: DingService type + `ding` field, read/write + validation.
- launch.ts: dingBin()/dingCommand(service) — writePtyToml reads the net's
  choice and bakes the right ding binary into each agent's pty.toml. The
  pre-#43 ding-heal path stays node-only (it only ever matches `st ding` tomls;
  a rust ding is new and already carries --root, so heal skips it).
- convoy init --ding node|rust records the choice (mirrors --megarepo), also
  surfaced in the command table (completions + flag allow-list).

Coordinated with ding-rust-claude: the rust `ding` is a confirmed drop-in
(same positional session-id, same --identity/--root, zero new required config).


Claude-Session: https://claude.ai/code/session_01MCzqQKSpPiNX2ketyubByS

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: myobie

src/cli.ts

@@ -137,7 +137,7 @@ function printHelp(): void {
       "SUBCOMMANDS:\n" +
       "  ls (default)   list the convoy's members [--tree = spawn-parentage tree + cross-machine liveness (synced status-mtime + host) --stale-after <ms> --live-only --json --network]\n" +
       "  doctor         setup-readiness suite: prove your setup can do real agent work [--quick = preflight only; --full = real CoS→sup→worker org proof (slower)]\n" +
-      "  init [name|dir] interactive, narrated: stand up a network (name → megarepo → CoS), NAME lives at <home>/<name> [--megarepo <path> --quiet --json --yes --no-channel]\n" +
+      "  init [name|dir] interactive, narrated: stand up a network (name → megarepo → CoS), NAME lives at <home>/<name> [--megarepo <path> --ding node|rust --quiet --json --yes --no-channel]\n" +
       "  add <role>     DECLARE an agent — write its agent file into the synced catalog; NO launch (convoy up runs it) [--identity --host --harness claude|codex --model <id> --transport ding|mcp --mcp --network --dir --persona --permanent --dry-run --force]\n" +
       "  render <id>    materialize an agent's worktree overlay from its catalog agent file — NO launch, NO bus (declarative: add=declare · render=materialize · up=reconcile) [--dir <workspace> --network --dry-run]\n" +
       "  cos --repo <d> bootstrap a Chief of Staff\n" +

src/command-table.ts

@@ -14,6 +14,7 @@
 
 import { HARNESSES, TRANSPORTS } from "./agent-spec.ts";
 import { ROLE_SPELLINGS } from "./role.ts";
+import { DING_SERVICES } from "./network-config.ts";
 
 /** A `--flag`. `kind` decides whether it consumes the next token — the same distinction `unknownFlag`
  *  makes. `values` is a closed set of completions for the argument; `takesPath` means the argument is a
@@ -93,6 +94,7 @@ export const COMMANDS: readonly CommandSpec[] = [
     flags: [
       { name: "name", desc: "Network name", kind: "value" },
       { name: "megarepo", desc: "Megarepo path agents cut worktrees off", kind: "value", takesPath: true },
+      { name: "ding", desc: "Ding sidecar service (node = st ding, rust = compoundingtech/ding)", kind: "value", values: DING_SERVICES },
       { name: "quiet", desc: "No prompts or narration", kind: "bool" },
       { name: "yes", desc: "Accept defaults non-interactively", kind: "bool" },
       { name: "no-channel", desc: "Skip creating the default channel", kind: "bool" },

src/commands.ts

@@ -10,7 +10,7 @@ import { fileURLToPath } from "node:url";
 import { run } from "./exec.ts";
 import { flagAllowList } from "./command-table.ts";
 import { CONVOY_DIR, DEFAULT_NETWORK_NAME, defaultConvoyNetwork, isNetworkName, networkDirForName, networkDirOfStRoot, networkLayout, stRootOf } from "./paths.ts";
-import { networkNameFromDir, readNetworkConfig, writeNetworkConfig } from "./network-config.ts";
+import { DING_SERVICES, isDingService, networkNameFromDir, readNetworkConfig, writeNetworkConfig, type DingService } from "./network-config.ts";
 import { defaultBinDir, installClis } from "./install-cli.ts";
 import { Bus, isLive, type Agent } from "./bus.ts";
 import { PtyHost, spawnFromPtyFile, workspaceOfPtyfile, type SupervisedSession } from "./host.ts";
@@ -533,7 +533,7 @@ async function askYesNo(question: string, def: boolean): Promise<boolean> {
   return a ? a.startsWith("y") : def;
 }
 
-/** `convoy init [name|dir] [--megarepo <path>] [--quiet|--json] [--yes] [--no-channel]` — stand up a
+/** `convoy init [name|dir] [--megarepo <path>] [--ding node|rust] [--quiet|--json] [--yes] [--no-channel]` — stand up a
  *  correctly-structured network. INTERACTIVE + NARRATED by default (Nathan): on a TTY it walks the user
  *  through network name → megarepo → CoS, and tells them what it's doing at each step. `--quiet`/`--json`
  *  (or a non-TTY, e.g. scripts/evals) skips prompts + narration; `--yes` accepts defaults non-interactively;
@@ -581,15 +581,28 @@ export async function cmdInit(args: string[]): Promise<number> {
     megarepo = abs;
   }
 
+  // 2b. Ding service — which ding sidecar this net runs: node `st ding` (default) or the rust `ding`.
+  //     --ding wins; else preserve a prior config. A machine-runtime choice, so it is NOT prompted for.
+  let ding: DingService | undefined = priorCfg?.ding;
+  const dingInput = optValue(args, "--ding");
+  if (dingInput) {
+    if (!isDingService(dingInput)) {
+      err(`invalid --ding "${dingInput}" (want: ${DING_SERVICES.join(" | ")})`);
+      return 1;
+    }
+    ding = dingInput;
+  }
+
   // 3. Create the structure + config, narrating each step.
   say("→ Creating the network structure (smalltalk/ = the bus · catalog/ = agent files (desired state) · pty/ = runtime · worktrees/ = workspaces)…");
   mkdirSync(layout.stRoot, { recursive: true });
   mkdirSync(catalogDir(dir), { recursive: true }); // the catalog — `convoy add` writes agent files here (desired state); convoy declares it to `fabric sync` (below) so it propagates cross-machine
   mkdirSync(layout.ptyRoot, { recursive: true });
   mkdirSync(layout.worktrees, { recursive: true });
   say("→ Recording the network config (convoy.toml)…");
-  writeNetworkConfig(dir, { name: networkNameFromDir(dir), ...(megarepo ? { megarepo } : {}) });
+  writeNetworkConfig(dir, { name: networkNameFromDir(dir), ...(megarepo ? { megarepo } : {}), ...(ding ? { ding } : {}) });
   if (megarepo) say(`   megarepo: ${megarepo}`);
+  if (ding) say(`   ding: ${ding}${ding === "rust" ? " (compoundingtech/ding — rust)" : " (smalltalk st ding — node)"}`);
   say("→ Initializing the smalltalk bus…");
   const stArgs = ["init", layout.stRoot];
   if (hasFlag(args, "--no-channel")) stArgs.push("--no-channel");

src/launch.test.ts

@@ -5,6 +5,8 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { bootPrompt, dingCommand, discoverSmalltalkDir, harnessCommand, regenerateDingRoot, writeAgentFiles, writeContextFiles, writePtyToml } from "./launch.ts";
 import type { AgentSpec } from "./agent-spec.ts";
+import { stRootOf } from "./paths.ts";
+import { writeNetworkConfig } from "./network-config.ts";
 
 describe("native launch command builders (cold-start boot-prompt)", () => {
   it("harnessCommand claude: exec claude with the mode + boot prompt, NO poker, NO --resume", () => {
@@ -59,6 +61,20 @@ describe("native launch command builders (cold-start boot-prompt)", () => {
     // no root → no flag (unchanged behavior; falls back to ST_ROOT env / install default)
     expect(dingCommand("convoy-claude", "silber.convoy", null)).toBe("st ding silber.convoy --identity convoy-claude");
   });
+
+  it("dingCommand: service='rust' swaps the binary to `ding` (identical args); 'node'/undefined → `st ding`", () => {
+    // rust ding = drop-in: same positional session-id, same --identity/--root — only the prefix changes.
+    expect(dingCommand("convoy-claude", "silber.convoy", "/net/smalltalk", "rust")).toBe(
+      "ding silber.convoy --identity convoy-claude --root /net/smalltalk",
+    );
+    // node + undefined both → `st ding` (the default; every existing user is unchanged).
+    expect(dingCommand("convoy-claude", "silber.convoy", "/net/smalltalk", "node")).toBe(
+      "st ding silber.convoy --identity convoy-claude --root /net/smalltalk",
+    );
+    expect(dingCommand("convoy-claude", "silber.convoy", "/net/smalltalk")).toBe(
+      "st ding silber.convoy --identity convoy-claude --root /net/smalltalk",
+    );
+  });
 });
 
 describe("writePtyToml (pinned hostname-prefixed ids, cold start)", () => {
@@ -112,6 +128,29 @@ describe("writePtyToml (pinned hostname-prefixed ids, cold start)", () => {
     }
   });
 
+  it("network convoy.toml ding='rust' bakes the rust `ding` binary into the sidecar; default → node `st ding`", () => {
+    const net = mkdtempSync(join(tmpdir(), "convoy-ding-net-"));
+    const dir = mkdtempSync(join(tmpdir(), "convoy-ptytoml-ding-"));
+    try {
+      // default (network has no `ding` recorded) → node st ding, unchanged.
+      writeNetworkConfig(net, { name: "ournet" });
+      writePtyToml(dir, spec({ networkRoot: net }));
+      expect(readFileSync(join(dir, ".convoy", "pty.toml"), "utf8")).toContain(
+        `st ding silber.convoy --identity silber.convoy-claude --root ${stRootOf(net)}`,
+      );
+
+      // network chooses rust → the sidecar swaps to `ding` (same args), fully — no `st ding` left.
+      writeNetworkConfig(net, { name: "ournet", ding: "rust" });
+      writePtyToml(dir, spec({ networkRoot: net }));
+      const toml = readFileSync(join(dir, ".convoy", "pty.toml"), "utf8");
+      expect(toml).toContain(`ding silber.convoy --identity silber.convoy-claude --root ${stRootOf(net)}`);
+      expect(toml).not.toContain("st ding");
+    } finally {
+      rmSync(net, { recursive: true, force: true });
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
   it("--config-dir sets CLAUDE_CONFIG_DIR on the HARNESS session env only, not the ding sidecar", () => {
     const dir = mkdtempSync(join(tmpdir(), "convoy-ptytoml-cfg-"));
     try {

src/launch.ts

@@ -15,6 +15,7 @@ import { harnessDescriptor, type Harness } from "./harness.ts";
 import type { PermissionMode, Role } from "./role.ts";
 import { pretrustDir, pretrustDirsCodex } from "./trust.ts";
 import { CONVOY_DIR, networkLayout, stRootOf } from "./paths.ts";
+import { readNetworkConfig, type DingService } from "./network-config.ts";
 import { counterContextRefusal } from "./identity.ts";
 
 /** A harness without MCP always runs the ding sidecar; one with MCP honors its declared transport. */
@@ -134,14 +135,22 @@ export function harnessCommand(
   return `exec ${cmd}${tail}`;
 }
 
+/** The ding-sidecar BINARY for a network's chosen ding service (see network-config.ts `DingService`):
+ *  smalltalk's node `st ding` (default, unset → this) or the rust `ding` (compoundingtech/ding — full
+ *  `st ding` parity, ~0% CPU). Both take IDENTICAL args, so the selector swaps only this prefix. */
+export function dingBin(service?: DingService): string {
+  return service === "rust" ? "ding" : "st ding";
+}
+
 /** The ding sidecar command — pokes the agent's claude session when its bus inbox gets mail. Points at
- *  the stable session id (`st ding <prefix.agentShort> --identity <bus-id>`). `st ding` stays a
- *  smalltalk runtime binary. When a network `root` is given we bake `--root <net>` (smalltalk #85) into
- *  the command line — NOT just the env — so a `pty restart` (which replays the stored command) can never
- *  drop it and silently fall back to st's install-default root (the fleet phantom-poke/non-delivery bug). */
-export function dingCommand(busId: string, claudeSessionId: string, root?: string | null): string {
+ *  the stable session id (`<ding-bin> <prefix.agentShort> --identity <bus-id>`). The ding binary is the
+ *  network's chosen ding service (`dingBin`); default node `st ding`. When a network `root` is given we
+ *  bake `--root <net>` (smalltalk #85) into the command line — NOT just the env — so a `pty restart`
+ *  (which replays the stored command) can never drop it and silently fall back to st's install-default
+ *  root (the fleet phantom-poke/non-delivery bug). The rust ding honors `--root` identically. */
+export function dingCommand(busId: string, claudeSessionId: string, root?: string | null, service?: DingService): string {
   const rootFlag = root ? ` --root ${root}` : "";
-  return `st ding ${claudeSessionId} --identity ${busId}${rootFlag}`;
+  return `${dingBin(service)} ${claudeSessionId} --identity ${busId}${rootFlag}`;
 }
 
 /** Provision the agent's DURABLE CONTEXT dir (`<member>/context/`) — unless the identity is a counter.
@@ -177,6 +186,9 @@ export function provisionContext(memberDir: string, identity: string): string |
 export function writePtyToml(dir: string, spec: AgentSpec, opts?: { spawner?: string | null }): void {
   const busId = busAgentId(spec); // the host-prefixed bus identity, e.g. silber.convoy-claude
   const root = spec.networkRoot; // the network DIR; ST_ROOT is <root>/smalltalk (the bus), PTY_ROOT is <root>/pty
+  // The ding SERVICE is a per-network choice, recorded in <net>/convoy.toml (unset → node `st ding`). Read
+  // it here so the sidecar command baked into the pty.toml is the network's chosen ding (node or rust).
+  const dingService = root ? readNetworkConfig(root)?.ding : undefined;
   const harnessId = sessionId(spec); // e.g. silber.convoy (agentShort strips the -claude/-codex suffix)
   const dingId = `${harnessId}.ding`; // e.g. silber.convoy.ding
   const permanent = specPermanent(spec);
@@ -216,7 +228,7 @@ export function writePtyToml(dir: string, spec: AgentSpec, opts?: { spawner?: st
         ? {
             ding: {
               id: dingId,
-              command: dingCommand(busId, harnessId, root ? stRootOf(root) : null),
+              command: dingCommand(busId, harnessId, root ? stRootOf(root) : null, dingService),
               tags: { role: "ding", ...(permanent ? { strategy: "permanent" } : {}), ...stTag },
               env,
             },

src/network-config.test.ts

@@ -1,5 +1,5 @@
 import { afterEach, describe, it, expect } from "vitest";
-import { existsSync, mkdirSync, mkdtempSync, rmSync } from "node:fs";
+import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { execFileSync } from "node:child_process";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
@@ -32,6 +32,23 @@ describe("network-config (<net>/convoy.toml)", () => {
     expect(readNetworkConfig(d)).toEqual({ name: "big", megarepo: "/repos/mono" });
   });
 
+  it("write + read round-trips the ding service; an invalid value is ignored (falls back to node default)", () => {
+    const d = tmp();
+    // unset → absent from the parsed config (callers treat undefined as node `st ding`).
+    writeNetworkConfig(d, { name: "default" });
+    expect(readNetworkConfig(d)).toEqual({ name: "default" });
+
+    // node + rust both round-trip.
+    writeNetworkConfig(d, { name: "default", ding: "node" });
+    expect(readNetworkConfig(d)).toEqual({ name: "default", ding: "node" });
+    writeNetworkConfig(d, { name: "ournet", ding: "rust" });
+    expect(readNetworkConfig(d)).toEqual({ name: "ournet", ding: "rust" });
+
+    // a hand-edited garbage value is dropped (not surfaced as a bogus DingService).
+    writeFileSync(networkConfigPath(d), 'name = "x"\nding = "banana"\n');
+    expect(readNetworkConfig(d)).toEqual({ name: "x" });
+  });
+
   it("read is null when the file is missing or nameless", () => {
     const d = tmp();
     expect(readNetworkConfig(d)).toBeNull(); // no file yet

src/network-config.ts

@@ -8,12 +8,28 @@ import { readFileSync, writeFileSync } from "node:fs";
 import { basename, join } from "node:path";
 import { parse as tomlParse, stringify as tomlStringify } from "smol-toml";
 
+/** Which ding sidecar a network runs — "node" (smalltalk's `st ding`, the default for everyone) or
+ *  "rust" (compoundingtech/ding: full `st ding` parity, ~0% CPU). Both take identical args, so the
+ *  choice swaps ONLY the binary. Unset → "node". */
+export type DingService = "node" | "rust";
+
+/** The two `DingService` spellings, for validation + completions (a runtime tuple, not just the type). */
+export const DING_SERVICES: readonly DingService[] = ["node", "rust"];
+
 export interface NetworkConfig {
   /** The network's name (defaults to the dir basename). */
   name: string;
   /** Absolute path to the megarepo agents cut worktrees off, if the network uses one (else workspaces
    *  are symlinked into worktrees/). Optional — added by the megarepo model. */
   megarepo?: string;
+  /** The ding sidecar this network runs (see `DingService`). A per-NETWORK choice, not per-agent: the
+   *  ding binary is a runtime dependency of the box hosting the net. Unset → "node" (`st ding`). */
+  ding?: DingService;
+}
+
+/** True iff `v` is a valid `DingService` spelling. */
+export function isDingService(v: unknown): v is DingService {
+  return v === "node" || v === "rust";
 }
 
 /** The config file location for a network dir: `<dir>/convoy.toml`. */
@@ -31,7 +47,11 @@ export function readNetworkConfig(dir: string): NetworkConfig | null {
   try {
     const doc = tomlParse(readFileSync(networkConfigPath(dir), "utf8")) as Partial<NetworkConfig>;
     if (typeof doc.name !== "string" || doc.name === "") return null;
-    return { name: doc.name, ...(typeof doc.megarepo === "string" && doc.megarepo ? { megarepo: doc.megarepo } : {}) };
+    return {
+      name: doc.name,
+      ...(typeof doc.megarepo === "string" && doc.megarepo ? { megarepo: doc.megarepo } : {}),
+      ...(isDingService(doc.ding) ? { ding: doc.ding } : {}),
+    };
   } catch {
     return null;
   }
@@ -41,5 +61,6 @@ export function readNetworkConfig(dir: string): NetworkConfig | null {
 export function writeNetworkConfig(dir: string, config: NetworkConfig): void {
   const doc: Record<string, unknown> = { name: config.name };
   if (config.megarepo) doc["megarepo"] = config.megarepo;
+  if (config.ding) doc["ding"] = config.ding;
   writeFileSync(networkConfigPath(dir), tomlStringify(doc));
 }