feat(cli): retire serve — unify on run, lifespan is the only knob (#44)

Per the Phase-1 spec ("serve/live retired — it's all the agent running;
lifespan is the only distinction") + Nathan: the persistent entrypoint was
still a separate `bob serve` command. Fold it into `run`:

- `bob run <name>`            → PERSISTENT/on-duty (what `serve` did): one warm
                                 session, loads capabilities (discord gateway,
                                 cron), blocks until SIGTERM. The service unit
                                 runs this.
- `bob run <name> "<task>"`   → MINIMAL one-shot (claude -p style): ephemeral,
                                 no gateway (BOB_PERSISTENT unset, #43), prints
                                 the response, exits.
- `bob serve` deleted; service.ts ExecStart is now `bob run <name>`.

So "run minimal by default" (a task prompt is the minimal path) and the spec's
"persistent default" (no prompt = on-duty) both hold — prompt-presence is the
lifespan knob. Help + tests updated.

NOTE: Pulse's hand-rolled systemd unit still has `ExecStart=… bob serve pulse`
— I update it to `bob run pulse` in the same deploy so she doesn't break.

Co-authored-by: Flint <263629284+tps-flint@users.noreply.github.com>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: tps-flint

packages/cli/src/cli.ts

@@ -62,12 +62,12 @@ Commands:
                              --dry-run --force --no-interactive
   align <name>        Recurring check-in to refine an existing agent
                       Flags: --provider <p> --model <m> --agent-dir <dir>
-  run <name> <prompt> Run one short-lived task for the named agent (embeds pi
-                      via its SDK — fresh session, one prompt, exit)
+  run <name>          Run the agent PERSISTENTLY (on-duty) — one warm pi session
+                      that stays up, loading bob.yaml capabilities (discord
+                      gateway, cron). This is what the service unit runs.
+  run <name> <prompt> Run ONE short-lived task (claude -p style) — minimal +
+                      ephemeral, no gateway. Prints the response, exits.
                       Flags: --model <m>  (--interactive: coming in a later PR)
-  serve <name>        Run the agent PERSISTENTLY — one warm pi session that stays
-                      up, loading the agent's bob.yaml capabilities (incl. discord).
-                      This is what the service unit runs. Flags: --model <m>
   install-service <n> Write the agent's service unit (launchd on macOS / systemd
                       user unit on Linux) so it self-runs. Flags: --bob-bin <abs path> --model <m>
   up <name>           Load + start the agent's service unit
@@ -167,44 +167,37 @@ async function run(
   flags: Record<string, string | boolean>,
 ): Promise<number> {
   const model = flags.model !== undefined && flags.model !== true ? String(flags.model) : undefined;
-  // PR1 migrated `bob run` to pi's embedded SDK for the non-interactive prompt
-  // path only. The interactive REPL on the SDK lands in a later phase-1 PR.
+  // The interactive REPL on the SDK lands in a later phase-1 PR.
   if (flags.interactive === true) {
     console.error(
-      "bob run: --interactive is not yet supported on the embedded-SDK path (use a prompt for now)",
+      "bob run: --interactive is not yet supported on the embedded-SDK path (give a task prompt for now)",
     );
     return 2;
   }
+  // Lifespan is the only knob (`serve` is retired): a task prompt = a MINIMAL
+  // one-shot; NO prompt = the agent runs PERSISTENTLY (on-duty).
   if (prompt === undefined) {
-    console.error('bob run: a prompt is required, e.g. `bob run <name> "summarize my inbox"`');
-    return 2;
+    // PERSISTENT: one warm pi session that stays up, loading the agent's
+    // bob.yaml capabilities (discord's inbound gateway, cron, …) and posting
+    // back via them. This is what the service unit invokes. Blocks until
+    // SIGTERM/SIGINT — runPersistent disposes the session gracefully (await
+    // in-flight turn → dispose → exit 0); KeepAlive/Restart relaunches it.
+    await runPersistent({ name, model });
+    return 0;
   }
-  // captureStdout collects the assistant's final text into result.stdout.
-  // runAgent itself is silent (it accumulates deltas, never writes to console),
-  // so without this `bob run` printed nothing — print the response here.
+  // ONE-SHOT TASK (claude -p style) — minimal + ephemeral (no gateway; see
+  // BOB_PERSISTENT in run.ts). captureStdout collects the assistant's final
+  // text (runAgent is otherwise silent), so we print the response.
   const result = await runAgent({ name, prompt, model, captureStdout: true });
   if (result.stdout && result.stdout.trim().length > 0) {
     console.log(result.stdout);
   }
   return result.exitCode;
 }
 
-// `bob serve <name>` — run the agent PERSISTENTLY. ONE warm pi AgentSession that
-// stays up, loading the agent's bob.yaml `capabilities:` (incl. discord, whose
-// gateway listener feeds inbound messages via pi.sendUserMessage and routes
-// replies back to the originating channel). This is the entrypoint the launchd
-// unit runs. Discord is no longer a CLI flag — it's a declared capability.
-//
-// Blocks until SIGTERM/SIGINT, which runPersistent handles gracefully (await
-// in-flight turn → session.dispose() → exit 0). KeepAlive relaunches it.
-async function serve(name: string, flags: Record<string, string | boolean>): Promise<void> {
-  const model = flags.model !== undefined && flags.model !== true ? String(flags.model) : undefined;
-  await runPersistent({ name, model });
-}
-
 // `bob install-service <name>` — write the agent's launchd plist so it self-runs
 // (KeepAlive + RunAtLoad). Does NOT start it — that's `bob up`. The plist runs
-// `bob serve <name>`; it embeds NO secrets (the discord token is read from the
+// `bob run <name>`; it embeds NO secrets (the discord token is read from the
 // file path in bob.yaml at runtime).
 async function installServiceCmd(
   name: string,
@@ -219,7 +212,7 @@ async function installServiceCmd(
   const model = flags.model !== undefined && flags.model !== true ? String(flags.model) : undefined;
   const { path: written } = await installService({ name, bobBin, model });
   console.log(`[bob install-service] wrote ${written}`);
-  console.log(`  runs:    ${bobBin} serve ${name}`);
+  console.log(`  runs:    ${bobBin} run ${name}`);
   console.log(`  next:    bob up ${name}   (load + start)`);
   if (bobBin === "bob") {
     console.error(
@@ -294,13 +287,6 @@ async function main(): Promise<number> {
         const prompt = args.positional.slice(1).join(" ") || undefined;
         return await run(args.positional[0], prompt, args.flags);
       }
-      case "serve":
-        if (!args.positional[0]) {
-          console.error("bob serve: missing <name>");
-          return 2;
-        }
-        await serve(args.positional[0], args.flags);
-        return 0;
       case "install-service":
         if (!args.positional[0]) {
           console.error("bob install-service: missing <name>");

packages/cli/test/cli.test.ts

@@ -55,16 +55,17 @@ describe("bob CLI", () => {
 
   it("help advertises persistent run + lifecycle commands", () => {
     const out = execSync(`node ${CLI} help`, { encoding: "utf8" });
-    expect(out).toContain("serve <name>");
-    expect(out).toContain("PERSISTENTLY");
+    expect(out).toContain("run <name>");
+    expect(out).toContain("PERSISTENTLY"); // run-with-no-prompt = persistent on-duty
+    expect(out).not.toContain("serve <name>"); // serve is retired
     expect(out).toContain("install-service");
     expect(out).toContain("up <name>");
     expect(out).toContain("down <name>");
     expect(out).toContain("restart <name>");
   });
 
   it("lifecycle commands require a <name>", () => {
-    for (const cmd of ["up", "down", "restart", "install-service", "serve"]) {
+    for (const cmd of ["up", "down", "restart", "install-service"]) {
       try {
         execSync(`node ${CLI} ${cmd} 2>&1`, { encoding: "utf8" });
         throw new Error(`expected non-zero exit for bare '${cmd}'`);

packages/shell/src/service.ts

@@ -1,7 +1,7 @@
 // Service install + lifecycle (`bob install-service` / `up` / `down` / `restart`).
 //
 // The agent owns its runtime (spec §3): each agent runs as its OWN OS service
-// unit hosting the persistent process (`bob serve <agent>` → runPersistent). Bob
+// unit hosting the persistent process (`bob run <agent>` → runPersistent). Bob
 // installs the unit; Bob does NOT babysit the process — the init system restarts
 // it on crash (launchd KeepAlive / systemd Restart=always) and starts it on
 // login/boot.
@@ -55,7 +55,7 @@ export interface RenderServiceOptions {
   // Absolute path to the `bob` binary the unit runs. Both init systems use a
   // minimal PATH, so this MUST be absolute (the caller resolves it). Required.
   bobBin: string;
-  // Optional model override passed through to `bob serve` (→ runPersistent).
+  // Optional model override passed through to `bob run` (→ runPersistent).
   model?: string;
   // The agent's home dir for log paths + WorkingDirectory. Defaults to ~. The
   // agent's working dir is <home>/agents/<name>/work.
@@ -84,15 +84,15 @@ export function plistPath(name: string, home: string = homedir()): string {
 }
 
 // Render the per-agent launchd plist. KeepAlive (restart on crash) + RunAtLoad
-// (start on login). ProgramArguments run `bob serve <name>`. NO secret.
+// (start on login). ProgramArguments run `bob run <name>`. NO secret.
 export function renderPlist(opts: RenderServiceOptions): string {
   assertName(opts.name);
   const home = opts.home ?? homedir();
   const label = serviceLabel(opts.name);
   const workDir = join(home, "agents", opts.name, "work");
   const logDir = join(home, "agents", opts.name);
 
-  const args = [opts.bobBin, "serve", opts.name];
+  const args = [opts.bobBin, "run", opts.name];
   if (opts.model) args.push("--model", opts.model);
   const programArgs = args.map((a) => `    <string>${xmlEscape(a)}</string>`).join("\n");
 
@@ -153,7 +153,7 @@ export function systemdUnitPath(name: string, home: string = homedir()): string
 
 // Render the per-agent systemd USER unit. Restart=always (restart on crash);
 // WantedBy=default.target (start on login/boot when enabled). ExecStart runs
-// `bob serve <name>`. NO secret env, NO inline token — see the security note.
+// `bob run <name>`. NO secret env, NO inline token — see the security note.
 // `name` already passed the strict regex, so ExecStart has no whitespace/newline
 // injection surface; bobBin/model are trusted (resolved binary path + a flag).
 export function renderSystemdUnit(opts: RenderServiceOptions): string {
@@ -162,7 +162,7 @@ export function renderSystemdUnit(opts: RenderServiceOptions): string {
   const workDir = join(home, "agents", opts.name, "work");
   const logDir = join(home, "agents", opts.name);
 
-  const exec = [opts.bobBin, "serve", opts.name];
+  const exec = [opts.bobBin, "run", opts.name];
   if (opts.model) exec.push("--model", opts.model);
 
   return `# Generated by 'bob install-service ${opts.name}'. Don't edit — re-run to update.

packages/shell/test/service.test.ts

@@ -28,10 +28,10 @@ function captureRunner(): { runner: LaunchctlRunner; calls: string[][] } {
 }
 
 describe("renderPlist", () => {
-  it("references the PERSISTENT entrypoint (bob serve <name>)", () => {
+  it("references the PERSISTENT entrypoint (bob run <name>)", () => {
     const xml = renderPlist({ name: "pulse", bobBin: "/usr/local/bin/bob", home: HOME });
     expect(xml).toContain("<string>/usr/local/bin/bob</string>");
-    expect(xml).toContain("<string>serve</string>");
+    expect(xml).toContain("<string>run</string>");
     expect(xml).toContain("<string>pulse</string>");
   });
 
@@ -159,7 +159,7 @@ describe("lifecycle (launchd) — up / down / restart invoke the right launchctl
 describe("systemd backend", () => {
   it("renderSystemdUnit runs the persistent entrypoint + Restart=always, no secret", () => {
     const unit = renderSystemdUnit({ name: "pulse", bobBin: "/usr/local/bin/bob", home: HOME });
-    expect(unit).toContain("ExecStart=/usr/local/bin/bob serve pulse");
+    expect(unit).toContain("ExecStart=/usr/local/bin/bob run pulse");
     expect(unit).toContain("Restart=always");
     expect(unit).toContain("WantedBy=default.target");
     expect(unit).toContain(`WorkingDirectory=${HOME}/agents/pulse/work`);
@@ -175,7 +175,7 @@ describe("systemd backend", () => {
       model: "claude-fast",
       home: HOME,
     });
-    expect(unit).toContain("ExecStart=/usr/local/bin/bob serve pulse --model claude-fast");
+    expect(unit).toContain("ExecStart=/usr/local/bin/bob run pulse --model claude-fast");
     expect(() => renderSystemdUnit({ name: "../evil", bobBin: "/bin/bob" })).toThrow(
       /invalid agent name/,
     );
@@ -202,7 +202,7 @@ describe("systemd backend", () => {
     });
     expect(res.path).toBe(`${HOME}/.config/systemd/user/bob-pulse.service`);
     expect(written[0].path).toBe(res.path);
-    expect(written[0].contents).toContain("ExecStart=/usr/local/bin/bob serve pulse");
+    expect(written[0].contents).toContain("ExecStart=/usr/local/bin/bob run pulse");
     expect(calls).toEqual([["--user", "daemon-reload"]]);
   });