feat(daemon): standardize daemon naming around hunk daemon serve (#197)

Author: benvinegar

AGENTS.md

@@ -26,7 +26,7 @@ CLI input
 - All input sources normalize into one internal changeset model.
 - Pager mode has two paths: full diff UI for patch-like stdin, plain-text fallback for non-diff pager content.
 - View defaults are layered through built-ins, user config, repo `.hunk/config.toml`, command sections, pager sections, and CLI flags.
-- `hunk mcp serve` runs one loopback daemon that brokers agent commands to many live Hunk sessions. Normal Hunk sessions should auto-start and register with that daemon when MCP is enabled. Keep it local-only and session-brokered rather than opening per-TUI ports.
+- `hunk daemon serve` runs one loopback daemon that brokers agent commands to many live Hunk sessions. Normal Hunk sessions should auto-start and register with that daemon when session brokering is enabled. Keep it local-only and session-brokered rather than opening per-TUI ports.
 - Agent rationale is optional sidecar JSON matched onto files/hunks.
 - The order of `files` in the sidecar is intentional. Hunk uses that order for the sidebar and main review stream.
 - Prefer one source of truth for each user-visible behavior. When rendering, navigation, scrolling, or note placement share the same model, derive them from the same planning layer rather than maintaining parallel implementations.

src/core/cli.test.ts

@@ -215,11 +215,19 @@ describe("parseCli", () => {
     });
   });
 
-  test("parses the MCP daemon command", async () => {
+  test("parses the daemon serve command", async () => {
+    const parsed = await parseCli(["bun", "hunk", "daemon", "serve"]);
+
+    expect(parsed).toEqual({
+      kind: "daemon-serve",
+    });
+  });
+
+  test("parses the legacy MCP daemon alias", async () => {
     const parsed = await parseCli(["bun", "hunk", "mcp", "serve"]);
 
     expect(parsed).toEqual({
-      kind: "mcp-serve",
+      kind: "daemon-serve",
     });
   });
 

src/core/cli.ts

@@ -136,7 +136,7 @@ function renderCliHelp() {
     "  hunk difftool <left> <right> [path]     review Git difftool file pairs",
     "  hunk session <subcommand>               inspect or control a live Hunk session",
     "  hunk skill path                         print the bundled Hunk review skill path",
-    "  hunk mcp serve                          run the local Hunk session daemon",
+    "  hunk daemon serve                       run the local Hunk session daemon",
     "",
     "Global options:",
     "  -h, --help                              show help",
@@ -555,7 +555,7 @@ async function parseDifftoolCommand(tokens: string[], argv: string[]): Promise<P
 }
 
 function requireReloadableCliInput(input: ParsedCliInput): CliInput {
-  if (input.kind === "help" || input.kind === "pager" || input.kind === "mcp-serve") {
+  if (input.kind === "help" || input.kind === "pager" || input.kind === "daemon-serve") {
     throw new Error(
       "Session reload requires a Hunk review command after --, such as `diff` or `show`.",
     );
@@ -1190,15 +1190,15 @@ async function parseSkillCommand(tokens: string[]): Promise<HelpCommandInput> {
   };
 }
 
-/** Parse `hunk mcp serve` as the local daemon entrypoint. */
-async function parseMcpCommand(tokens: string[]): Promise<ParsedCliInput> {
+/** Parse `hunk daemon serve` as the canonical local daemon entrypoint. */
+async function parseDaemonCommand(tokens: string[]): Promise<ParsedCliInput> {
   const [subcommand, ...rest] = tokens;
   if (!subcommand || subcommand === "--help" || subcommand === "-h") {
     return {
       kind: "help",
       text:
         [
-          "Usage: hunk mcp serve",
+          "Usage: hunk daemon serve",
           "",
           "Run the local Hunk session daemon and websocket session broker.",
           "",
@@ -1211,23 +1211,23 @@ async function parseMcpCommand(tokens: string[]): Promise<ParsedCliInput> {
   }
 
   if (subcommand !== "serve") {
-    throw new Error("Only `hunk mcp serve` is supported.");
+    throw new Error("Only `hunk daemon serve` is supported.");
   }
 
   if (rest.includes("--help") || rest.includes("-h")) {
     return {
       kind: "help",
       text:
         [
-          "Usage: hunk mcp serve",
+          "Usage: hunk daemon serve",
           "",
           "Run the local Hunk session daemon and websocket session broker.",
         ].join("\n") + "\n",
     };
   }
 
   return {
-    kind: "mcp-serve",
+    kind: "daemon-serve",
   };
 }
 
@@ -1309,8 +1309,9 @@ export async function parseCli(argv: string[]): Promise<ParsedCliInput> {
       return parseSessionCommand(rest);
     case "skill":
       return parseSkillCommand(rest);
+    case "daemon":
     case "mcp":
-      return parseMcpCommand(rest);
+      return parseDaemonCommand(rest);
     default:
       throw new Error(`Unknown command: ${commandName}`);
   }

src/core/liveComments.ts

@@ -1,6 +1,6 @@
 import type { Hunk } from "@pierre/diffs";
 import type { DiffFile } from "./types";
-import type { CommentTargetInput, DiffSide, LiveComment } from "../mcp/types";
+import type { CommentTargetInput, DiffSide, LiveComment } from "../daemon/types";
 
 export interface ResolvedCommentTarget {
   hunkIndex: number;
@@ -114,7 +114,7 @@ export function resolveCommentTarget(
   };
 }
 
-/** Convert one incoming MCP comment command into a live annotation. */
+/** Convert one incoming session-daemon comment command into a live annotation. */
 export function buildLiveComment(
   input: CommentTargetInput & { side: DiffSide; line: number },
   commentId: string,

src/core/startup.test.ts

@@ -32,18 +32,18 @@ describe("startup planning", () => {
     expect(loaded).toBe(false);
   });
 
-  test("passes the MCP serve command through without app bootstrap work", async () => {
+  test("passes the daemon serve command through without app bootstrap work", async () => {
     let loaded = false;
 
-    const plan = await prepareStartupPlan(["bun", "hunk", "mcp", "serve"], {
-      parseCliImpl: async () => ({ kind: "mcp-serve" }),
+    const plan = await prepareStartupPlan(["bun", "hunk", "daemon", "serve"], {
+      parseCliImpl: async () => ({ kind: "daemon-serve" }),
       loadAppBootstrapImpl: async () => {
         loaded = true;
         throw new Error("unreachable");
       },
     });
 
-    expect(plan).toEqual({ kind: "mcp-serve" });
+    expect(plan).toEqual({ kind: "daemon-serve" });
     expect(loaded).toBe(false);
   });
 

src/core/startup.ts

@@ -18,7 +18,7 @@ export type StartupPlan =
       text: string;
     }
   | {
-      kind: "mcp-serve";
+      kind: "daemon-serve";
     }
   | {
       kind: "session-command";
@@ -70,9 +70,9 @@ export async function prepareStartupPlan(
     };
   }
 
-  if (parsedCliInput.kind === "mcp-serve") {
+  if (parsedCliInput.kind === "daemon-serve") {
     return {
-      kind: "mcp-serve",
+      kind: "daemon-serve",
     };
   }
 

src/core/types.ts

@@ -84,8 +84,8 @@ export interface PagerCommandInput {
   options: CommonOptions;
 }
 
-export interface McpServeCommandInput {
-  kind: "mcp-serve";
+export interface DaemonServeCommandInput {
+  kind: "daemon-serve";
 }
 
 export type SessionCommandOutput = "text" | "json";
@@ -263,7 +263,7 @@ export type ParsedCliInput =
   | CliInput
   | HelpCommandInput
   | PagerCommandInput
-  | McpServeCommandInput
+  | DaemonServeCommandInput
   | SessionCommandInput;
 
 export interface AppBootstrap {

src/mcp/client.test.ts src/daemon/client.test.tssrc/mcp/client.test.ts renamed to src/daemon/client.test.ts

@@ -4,7 +4,7 @@ import {
   createTestSessionRegistration,
   createTestSessionReviewFile,
   createTestSessionSnapshot,
-} from "../../test/helpers/mcp-fixtures";
+} from "../../test/helpers/session-daemon-fixtures";
 import { HUNK_SESSION_API_VERSION, HUNK_SESSION_DAEMON_VERSION } from "../session/protocol";
 import { HunkHostClient } from "./client";
 
@@ -75,8 +75,8 @@ afterEach(() => {
   console.error = originalConsoleError;
 });
 
-describe("Hunk MCP client", () => {
-  test("logs one actionable warning when MCP is configured for a non-loopback host without opt-in", async () => {
+describe("Hunk session daemon client", () => {
+  test("logs one actionable warning when the session daemon is configured for a non-loopback host without opt-in", async () => {
     process.env.HUNK_MCP_HOST = "0.0.0.0";
     process.env.HUNK_MCP_PORT = "47657";
     delete process.env.HUNK_MCP_UNSAFE_ALLOW_REMOTE;
@@ -91,10 +91,10 @@ describe("Hunk MCP client", () => {
 
     try {
       client.start();
-      await waitUntil("non-loopback MCP warning", () => messages.length === 1);
+      await waitUntil("non-loopback session-daemon warning", () => messages.length === 1);
 
       expect(messages[0]).toContain(
-        "[hunk:mcp] Hunk MCP refuses to bind 0.0.0.0:47657 because the daemon is local-only by default.",
+        "[hunk:session] Hunk session daemon refuses to bind 0.0.0.0:47657 because the daemon is local-only by default.",
       );
       expect(messages[0]).toContain("HUNK_MCP_UNSAFE_ALLOW_REMOTE=1");
     } finally {
@@ -228,7 +228,7 @@ describe("Hunk MCP client", () => {
     }
   }, 10_000);
 
-  test("logs one actionable warning when a non-Hunk listener owns the MCP port", async () => {
+  test("logs one actionable warning when a non-Hunk listener owns the session daemon port", async () => {
     const conflictingListener = createServer((_request, response) => {
       response.writeHead(404, { "content-type": "text/plain" });
       response.end("not hunk");
@@ -253,14 +253,14 @@ describe("Hunk MCP client", () => {
 
     try {
       client.start();
-      await waitUntil("initial MCP conflict warning", () => messages.length === 1);
+      await waitUntil("initial session-daemon conflict warning", () => messages.length === 1);
 
       client.start();
       await Bun.sleep(2_000);
 
       expect(messages).toHaveLength(1);
       expect(messages[0]).toContain(
-        `[hunk:mcp] Hunk MCP port 127.0.0.1:${port} is already in use by another process.`,
+        `[hunk:session] Hunk session daemon port 127.0.0.1:${port} is already in use by another process.`,
       );
       expect(messages[0]).toContain(
         "Stop the conflicting process or set HUNK_MCP_PORT to a different loopback port.",

src/mcp/client.ts src/daemon/client.tssrc/mcp/client.ts renamed to src/daemon/client.ts

@@ -13,8 +13,8 @@ import type {
 } from "./types";
 import {
   HUNK_SESSION_SOCKET_PATH,
-  resolveHunkMcpConfig,
-  type ResolvedHunkMcpConfig,
+  resolveHunkSessionDaemonConfig,
+  type ResolvedHunkSessionDaemonConfig,
 } from "./config";
 import {
   ensureHunkDaemonAvailable,
@@ -55,7 +55,7 @@ interface HunkAppBridge {
   ) => Promise<ClearedCommentsResult>;
 }
 
-/** Keep one running Hunk TUI session registered with the local MCP daemon. */
+/** Keep one running Hunk TUI session registered with the local session daemon. */
 export class HunkHostClient {
   private websocket: WebSocket | null = null;
   private bridge: HunkAppBridge | null = null;
@@ -121,7 +121,7 @@ export class HunkHostClient {
   }
 
   private resolveConfig() {
-    return resolveHunkMcpConfig();
+    return resolveHunkSessionDaemonConfig();
   }
 
   private async ensureDaemonAndConnect() {
@@ -130,7 +130,7 @@ export class HunkHostClient {
     this.connect(config);
   }
 
-  private async ensureDaemonAvailable(config: ResolvedHunkMcpConfig) {
+  private async ensureDaemonAvailable(config: ResolvedHunkSessionDaemonConfig) {
     await ensureHunkDaemonAvailable({
       config,
       timeoutMs: DAEMON_STARTUP_TIMEOUT_MS,
@@ -155,7 +155,7 @@ export class HunkHostClient {
     this.lastConnectionWarning = null;
   }
 
-  private async restartIncompatibleDaemon(config: ResolvedHunkMcpConfig) {
+  private async restartIncompatibleDaemon(config: ResolvedHunkSessionDaemonConfig) {
     reportHunkDaemonUpgradeRestart();
     const health = await readHunkDaemonHealth(config);
     const pid = health?.pid;
@@ -205,7 +205,7 @@ export class HunkHostClient {
     });
   }
 
-  private connect(config: ResolvedHunkMcpConfig) {
+  private connect(config: ResolvedHunkSessionDaemonConfig) {
     if (this.stopped || this.websocket) {
       return;
     }
@@ -331,7 +331,7 @@ export class HunkHostClient {
 
   private dispatchCommand(message: SessionServerMessage): Promise<SessionCommandResult> {
     if (!this.bridge) {
-      throw new Error("Hunk MCP bridge is not connected.");
+      throw new Error("Hunk session bridge is not connected.");
     }
 
     switch (message.command) {
@@ -372,12 +372,13 @@ export class HunkHostClient {
   }
 
   private warnUnavailable(error: unknown) {
-    const message = error instanceof Error ? error.message : "Unknown Hunk MCP connection error.";
+    const message =
+      error instanceof Error ? error.message : "Unknown Hunk session daemon connection error.";
     if (message === this.lastConnectionWarning) {
       return;
     }
 
     this.lastConnectionWarning = message;
-    console.error(`[hunk:mcp] ${message}`);
+    console.error(`[hunk:session] ${message}`);
   }
 }

src/mcp/config.test.ts src/daemon/config.test.tssrc/mcp/config.test.ts renamed to src/daemon/config.test.ts

@@ -1,12 +1,12 @@
 import { describe, expect, test } from "bun:test";
 import {
   HUNK_MCP_UNSAFE_ALLOW_REMOTE_ENV,
-  allowsUnsafeRemoteMcp,
+  allowsUnsafeRemoteSessionDaemon,
   isLoopbackHost,
-  resolveHunkMcpConfig,
+  resolveHunkSessionDaemonConfig,
 } from "./config";
 
-describe("Hunk MCP config", () => {
+describe("Hunk session daemon config", () => {
   test("accepts loopback hosts without an unsafe override", () => {
     expect(isLoopbackHost("127.0.0.1")).toBe(true);
     expect(isLoopbackHost("127.1.2.3")).toBe(true);
@@ -21,14 +21,14 @@ describe("Hunk MCP config", () => {
 
   test("refuses non-loopback binds unless the unsafe override is enabled", () => {
     expect(() =>
-      resolveHunkMcpConfig({
+      resolveHunkSessionDaemonConfig({
         HUNK_MCP_HOST: "0.0.0.0",
         HUNK_MCP_PORT: "49000",
       }),
     ).toThrow("local-only by default");
 
     expect(
-      resolveHunkMcpConfig({
+      resolveHunkSessionDaemonConfig({
         HUNK_MCP_HOST: "0.0.0.0",
         HUNK_MCP_PORT: "49000",
         [HUNK_MCP_UNSAFE_ALLOW_REMOTE_ENV]: "1",
@@ -39,9 +39,11 @@ describe("Hunk MCP config", () => {
     });
   });
 
-  test("reports whether unsafe remote MCP access was explicitly enabled", () => {
-    expect(allowsUnsafeRemoteMcp({})).toBe(false);
-    expect(allowsUnsafeRemoteMcp({ [HUNK_MCP_UNSAFE_ALLOW_REMOTE_ENV]: "0" })).toBe(false);
-    expect(allowsUnsafeRemoteMcp({ [HUNK_MCP_UNSAFE_ALLOW_REMOTE_ENV]: "1" })).toBe(true);
+  test("reports whether unsafe remote session-daemon access was explicitly enabled", () => {
+    expect(allowsUnsafeRemoteSessionDaemon({})).toBe(false);
+    expect(allowsUnsafeRemoteSessionDaemon({ [HUNK_MCP_UNSAFE_ALLOW_REMOTE_ENV]: "0" })).toBe(
+      false,
+    );
+    expect(allowsUnsafeRemoteSessionDaemon({ [HUNK_MCP_UNSAFE_ALLOW_REMOTE_ENV]: "1" })).toBe(true);
   });
 });