taskchef 7.3.0 → 7.4.0

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "taskchef",
-  "version": "7.3.0",
+  "version": "7.4.0",
   "description": "Dispatch work from a data-only workspace to visible Codex project tasks.",
   "author": {
     "name": "Favo Yang",

package/README.md

@@ -33,7 +33,8 @@ npm install --global taskchef
 
 The plugin provides four skills and a local MCP server. The npm installation
 puts the `taskchef` CLI on `PATH`. TaskChef installs no hooks, schedules,
-daemons, or background identity search.
+daemons, login items, system services, or background identity search and needs
+no elevated permissions.
 
 ## Bootstrap and configure
 
@@ -93,6 +94,12 @@ reads the executor's own `CODEX_THREAD_ID`, self-links, and reports lifecycle
 state. Independent outcomes may become separate executors; dependent work
 should stay together.
 
+At the start of every dispatcher turn, the managed workspace instructions ask
+the MCP server to best-effort ensure the dashboard. A startup failure never
+blocks an answer, report, or delegation. Every dispatcher response ends with
+the stable [TaskChef Dashboard](http://127.0.0.1:3210/) link; a created-task
+directive remains on the preceding line so dispatch still returns immediately.
+
 For example, TaskChef generates this shape:
 
 ```text
@@ -146,12 +153,35 @@ an unambiguous eight-character prefix.
 
 ## Dashboard
 
+Dispatcher turns call the input-free `ensure_dashboard` MCP tool. It starts at
+most one dashboard inside the existing TaskChef MCP process on
+`127.0.0.1:3210`, or reuses a listener only when its bounded `/api/health`
+identity proves the exact TaskChef/dashboard-server version and the same
+canonical workspace. The response says `started` or `reused` and includes the
+stable URL, canonical workspace, and versions.
+
+The in-process dashboard closes with the MCP process. Closing Codex or reloading
+the plugin may therefore stop the dashboard; the next dispatcher turn restores
+it. TaskChef adds no OS-persistent component.
+
+For manual development, run the foreground CLI:
+
 ```sh
 taskchef dashboard
+taskchef dashboard --port 3211
 ```
 
 The loopback dashboard watches `tasks.jsonl`, groups current states, and opens
 linked Codex tasks. It does not mutate TaskChef data and prints its local URL.
+When a compatible foreground dashboard already owns port 3210,
+`ensure_dashboard` reuses it but does not take ownership. If an unknown,
+different-workspace, or stale-version process owns the port, TaskChef reports a
+concise conflict and never kills or replaces that process. The foreground CLI
+similarly asks you to stop the listener or choose another `--port`.
+
+The health endpoint contains only a fixed service marker, health schema,
+TaskChef version, dashboard-server version, and canonical workspace. It exposes
+no task data, credentials, environment variables, process control, or secrets.
 
 ## Common recovery
 

package/assets/taskchef-dispatcher-instructions.md

@@ -3,6 +3,9 @@
 
 This folder is the canonical per-user TaskChef dispatcher workspace.
 
+- Early in every dispatcher turn, best-effort call the TaskChef
+  `ensure_dashboard` MCP tool. Dashboard startup failure must not block direct
+  TaskChef answers, reporting, or delegation.
 - Use `$taskchef-bootstrap` when initializing or refreshing this workspace,
   changing or listing its configured projects, running TaskChef doctor,
   or repairing its managed instructions.
@@ -20,4 +23,10 @@ This folder is the canonical per-user TaskChef dispatcher workspace.
   write status or results to this workspace.
 - Explicit invocations of TaskChef skills from other Codex projects use this
   same workspace and task history through TaskChef's global resolution rules.
+- Every final response in this dispatcher workspace must end with this exact
+  clickable link on its final non-empty line:
+  `[TaskChef Dashboard](http://127.0.0.1:3210/)`. Keep any
+  `::created-thread{...}` directive required by delegation on its own line
+  immediately before the dashboard link so the immediate-return contract still
+  holds. Include the link even when `ensure_dashboard` failed.
 <!-- taskchef:dispatcher-instructions:end -->

package/docs/spec.md

@@ -39,8 +39,8 @@ is dated research, not contract.
   privacy, and idempotency. It MUST NOT dispatch the owned assignment again.
 - `taskchef-report` MUST own on-demand reporting. It MUST NOT poll or persist
   inferred state.
-- The MCP server MUST expose four primary lifecycle tools plus the deprecated
-  `report_result` compatibility alias specified below.
+- The MCP server MUST expose `ensure_dashboard`, four primary lifecycle tools,
+  and the deprecated `report_result` compatibility alias specified below.
 - The CLI MAY administer and inspect the workspace, but MUST NOT provide a
   second agent lifecycle protocol.
 - The dashboard MUST be read-only with respect to dispatcher files.
@@ -100,6 +100,13 @@ fields MUST NOT change after recording.
 
 ## Required lifecycle
 
+At the start of every dispatcher turn, the dispatcher SHOULD call
+`ensure_dashboard` best-effort. Failure MUST NOT block direct TaskChef answers,
+reporting, or delegation. Every dispatcher final response MUST end with the
+exact clickable `[TaskChef Dashboard](http://127.0.0.1:3210/)` link even when
+ensure failed. A created-thread directive MUST remain on its own line before
+the final link, preserving the delegate skill's immediate-return contract.
+
 1. The dispatcher MUST call `prepare_dispatch` once per outcome.
 2. It MUST choose exactly one configured project and exact native-project path.
 3. It MUST build the instruction with the user's outcome beginning on line 1
@@ -144,6 +151,43 @@ path. Success returns both one text content item and the stated structured
 object. Validation, marker, identity, uniqueness, freshness, or filesystem
 failures are surfaced as tool errors and MUST NOT partially mutate the log.
 
+### `ensure_dashboard`
+
+**Caller:** dispatcher. **Mutation:** starts at most one in-process loopback
+HTTP server; it does not mutate dispatcher workspace files.
+
+**Input:** empty object.
+
+**Structured output:**
+
+```text
+{ dashboard: {
+  action: "started" | "reused",
+  url: "http://127.0.0.1:3210/",
+  workspace: string,
+  taskchefVersion: string,
+  serverVersion: string
+} }
+```
+
+Calls MUST serialize within one MCP process. The first call starts an owned
+dashboard or reuses an exact compatible listener; later and concurrent calls
+are idempotent and report reuse after the single start. The stable default MUST
+bind only to `127.0.0.1:3210` and MUST NOT accept a model-supplied workspace,
+host, or port.
+
+Before reuse, TaskChef MUST query a bounded loopback identity endpoint and
+require the exact fixed service/schema, TaskChef version, dashboard-server
+version, and canonical workspace. An unknown, malformed, different-workspace,
+or stale-version listener MUST produce a concise actionable conflict. TaskChef
+MUST NOT kill, replace, signal, or otherwise control that listener. A startup
+failure MUST leave no owned listener. The MCP server MUST close its owned
+dashboard when its transport or process shuts down; it MUST NOT close a reused
+external foreground server.
+
+**Annotations:** `readOnlyHint: false`, `destructiveHint: false`,
+`openWorldHint: false`.
+
 ### `prepare_dispatch`
 
 **Caller:** dispatcher. **Mutation:** none.
@@ -259,7 +303,13 @@ reports MAY read a selected task once when metadata is newer or evidence is
 uncertain. Reports MUST NOT poll or classify assistant prose.
 
 The dashboard MUST bind only to loopback, validate the current workspace
-snapshot, and avoid sessions or shared client state. Direct thread navigation
+snapshot, and avoid sessions or shared client state. `GET /api/health` MUST
+return only the bounded service identity, health schema, exact TaskChef and
+dashboard-server versions, and canonical workspace. It MUST NOT return task
+records, secrets, credentials, environment values, or process-control data.
+Identity remains available while an already-started monitor retains its last
+valid snapshot after a later invalid task log; an invalid initial log MAY fail
+startup safely. Direct thread navigation
 MUST require a canonical Codex UUIDv7. Otherwise it MAY open the revalidated
 configured project. Project paths from task history MUST be matched against
 current configuration before use.
@@ -279,3 +329,9 @@ loopback origin, and current configuration before acting.
 TaskChef MUST NOT use lifecycle hooks, schedules, polling, recent-thread search,
 transcript search, title matching, hidden reasoning, or token usage to discover
 identity or infer semantic results.
+
+TaskChef MUST NOT install or require daemons, launchd agents, login items,
+system services, cron jobs, hooks, privileged components, or elevated/system
+permissions for dashboard availability. Availability is best-effort while the
+owning Codex/plugin MCP process is alive and is not guaranteed while Codex is
+closed.

package/docs/workflows.md

@@ -14,16 +14,55 @@ research.
 | `skills/taskchef-executor/SKILL.md` | Own, self-link, execute, and report every executor turn. |
 | `skills/taskchef-bootstrap/SKILL.md` | Initialize current workspace and configure projects. |
 | `skills/taskchef-report/SKILL.md` | Select cached tasks and perform bounded live checks. |
-| `src/mcp.js` | Four primary lifecycle tools, one deprecated alias, and MCP annotations. |
+| `src/mcp.js` | Dashboard ensure, four primary lifecycle tools, one deprecated alias, shutdown ownership, and MCP annotations. |
 | `src/delegation.js` | UUID marker, concise executor-skill invocation shape, and creation-failure handling. |
 | `src/workspace.js` | Current schemas, validation, locking, atomic JSONL writes, linking, and result freshness. |
 | `src/cli.js` | Administration, inspection, diagnostics, and dashboard startup. |
-| `src/dashboard.js` | Validated snapshots, SSE fan-out, and bounded open actions. |
+| `src/dashboard.js` | Versioned health identity, validated snapshots, SSE fan-out, and bounded open actions. |
+| `src/dashboard-manager.js` | Concurrent singleton ensure, exact listener reuse, conflicts, and owned shutdown. |
 
 The MCP process resolves `TASKCHEF_WORKSPACE` once and never accepts a model
 supplied path. The CLI resolves `--workspace`, then the environment, then the
 per-user default.
 
+## Dispatcher dashboard lifecycle
+
+The generated managed `AGENTS.md` block makes dashboard maintenance a
+best-effort prelude to every dispatcher turn and keeps response ordering
+centralized instead of duplicating it across delegate/report skills.
+
+```mermaid
+sequenceDiagram
+  autonumber
+  participant D as Dispatcher
+  participant M as TaskChef MCP
+  participant H as Loopback health
+  participant S as Dashboard server
+  D->>M: ensure_dashboard()
+  M->>M: Serialize concurrent ensure calls
+  M->>H: GET 127.0.0.1:3210/api/health
+  alt Exact service, versions, and canonical workspace
+    H-->>M: Bounded compatible identity
+    M-->>D: reused, URL, workspace, versions
+  else No listener
+    H--xM: Connection refused
+    M->>S: Start in this MCP process on 127.0.0.1:3210
+    S-->>M: Owned server
+    M-->>D: started, URL, workspace, versions
+  else Unknown, stale, or different workspace
+    H-->>M: Missing or incompatible identity
+    M-->>D: Actionable conflict, listener untouched
+  end
+  Note over D: Continue even when ensure failed
+  D-->>D: Answer, report, or dispatch
+  Note over D: Created-thread directive, when any, precedes final dashboard link
+```
+
+When the MCP transport or plugin process closes, it closes only the server it
+started. A compatible foreground `taskchef dashboard` listener may be reused
+but remains owned by that CLI process. No TaskChef path terminates an unknown
+listener or installs OS persistence.
+
 ## Normal delegation and self-linking
 
 The dispatcher uses native Codex project discovery for routing and MCP for
@@ -235,8 +274,9 @@ sequenceDiagram
 ```
 
 The dashboard binds to `127.0.0.1`, has no shared session state, limits
-request bodies, and checks origin/authority for stateful local actions. Historical
-project paths are untrusted until matched against current configuration.
+request bodies, and checks origin/authority for stateful local actions. Its
+bounded identity endpoint contains no task data or secrets. Historical project
+paths are untrusted until matched against current configuration.
 
 ## Concurrency and trust boundaries
 

package/index.js

@@ -57,10 +57,19 @@ export {
 } from "./src/codex-app.js";
 
 export {
+  DASHBOARD_HEALTH_MAX_BYTES,
+  DASHBOARD_HEALTH_PATH,
   DashboardMonitor,
   createDashboardServer,
   dashboardAuthority,
   sortTasksByMeaningfulUpdate,
 } from "./src/dashboard.js";
 
+export {
+  createDashboardManager,
+  readDashboardIdentity,
+} from "./src/dashboard-manager.js";
+
+export { DASHBOARD_SERVER_VERSION, TASKCHEF_VERSION } from "./src/version.js";
+
 export { createTaskChefMcpServer } from "./src/mcp.js";

package/mcp/server.js

@@ -5,3 +5,15 @@ import { createTaskChefMcpServer } from "../src/mcp.js";
 
 const server = createTaskChefMcpServer();
 await server.connect(new StdioServerTransport());
+
+let shutdownPromise = null;
+const shutdown = () => {
+  shutdownPromise ??= server.close().catch((error) => {
+    process.stderr.write(`TaskChef MCP shutdown failed: ${error.message}\n`);
+    process.exitCode = 1;
+  });
+  return shutdownPromise;
+};
+
+process.once("SIGINT", shutdown);
+process.once("SIGTERM", shutdown);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "taskchef",
-  "version": "7.3.0",
+  "version": "7.4.0",
   "description": "A non-blocking interactive dispatcher for visible Codex tasks.",
   "license": "MIT",
   "author": "Favo Yang",

package/skills/taskchef-bootstrap/SKILL.md

@@ -19,8 +19,10 @@ all deterministic workspace operations.
   dispatcher workspace. Preserve unrelated user-owned paths.
 - Do not dispatch tasks or report on executor threads during bootstrap unless
   the user separately requests those actions.
-- Never create hooks, schedules, polling, or daemons. TaskChef executors
-  self-link through the installed MCP server.
+- Never create hooks, schedules, polling, daemons, login items, or system
+  services. The managed dispatcher instructions own best-effort dashboard
+  startup and final-link guidance; bootstrap only refreshes that managed block.
+  TaskChef executors self-link through the installed MCP server.
 
 ## Initialize and repair
 

package/src/cli.js

@@ -409,10 +409,22 @@ async function dashboard(args) {
     values: ["--port", "--workspace"],
     switches: ["--json"],
   });
-  const server = await createDashboardServer({
-    workspace: workspaceRoot(args),
-    port: dashboardPort(args),
-  });
+  const port = dashboardPort(args);
+  let server;
+  try {
+    server = await createDashboardServer({
+      workspace: workspaceRoot(args),
+      port,
+    });
+  } catch (error) {
+    if (error?.code === "EADDRINUSE") {
+      throw new Error(
+        `dashboard port 127.0.0.1:${port} is already in use; `
+        + "stop the existing listener or choose another --port (TaskChef will not terminate it)",
+      );
+    }
+    throw error;
+  }
   print({
     schemaVersion: 1,
     url: server.url,
@@ -461,8 +473,10 @@ Project import reads a JSON
 array from a file, or from standard input when the source is '-' or omitted.
 Workspace resolution precedence is --workspace, TASKCHEF_WORKSPACE, then
 ~/.agents/taskchef.
-The dashboard binds to 127.0.0.1 and reads the canonical task log without
-modifying dispatcher-workspace files.
+The foreground dashboard binds to 127.0.0.1 and reads the canonical task log
+without modifying dispatcher-workspace files. The dispatcher MCP may reuse a
+compatible foreground server on port 3210; neither mode terminates a listener
+that already occupies its requested port.
 `);
 }
 

package/src/dashboard-manager.js

@@ -0,0 +1,183 @@
+import http from "node:http";
+import { realpath } from "node:fs/promises";
+import path from "node:path";
+
+import {
+  DASHBOARD_HEALTH_MAX_BYTES,
+  DASHBOARD_HEALTH_PATH,
+  createDashboardServer,
+  dashboardAuthority,
+} from "./dashboard.js";
+import { DASHBOARD_SERVER_VERSION, TASKCHEF_VERSION } from "./version.js";
+
+const DEFAULT_HOST = "127.0.0.1";
+const DEFAULT_PORT = 3210;
+const HEALTH_TIMEOUT_MS = 750;
+
+function expectedIdentity(workspace, taskchefVersion, serverVersion) {
+  return {
+    schemaVersion: 1,
+    service: "taskchef-dashboard",
+    taskchefVersion,
+    serverVersion,
+    workspace,
+  };
+}
+
+function isExactIdentity(value, expected) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const keys = Object.keys(value).sort();
+  const expectedKeys = Object.keys(expected).sort();
+  return keys.length === expectedKeys.length
+    && keys.every((key, index) => key === expectedKeys[index])
+    && expectedKeys.every((key) => value[key] === expected[key]);
+}
+
+function listenerConflict(url, detail) {
+  return new Error(
+    `TaskChef dashboard port conflict at ${url} ${detail} `
+    + "Stop that listener or choose another port for the foreground dashboard CLI; TaskChef will not terminate it.",
+  );
+}
+
+export function readDashboardIdentity({
+  host = DEFAULT_HOST,
+  port = DEFAULT_PORT,
+  maximumBytes = DASHBOARD_HEALTH_MAX_BYTES,
+  timeoutMs = HEALTH_TIMEOUT_MS,
+} = {}) {
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const finish = (error, value) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(deadline);
+      if (error) reject(error);
+      else resolve(value);
+    };
+    const request = http.get({
+      host,
+      port,
+      path: DASHBOARD_HEALTH_PATH,
+      headers: {
+        Accept: "application/json",
+        Host: dashboardAuthority(host, port),
+      },
+    }, (response) => {
+      const chunks = [];
+      let total = 0;
+      response.on("data", (chunk) => {
+        total += chunk.length;
+        if (total > maximumBytes) {
+          const error = new Error("dashboard health response exceeds the identity limit");
+          finish(error);
+          request.destroy(error);
+          return;
+        }
+        chunks.push(chunk);
+      });
+      response.on("end", () => {
+        if (response.statusCode !== 200) {
+          finish(new Error(`dashboard health returned HTTP ${response.statusCode}`));
+          return;
+        }
+        try {
+          finish(null, JSON.parse(Buffer.concat(chunks, total).toString("utf8")));
+        } catch {
+          finish(new Error("dashboard health returned invalid JSON"));
+        }
+      });
+    });
+    const deadline = setTimeout(() => {
+      const error = new Error("dashboard health request timed out");
+      finish(error);
+      request.destroy(error);
+    }, timeoutMs);
+    request.on("error", (error) => finish(error));
+  });
+}
+
+function listenerAbsent(error) {
+  return error?.code === "ECONNREFUSED" || error?.code === "EHOSTUNREACH";
+}
+
+export function createDashboardManager({
+  workspace,
+  host = DEFAULT_HOST,
+  port = DEFAULT_PORT,
+  taskchefVersion = TASKCHEF_VERSION,
+  serverVersion = DASHBOARD_SERVER_VERSION,
+  createServer = createDashboardServer,
+  readIdentity = readDashboardIdentity,
+} = {}) {
+  let canonicalWorkspace;
+  let ownedServer = null;
+  let ensurePromise = null;
+  let closePromise = null;
+
+  const publicResult = (action) => ({
+    action,
+    url: `http://${dashboardAuthority(host, ownedServer?.port ?? port)}/`,
+    workspace: canonicalWorkspace,
+    taskchefVersion,
+    serverVersion,
+  });
+
+  const probe = async () => {
+    const url = `http://${dashboardAuthority(host, port)}/`;
+    let identity;
+    try {
+      identity = await readIdentity({ host, port });
+    } catch (error) {
+      if (listenerAbsent(error)) return false;
+      throw listenerConflict(url, `is occupied but did not return a compatible identity (${error.message}).`);
+    }
+    const expected = expectedIdentity(canonicalWorkspace, taskchefVersion, serverVersion);
+    if (!isExactIdentity(identity, expected)) {
+      throw listenerConflict(url, "belongs to an unknown, stale, or different-workspace service.");
+    }
+    return true;
+  };
+
+  const ensureOnce = async () => {
+    canonicalWorkspace ??= await realpath(path.resolve(workspace));
+    if (ownedServer) return publicResult("reused");
+    if (await probe()) return publicResult("reused");
+    try {
+      ownedServer = await createServer({
+        workspace: canonicalWorkspace,
+        host,
+        port,
+        taskchefVersion,
+        serverVersion,
+      });
+      return publicResult("started");
+    } catch (error) {
+      if (error?.code !== "EADDRINUSE") throw error;
+      if (await probe()) return publicResult("reused");
+      throw error;
+    }
+  };
+
+  return {
+    async ensure() {
+      if (closePromise) throw new Error("TaskChef dashboard manager is shutting down");
+      if (ensurePromise) {
+        await ensurePromise;
+        return publicResult("reused");
+      }
+      ensurePromise = ensureOnce().finally(() => { ensurePromise = null; });
+      return ensurePromise;
+    },
+    async close() {
+      closePromise ??= (async () => {
+        await ensurePromise?.catch(() => {});
+        const server = ownedServer;
+        ownedServer = null;
+        await server?.close();
+      })();
+      return closePromise;
+    },
+    get owned() { return ownedServer !== null; },
+  };
+}

package/src/dashboard.js

@@ -16,6 +16,7 @@ import {
   parseTaskLogContent,
   readConfig,
 } from "./workspace.js";
+import { DASHBOARD_SERVER_VERSION, TASKCHEF_VERSION } from "./version.js";
 
 const TASKS_FILE_NAME = "tasks.jsonl";
 const STATIC_ROOT = fileURLToPath(new URL("./dashboard/", import.meta.url));
@@ -24,6 +25,8 @@ const LOOPBACK_HOSTS = new Set(["127.0.0.1", "::1"]);
 const DEFAULT_MAX_FILE_BYTES = 16 * 1024 * 1024;
 const DEFAULT_MAX_TASKS = 2_000;
 const DEFAULT_MAX_EVENT_CLIENTS = 16;
+export const DASHBOARD_HEALTH_PATH = "/api/health";
+export const DASHBOARD_HEALTH_MAX_BYTES = 8 * 1024;
 const CONTENT_SECURITY_POLICY = [
   "default-src 'self'",
   "base-uri 'none'",
@@ -402,6 +405,8 @@ export async function createDashboardServer({
   monitorOptions = {},
   openProject = null,
   openThread = null,
+  taskchefVersion = TASKCHEF_VERSION,
+  serverVersion = DASHBOARD_SERVER_VERSION,
 } = {}) {
   if (!LOOPBACK_HOSTS.has(host)) {
     throw new Error("dashboard host must be a loopback address");
@@ -414,6 +419,17 @@ export async function createDashboardServer({
   }
   const monitor = new DashboardMonitor(workspace, monitorOptions);
   await monitor.start();
+  const identity = Object.freeze({
+    schemaVersion: 1,
+    service: "taskchef-dashboard",
+    taskchefVersion,
+    serverVersion,
+    workspace: monitor.workspace,
+  });
+  if (Buffer.byteLength(`${JSON.stringify(identity)}\n`) > DASHBOARD_HEALTH_MAX_BYTES) {
+    monitor.close();
+    throw new Error("dashboard identity exceeds the health response limit");
+  }
   const clients = new Set();
   let allowedAuthority;
   let allowedOrigin;
@@ -446,6 +462,16 @@ export async function createDashboardServer({
       return;
     }
 
+    if (url.pathname === DASHBOARD_HEALTH_PATH && (method === "GET" || method === "HEAD")) {
+      if (method === "HEAD") {
+        response.writeHead(200, securityHeaders("application/json; charset=utf-8"));
+        response.end();
+      } else {
+        sendJson(response, 200, identity);
+      }
+      return;
+    }
+
     if (url.pathname === "/api/snapshot" && (method === "GET" || method === "HEAD")) {
       if (method === "HEAD") {
         response.writeHead(200, securityHeaders("application/json; charset=utf-8"));
@@ -574,6 +600,7 @@ export async function createDashboardServer({
     port: boundPort,
     origin: allowedOrigin,
     url: `${allowedOrigin}/`,
+    identity,
     monitor,
     get eventClientCount() { return clients.size; },
     async close() {

package/src/mcp.js

@@ -8,7 +8,9 @@ import {
   reportTaskResult,
 } from "./workspace.js";
 import { parseTaskChefMarker } from "./delegation.js";
+import { createDashboardManager } from "./dashboard-manager.js";
 import { resolveWorkspacePath } from "./workspace-path.js";
+import { DASHBOARD_SERVER_VERSION, TASKCHEF_VERSION } from "./version.js";
 
 const projectSchema = z.object({
   name: z.string(),
@@ -49,6 +51,14 @@ const preparationSchema = z.object({
   projects: z.array(projectSchema),
 });
 
+const dashboardSchema = z.object({
+  action: z.enum(["started", "reused"]),
+  url: z.string().url(),
+  workspace: z.string(),
+  taskchefVersion: z.string(),
+  serverVersion: z.string(),
+});
+
 function toolResult(key, value, message) {
   return {
     structuredContent: { [key]: value },
@@ -63,15 +73,53 @@ export function createTaskChefMcpServer({
   reportResult = reportTaskResult,
   reportState = reportTaskState,
   link = linkTask,
+  dashboardManager = createDashboardManager({ workspace }),
 } = {}) {
   const server = new McpServer(
-    { name: "taskchef", version: "1.0.0" },
+    { name: "taskchef", version: TASKCHEF_VERSION },
     {
       instructions:
         "Prepare with prepare_dispatch, call record_task before creating the Codex task, then create it natively and return immediately. Follow the active TaskChef skill for role-specific sequencing of the identity and state tools.",
     },
   );
 
+  const originalClose = server.close.bind(server);
+  let closePromise = null;
+  server.close = async () => {
+    closePromise ??= (async () => {
+      await dashboardManager.close();
+      await originalClose();
+    })();
+    return closePromise;
+  };
+  server.server.onclose = () => {
+    void dashboardManager.close();
+  };
+
+  server.registerTool(
+    "ensure_dashboard",
+    {
+      title: "Ensure TaskChef dashboard",
+      description:
+        "Best-effort ensure the canonical TaskChef dashboard is available on 127.0.0.1:3210. Starts one dashboard inside this MCP process or reuses only an exact compatible TaskChef dashboard for the same canonical workspace; unknown listeners are never terminated or replaced.",
+      inputSchema: {},
+      outputSchema: { dashboard: dashboardSchema },
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        openWorldHint: false,
+      },
+    },
+    async () => {
+      const dashboard = await dashboardManager.ensure();
+      return toolResult(
+        "dashboard",
+        dashboard,
+        `${dashboard.action === "started" ? "Started" : "Reused"} TaskChef dashboard ${dashboard.url}`,
+      );
+    },
+  );
+
   server.registerTool(
     "prepare_dispatch",
     {

package/src/version.js

@@ -0,0 +1,7 @@
+import { createRequire } from "node:module";
+
+const require = createRequire(import.meta.url);
+const packageMetadata = require("../package.json");
+
+export const TASKCHEF_VERSION = packageMetadata.version;
+export const DASHBOARD_SERVER_VERSION = "1";