feat(cli): background server for codework tui

`codework tui` now finds or starts a background server and attaches the
Rust TUI to it:

- Discovery reads <home>/service.json and trusts it only when the
  endpoint answers `server.info` with the registered pid. A server from
  another CLI version is replaced. Otherwise a detached
  `codework serve --service` is started, logging to
  <home>/log/server.log, and startup fails fast with the reason from
  that log.
- Concurrent starts converge on one server: the loser adopts the
  winner, and a contender that is not adopted is stopped with the
  caller's scope.
- A registered server rewrites a missing service.json and shuts down
  when another server takes it over, so no server runs undiscoverable.
- While the TUI runs, the CLI restarts a server that dies on the same
  port so the TUI's reconnect lands.
- The TUI is spawned through Effect's ChildProcessSpawner in the CLI's
  scope, so SIGINT/SIGTERM to `codework tui` now stop the UI instead of
  orphaning it.

Adds `codework service start|restart|status|stop`, moves the RPC route
to /rpc/v1, and shows the cause of a failed `serve` (e.g. EADDRINUSE)
instead of a bare tag. The TUI launcher package now only resolves the
binary, Unix only.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: sanchitrk

packages/codework/README.md

@@ -49,7 +49,7 @@ codework run --sandbox-driver daytona --sandbox-provider-id <remote-id> "Continu
 
 #### Flags:
 
-- `--server <url>` — Connect to a running RPC server, e.g. `ws://127.0.0.1:7433/rpc`.
+- `--server <url>` — Connect to a running RPC server, e.g. `ws://127.0.0.1:7433/rpc/v1`.
 - `-s, --session <id>` — Continue an existing session.
 - `-C, --cwd <path>` — Working directory for a new session.
 - `--sandbox-driver <driver>` — Sandbox driver (`local`, `daytona`, `vercel`, `memory`, `sqldb`). Default: `local`.
@@ -69,9 +69,9 @@ Start a persistent server that owns sessions and sandboxes:
 
 ```bash
 codework serve --host 127.0.0.1 --port 7433
-codework run --server ws://127.0.0.1:7433/rpc "Inspect the failing tests"
-codework run --server ws://127.0.0.1:7433/rpc --session <id> "Now fix them"
-codework run --server ws://127.0.0.1:7433/rpc --sandbox-id <sandbox-id> "Start another session in this sandbox"
+codework run --server ws://127.0.0.1:7433/rpc/v1 "Inspect the failing tests"
+codework run --server ws://127.0.0.1:7433/rpc/v1 --session <id> "Now fix them"
+codework run --server ws://127.0.0.1:7433/rpc/v1 --sandbox-id <sandbox-id> "Start another session in this sandbox"
 ```
 
 The default address is `127.0.0.1:7433`; `--port 0` picks an available port and prints the actual URL. Set `--home`, `--database`, and `--user-config-dir` on the server. Model credentials, plugins, and working directories are resolved by the server. A remote run does not boot a local harness.
@@ -105,7 +105,7 @@ codework auth refresh --openai-codex
 codework auth logout --github-copilot
 
 # Authenticate the home owned by a running RPC server
-codework auth login --openai-codex --server ws://127.0.0.1:7433/rpc
+codework auth login --openai-codex --server ws://127.0.0.1:7433/rpc/v1
 ```
 
 `--home` keeps authentication alongside the rest of that Codework installation; `--auth-file` overrides the credential

packages/codework/src/cli/cmd/cmd.ts

@@ -23,13 +23,26 @@ const AuthParams = {
 		Flag.withDescription("Use GitHub Copilot OAuth (device flow)"),
 		Flag.withDefault(false),
 	),
-	server: Flag.String("server").pipe(Flag.withDescription("RPC server URL (ws://host:port/rpc)"), Flag.optional),
+	server: Flag.String("server").pipe(Flag.withDescription("RPC server URL (ws://host:port/rpc/v1)"), Flag.optional),
 	authFile: Flag.String("auth-file").pipe(
 		Flag.withDescription("Credential file (defaults to <home>/aikit/auth.json)"),
 		Flag.optional,
 	),
 };
 
+/** Where the background server binds when `tui` or `service` has to start one. */
+const ServerAddress = {
+	host: Flag.String("host").pipe(
+		Flag.withDescription("Host interface the background server binds"),
+		Flag.withDefault("127.0.0.1"),
+	),
+	port: Flag.Int("port").pipe(
+		Flag.withSchema(Schema.Int.check(Schema.isBetween({ minimum: 0, maximum: 65535 }))),
+		Flag.withDescription("Port the background server listens on"),
+		Flag.withDefault(7433),
+	),
+};
+
 const JsonFlag = Flag.Boolean("json").pipe(
 	Flag.withDescription("Print machine-readable output"),
 	Flag.withDefault(false),
@@ -82,7 +95,7 @@ export const Cmd = Spec.make("codework", {
 							description: "Sign in with a device code, no local port",
 						},
 						{
-							command: "codework auth login --openai-codex --server ws://127.0.0.1:7433/rpc",
+							command: "codework auth login --openai-codex --server ws://127.0.0.1:7433/rpc/v1",
 							description: "Sign in the running server",
 						},
 					],
@@ -108,7 +121,7 @@ export const Cmd = Spec.make("codework", {
 			description: "Start or continue an agent session",
 			params: {
 				server: Flag.String("server").pipe(
-					Flag.withDescription("RPC server URL (ws://host:port/rpc)"),
+					Flag.withDescription("RPC server URL (ws://host:port/rpc/v1)"),
 					Flag.optional,
 				),
 				prompt: Argument.String("prompt").pipe(Argument.withDescription("Prompt for the agent")),
@@ -162,29 +175,21 @@ export const Cmd = Spec.make("codework", {
 			],
 		}),
 		Spec.make("tui", {
-			description: "Launch the CodeWork terminal UI against a managed server",
+			description: "Launch the CodeWork terminal UI against the background server",
 			params: {
 				server: Flag.String("server").pipe(
-					Flag.withDescription("RPC server URL to use instead of a managed one (ws://host:port/rpc)"),
+					Flag.withDescription("RPC server URL to use instead of the background server (ws://host:port/rpc/v1)"),
 					Flag.optional,
 				),
-				host: Flag.String("host").pipe(
-					Flag.withDescription("Host interface a managed server binds"),
-					Flag.withDefault("127.0.0.1"),
-				),
-				port: Flag.Int("port").pipe(
-					Flag.withSchema(Schema.Int.check(Schema.isBetween({ minimum: 0, maximum: 65535 }))),
-					Flag.withDescription("Port a managed server listens on"),
-					Flag.withDefault(7433),
-				),
+				...ServerAddress,
 				args: Argument.variadic(
 					Argument.String("args").pipe(Argument.withDescription("Arguments forwarded to the terminal UI")),
 				),
 			},
 			examples: [
 				{ command: "codework tui", description: "Start or reuse the local server and open the terminal UI" },
 				{
-					command: "codework tui --server ws://127.0.0.1:7433/rpc",
+					command: "codework tui --server ws://127.0.0.1:7433/rpc/v1",
 					description: "Attach the terminal UI to a server you started yourself",
 				},
 			],
@@ -201,12 +206,27 @@ export const Cmd = Spec.make("codework", {
 					Flag.withDescription("Port to listen on (0 for an ephemeral port)"),
 					Flag.withDefault(7433),
 				),
+				service: Flag.Boolean("service").pipe(
+					Flag.withDescription(
+						"Run as the background server `codework tui` manages, logging to <home>/log/server.log",
+					),
+					Flag.withDefault(false),
+				),
 			},
 			examples: [
 				{ command: "codework serve", description: "Start the RPC server on 127.0.0.1:7433" },
 				{ command: "codework serve --port 0", description: "Choose an available local port" },
 			],
 		}),
+		Spec.make("service", {
+			description: "Manage the background server",
+			commands: [
+				Spec.make("start", { description: "Start the background server", params: ServerAddress }),
+				Spec.make("restart", { description: "Restart the background server", params: ServerAddress }),
+				Spec.make("status", { description: "Show background server status" }),
+				Spec.make("stop", { description: "Stop the background server" }),
+			],
+		}),
 		Spec.make("session", {
 			description: "Manage sessions",
 			commands: [

packages/codework/src/cli/cmd/handlers/serve.ts

@@ -1,25 +1,39 @@
-import { Effect, Layer } from "effect";
+import { Global } from "@codeworksh/harness/effect";
+import { Effect, FileSystem, Layer, Logger } from "effect";
 import { Runtime } from "../../../framework/runtime.ts";
+import { Registration } from "../../../server/registration.ts";
 import { Server } from "../../../server/server.ts";
 import { renderError } from "../../error.ts";
 import { harnessOptions } from "../../harness.ts";
 import { writeError } from "../../output.ts";
 import { Cmd } from "../cmd.ts";
 
+const failed = Effect.sync(() => {
+	process.exitCode = 1;
+});
+
+const report = (error: unknown) => writeError(renderError(error)).pipe(Effect.andThen(failed));
+
 export default Runtime.handler(
 	Cmd.commands.serve,
-	Effect.fn("CLI.serve")(function* ({ host, port }) {
+	Effect.fn("CLI.serve")(function* ({ host, port, service }) {
 		const shared = yield* Cmd.spec;
-		yield* Layer.launch(Server.layer({ host, port, harness: { ...harnessOptions(shared), watchModels: true } })).pipe(
-			Effect.catch((error) =>
-				writeError(renderError(error)).pipe(
-					Effect.andThen(
-						Effect.sync(() => {
-							process.exitCode = 1;
-						}),
-					),
-				),
-			),
-		);
+		const harness = { ...harnessOptions(shared), watchModels: true };
+		const serve = Layer.launch(Server.layer({ host, port, harness }));
+		if (!service) return yield* serve.pipe(Effect.catch(report));
+
+		// A background server has no terminal: its log, and the reason it stopped, go to a
+		// file the CLI that started it reads back when startup fails.
+		const background = Effect.gen(function* () {
+			const paths = yield* Global.resolve(harness.home === undefined ? {} : { home: harness.home });
+			const fs = yield* FileSystem.FileSystem;
+			yield* fs.makeDirectory(paths.log, { recursive: true });
+			const logger = Logger.formatSimple.pipe(Logger.toFile(Registration.log(paths.log), { flag: "w" }));
+			yield* serve.pipe(
+				Effect.catch((error) => Effect.logError(renderError(error).trim()).pipe(Effect.andThen(failed))),
+				Effect.provide(Logger.layer([logger])),
+			);
+		});
+		yield* background.pipe(Effect.catch(report));
 	}),
 );

packages/codework/src/cli/cmd/handlers/service/restart.ts

@@ -0,0 +1,17 @@
+import { Effect } from "effect";
+import { Runtime } from "../../../../framework/runtime.ts";
+import { Discovery } from "../../../../server/discovery.ts";
+import { reportFailure } from "../../../error.ts";
+import { writeOut } from "../../../output.ts";
+import { Service } from "../../../service.ts";
+import { Cmd } from "../../cmd.ts";
+
+export default Runtime.handler(
+	Cmd.commands.service.commands.restart,
+	Effect.fn("CLI.service.restart")(function* ({ host, port }) {
+		const options = yield* Service.options(yield* Cmd.spec, { host, port });
+		yield* Discovery.stop(options.home);
+		const server = yield* Discovery.ensure({ ...options, replace: true });
+		yield* writeOut(`${server.url}\n`);
+	}, Effect.catch(reportFailure)),
+);

packages/codework/src/cli/cmd/handlers/service/start.ts

@@ -0,0 +1,16 @@
+import { Effect } from "effect";
+import { Runtime } from "../../../../framework/runtime.ts";
+import { Discovery } from "../../../../server/discovery.ts";
+import { reportFailure } from "../../../error.ts";
+import { writeOut } from "../../../output.ts";
+import { Service } from "../../../service.ts";
+import { Cmd } from "../../cmd.ts";
+
+export default Runtime.handler(
+	Cmd.commands.service.commands.start,
+	Effect.fn("CLI.service.start")(function* ({ host, port }) {
+		const options = yield* Service.options(yield* Cmd.spec, { host, port });
+		const server = yield* Discovery.ensure({ ...options, replace: true });
+		yield* writeOut(`${server.url}\n`);
+	}, Effect.catch(reportFailure)),
+);

packages/codework/src/cli/cmd/handlers/service/status.ts

@@ -0,0 +1,16 @@
+import { Effect } from "effect";
+import { Runtime } from "../../../../framework/runtime.ts";
+import { Discovery } from "../../../../server/discovery.ts";
+import { reportFailure } from "../../../error.ts";
+import { writeOut } from "../../../output.ts";
+import { Service } from "../../../service.ts";
+import { Cmd } from "../../cmd.ts";
+
+export default Runtime.handler(
+	Cmd.commands.service.commands.status,
+	Effect.fn("CLI.service.status")(function* () {
+		const paths = yield* Service.home(yield* Cmd.spec);
+		const server = yield* Discovery.discover(paths.home);
+		yield* writeOut(`${server?.url ?? "stopped"}\n`);
+	}, Effect.catch(reportFailure)),
+);

packages/codework/src/cli/cmd/handlers/service/stop.ts

@@ -0,0 +1,14 @@
+import { Effect } from "effect";
+import { Runtime } from "../../../../framework/runtime.ts";
+import { Discovery } from "../../../../server/discovery.ts";
+import { reportFailure } from "../../../error.ts";
+import { Service } from "../../../service.ts";
+import { Cmd } from "../../cmd.ts";
+
+export default Runtime.handler(
+	Cmd.commands.service.commands.stop,
+	Effect.fn("CLI.service.stop")(function* () {
+		const paths = yield* Service.home(yield* Cmd.spec);
+		yield* Discovery.stop(paths.home);
+	}, Effect.catch(reportFailure)),
+);