taskchef 7.17.0 → 7.18.0

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "taskchef",
-  "version": "7.17.0",
+  "version": "7.18.0",
   "description": "Dispatch work from a data-only workspace to visible Codex project tasks.",
   "author": {
     "name": "Favo Yang",
@@ -31,7 +31,7 @@
     "defaultPrompt": [
       "$taskchef-bootstrap Set up TaskChef and index my local Codex projects.",
       "$taskchef-delegate Do X in Y project.",
-      "Start and open the TaskChef dashboard.",
+      "$taskchef-dashboard Ensure and open the TaskChef dashboard.",
       "$taskchef-copilot Summarize recent delegated work and tell me what needs attention."
     ],
     "brandColor": "#D97706",

package/README.md

@@ -31,7 +31,7 @@ codex plugin add taskchef@favoyang-plugins
 npm install --global taskchef
 ```
 
-The plugin provides four skills and a local MCP server. The npm installation
+The plugin provides five skills and a local MCP server. The npm installation
 puts the `taskchef` CLI on `PATH`. TaskChef installs no hooks, schedules,
 daemons, login items, system services, or background identity search and needs
 no elevated permissions.
@@ -48,7 +48,7 @@ The canonical workspace is `~/.agents/taskchef`. TaskChef owns only:
 
 ```text
 AGENTS.md       managed dispatcher instructions plus user additions
-taskchef.json   schema-2 Codex project index and delegation metadata
+taskchef.json   schema-2 Codex project index, dashboard preference, and delegation metadata
 tasks.jsonl     one task snapshot per line (schema 9; schema 4-8 migration supported)
 ```
 
@@ -129,9 +129,10 @@ correlation marker. That skill reads the executor's own `CODEX_THREAD_ID`, self-
 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
+Activating the TaskChef MCP process best-effort ensures the dashboard by
+default. The managed workspace instructions also retry it at the start of each
+dispatcher turn. A startup failure never blocks MCP tools, 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.
 
@@ -219,13 +220,14 @@ eight-character prefix.
 
 ## Dashboard
 
-Ask the dispatcher to make the dashboard available and open it:
+Use the packaged recovery skill to make the dashboard available and open it:
 
 ```text
-Start and open the TaskChef dashboard.
+$taskchef-dashboard Ensure and open the TaskChef dashboard.
 ```
 
-Dispatcher turns call the input-free `ensure_dashboard` MCP tool. It starts at
+MCP activation and `$taskchef-dashboard` 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
@@ -233,8 +235,22 @@ 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.
+the plugin may therefore stop the dashboard; activating the next TaskChef MCP
+process normally restores it. TaskChef adds no OS-persistent component.
+
+Autostart is enabled when `dashboard` is absent and in new workspaces. To opt
+out, add this optional exact object to `taskchef.json` while retaining its other
+fields:
+
+```json
+"dashboard": { "autostart": false }
+```
+
+The manual `$taskchef-dashboard` recovery skill remains available when
+autostart is disabled or fails. It reports whether the compatible dashboard was
+started or reused and always returns its canonical clickable URL. It may open
+the returned localhost URL in an available in-app browser, but browser failure
+does not make dashboard recovery fail.
 
 For manual development, run the foreground CLI:
 
@@ -322,6 +338,21 @@ codex plugin marketplace upgrade favoyang-plugins
 codex plugin add taskchef@favoyang-plugins
 ```
 
+Replacing or installing plugin files cannot execute autostart by itself. After
+installation, activate or reload the new TaskChef MCP process; installation
+does not necessarily reload Codex. Then run `$taskchef-dashboard` (or call
+`ensure_dashboard`) and verify the returned dashboard identity has all of:
+
+- the expected released TaskChef version;
+- the expected dashboard protocol `serverVersion`;
+- the canonical TaskChef workspace path;
+- the canonical `http://127.0.0.1:3210/` URL.
+
+The release-install sequence is therefore: install plugin, activate or reload
+the new MCP process, ensure the dashboard, then verify TaskChef version,
+protocol `serverVersion`, canonical workspace, and URL. Exact-compatible
+servers may be reused; unknown listeners remain untouched.
+
 ## Development
 
 ```sh

package/assets/taskchef-dispatcher-instructions.md

@@ -6,10 +6,8 @@ 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.
-- A request to start or open the TaskChef dashboard is TaskChef maintenance,
-  not delegated project work. Call `ensure_dashboard`, then open or navigate to
-  its returned URL when an in-app browser capability is available. Otherwise,
-  return the URL as a clickable link.
+- A request to start, recover, or open the TaskChef dashboard is TaskChef
+  maintenance, not delegated project work. Use `$taskchef-dashboard`.
 - Use `$taskchef-bootstrap` when initializing or refreshing this workspace,
   changing or listing its configured projects, running TaskChef doctor,
   or repairing its managed instructions.

package/docs/firstmate-taskchef-comparison.md

@@ -70,7 +70,7 @@ responsibility until an outcome is landed, transferred, or safely preserved.
 | Dimension | TaskChef 7 | FirstMate at `038d0f7` |
 | --- | --- | --- |
 | Primary goal | Put multi-project work into the right visible Codex task and make it findable later. | Let one person direct a supervised crew across projects through one liaison. |
-| Product form | Codex plugin: four skills, local MCP server, data CLI, and loopback dashboard. | Cloneable agent distribution: instructions, internal skills, scripts, policies, and private on-disk state. |
+| Product form | Codex plugin: five skills, local MCP server, data CLI, and loopback dashboard. | Cloneable agent distribution: instructions, internal skills, scripts, policies, and private on-disk state. |
 | Runtime | Native Codex desktop tasks are the executors and live source of truth. | Harness-driven workers in tmux by default, with documented alternative session backends; Codex can be a harness, but Codex desktop is not a runtime backend. |
 | Coordinator lifetime | Dispatcher returns immediately and does not supervise. | First mate remains active and uses watcher/guard mechanisms to supervise meaningful events. |
 | Project isolation | Delegates to the configured Codex project; isolation follows native Codex/project behavior. | Ship and scout workers require separate Treehouse- or backend-managed worktrees. |
@@ -219,7 +219,7 @@ harness adapter.
 | --- | --- | --- |
 | Codex | Built around native Codex projects, tasks, thread reads, and desktop deep links. | Codex is one verified harness; desktop tasks are not its worker runtime. |
 | GitHub | Configured repository URLs aid routing; delivery remains the executor project's concern. | GitHub CLI, PR state, and configured delivery modes are part of supervised shipping workflows. |
-| Skills | Four plugin skills with narrow bootstrap, delegate, executor, and conversational coordination responsibilities. | Internal firstmate-only skills plus standalone public skills; AGENTS.md routes conditional procedures. |
+| Skills | Five plugin skills with narrow bootstrap, dashboard recovery, delegate, executor, and conversational coordination responsibilities. | Internal firstmate-only skills plus standalone public skills; AGENTS.md routes conditional procedures. |
 | MCP | Four primary local TaskChef tools plus one deprecated compatibility alias own deterministic identity and state writes. | FirstMate describes itself as an agent distribution rather than an MCP product; deterministic behavior lives largely in scripts. |
 | Runtime extensions | Extend plugin skills/MCP/CLI/dashboard or compose native Codex capabilities. | Add or verify harness adapters, session backends, dispatch profiles, operational scripts, and optional integrations. |
 

package/docs/spec.md

@@ -29,7 +29,7 @@ is dated research, not contract.
 | **Turn reference** | Required lifecycle identity for one executor prompt. It is the native Codex turn ID when available, otherwise a retained client-generated UUID. |
 | **Current turn ID** | Optional Codex metadata for the reported prompt; null when native turn reading is unavailable. |
 | **Dashboard** | The loopback, read-only UI derived from validated workspace snapshots and bounded native actions. |
-| **Skill** | One packaged agent procedure: `taskchef-bootstrap`, `taskchef-delegate`, `taskchef-executor`, or `taskchef-copilot`. |
+| **Skill** | One packaged agent procedure: `taskchef-bootstrap`, `taskchef-dashboard`, `taskchef-delegate`, `taskchef-executor`, or `taskchef-copilot`. |
 
 ## Components and ownership
 
@@ -43,6 +43,9 @@ is dated research, not contract.
 - `taskchef-copilot` MUST own conversational outcome explanation, attention,
   and next-action recommendations. It MUST use cached normalized briefs by
   default and MUST NOT poll or persist inferred state.
+- `taskchef-dashboard` MUST own manual dashboard ensure and recovery. It MUST
+  NOT dispatch work or inspect task outcomes, and browser navigation failure
+  MUST NOT suppress the returned dashboard URL.
 - 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
@@ -56,7 +59,8 @@ is dated research, not contract.
 TaskChef MUST manage only `AGENTS.md`, `taskchef.json`, and `tasks.jsonl`
 inside the dispatcher workspace. It MUST preserve unrelated paths.
 
-`taskchef.json` MUST have schema version 2 and exactly:
+`taskchef.json` MUST have schema version 2, the following required fields, and
+an optional exact `dashboard` object:
 
 ```json
 {
@@ -71,6 +75,11 @@ Names and paths MUST be unique. Git projects MUST be exact Git roots.
 Repository URLs MUST canonicalize to `https://github.com/<owner>/<repository>`
 and be case-insensitively deduplicated.
 
+When present, `dashboard` MUST contain exactly boolean `autostart`. Its absence
+is backward-compatible and means `true`; new workspaces SHOULD write
+`{"autostart": true}`. `false` disables MCP-lifecycle autostart but MUST NOT
+disable the explicit `ensure_dashboard` tool.
+
 `tasks.jsonl` MUST contain zero or more newline-terminated schema-4 through
 schema-9 records, one per line. Schemas 4 through 8 are supported
 migration/read formats; every new record and state mutation MUST write schema 9. Other schemas
@@ -112,6 +121,14 @@ fields MUST NOT change after recording.
 
 ## Required lifecycle
 
+When the canonical TaskChef MCP server finishes connecting, it MUST invoke the
+same serialized dashboard ensure path once by default. It MUST read the
+canonical configuration and skip this only for explicit
+`dashboard.autostart: false`. Initialization failures, invalid workspace state,
+port conflicts, and dashboard errors MUST NOT prevent tool registration or MCP
+availability. They MUST emit only a bounded non-sensitive diagnostic through
+the MCP process logging channel. MCP initialization MUST NOT open a browser.
+
 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
@@ -233,6 +250,11 @@ 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.
 
+The packaged `$taskchef-dashboard` skill MUST call this tool, report `started`
+or `reused`, and return the canonical clickable URL. It MAY use an available
+in-app browser when permitted; absent or blocked browser navigation MUST fall
+back to the link without failing. It MUST NOT inspect task outcomes or dispatch.
+
 **Annotations:** `readOnlyHint: false`, `destructiveHint: false`,
 `openWorldHint: false`.
 
@@ -473,3 +495,10 @@ 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.
+
+Installing or replacing plugin files MUST NOT be described as activating the
+new MCP code. Release verification MUST install the plugin, activate or reload
+the new MCP process, ensure the dashboard, and verify the expected TaskChef
+version, dashboard protocol `serverVersion`, canonical workspace, and canonical
+URL. Exact-compatible listener reuse remains valid; installation MUST NOT be
+claimed to reload Codex automatically.

package/docs/workflows.md

@@ -13,6 +13,7 @@ research.
 | `skills/taskchef-delegate/SKILL.md` | Split, route, record-before-create, create, return. |
 | `skills/taskchef-executor/SKILL.md` | Own, self-link, execute, and report every executor turn. |
 | `skills/taskchef-bootstrap/SKILL.md` | Initialize the workspace and maintain the Codex project index. |
+| `skills/taskchef-dashboard/SKILL.md` | Ensure or recover the canonical dashboard and return its URL. |
 | `skills/taskchef-copilot/SKILL.md` | Explain normalized cached briefs and coordinate safe next actions. |
 | `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. |
@@ -27,9 +28,9 @@ 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/copilot skills.
+MCP activation makes dashboard maintenance a best-effort lifecycle action. The
+generated managed `AGENTS.md` block also retries it before dispatcher turns and
+keeps response ordering centralized instead of duplicating it across skills.
 
 ```mermaid
 sequenceDiagram
@@ -38,6 +39,8 @@ sequenceDiagram
   participant M as TaskChef MCP
   participant H as Loopback health
   participant S as Dashboard server
+  M->>M: Read dashboard.autostart (absent means true)
+  M->>M: Best-effort ensure after MCP connect
   D->>M: ensure_dashboard()
   M->>M: Serialize concurrent ensure calls
   M->>H: GET 127.0.0.1:3210/api/health
@@ -63,6 +66,27 @@ 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.
 
+Autostart and explicit ensures share the same manager promise, so concurrent
+initialization and recovery calls produce at most one owned listener. An
+explicit `dashboard.autostart: false` skips only activation-time ensure. Any
+failure is reduced to a fixed stderr diagnostic; tool registration and MCP
+availability continue. Activation never opens a browser.
+
+## Release-install verification
+
+The practical release handoff ends in this order:
+
+1. Install the released plugin.
+2. Activate or reload its new TaskChef MCP process.
+3. Run `$taskchef-dashboard` or call `ensure_dashboard`.
+4. Verify the expected TaskChef version, protocol `serverVersion`, canonical
+   workspace, and canonical URL returned by the dashboard identity.
+
+Replacing plugin files alone cannot execute autostart because old code remains
+in the already-running MCP process. Installation does not necessarily reload
+Codex. An exact-compatible dashboard may be reused; an unknown listener is
+never terminated or replaced.
+
 ## Normal delegation and self-linking
 
 The dispatcher uses native Codex project discovery for routing and MCP for

package/index.js

@@ -5,6 +5,7 @@ export {
   canonicalDirectory,
   canonicalGitRoot,
   doctorWorkspace,
+  dashboardAutostartEnabled,
   ensureWorkspaceInstructions,
   filterTasks,
   importProjects,
@@ -74,4 +75,4 @@ export {
 
 export { DASHBOARD_SERVER_VERSION, TASKCHEF_VERSION } from "./src/version.js";
 
-export { createTaskChefMcpServer } from "./src/mcp.js";
+export { createDashboardAutostart, createTaskChefMcpServer } from "./src/mcp.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "taskchef",
-  "version": "7.17.0",
+  "version": "7.18.0",
   "description": "A non-blocking interactive dispatcher for visible Codex tasks.",
   "license": "MIT",
   "author": "Favo Yang",
@@ -36,6 +36,7 @@
     "scripts/e2e-benchmark.js",
     "src",
     "skills/taskchef-bootstrap",
+    "skills/taskchef-dashboard",
     "skills/taskchef-delegate",
     "skills/taskchef-executor",
     "skills/taskchef-copilot"

package/skills/taskchef-bootstrap/SKILL.md

@@ -160,5 +160,8 @@ Example managed-workspace import entry:
 }
 ```
 
-TaskChef accepts configuration schema version 2 only. `githubRepos` is always
-an array; unsupported configuration is rejected without being rewritten.
+TaskChef accepts configuration schema version 2 only. Its optional exact
+`dashboard` object contains boolean `autostart`; absence means enabled and
+`false` opts out of MCP-lifecycle dashboard startup without disabling manual
+`$taskchef-dashboard` recovery. `githubRepos` is always an array; unsupported
+configuration is rejected without being rewritten.

package/skills/taskchef-dashboard/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: taskchef-dashboard
+description: "Ensure and recover the canonical TaskChef dashboard. Use when the user asks to start, restore, open, or get the link for the TaskChef dashboard. Do not use to dispatch work or inspect task outcomes."
+---
+
+# TaskChef Dashboard
+
+Maintain only the canonical TaskChef dashboard.
+
+1. Call the TaskChef `ensure_dashboard` MCP tool with its empty input. Do not
+   supply a workspace, host, or port.
+2. Report whether the returned `action` is `started` or `reused` and provide
+   the returned canonical URL as a clickable link.
+3. If the user asked to open the dashboard and an in-app browser navigation
+   capability is available and permits the returned localhost URL, open or
+   navigate to it. Browser absence, refusal, or blocked localhost navigation is
+   non-fatal: still return the clickable URL and the ensure result.
+
+Do not dispatch project work, read task briefs, inspect executor outcomes, poll,
+start a separate foreground CLI server, or modify TaskChef workspace files.

package/skills/taskchef-dashboard/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "TaskChef Dashboard"
+  short_description: "Start or recover the TaskChef dashboard"
+  default_prompt: "Use $taskchef-dashboard to ensure the TaskChef dashboard is available and give me its link."

package/src/dashboard/app.js

@@ -19,6 +19,7 @@ import { openTaskFromControl } from "./actions.js";
 import {
   githubReferenceAccessibleLabel,
   githubReferenceDisplayLabels,
+  groupRelatedGitHubLinks,
   referenceSegments,
 } from "./github-links.js";
 import { formatRelativeTime, RelativeTimeController, parsedTimestamp } from "./time.js";
@@ -116,26 +117,35 @@ function appendLinkedText(container, text, task) {
 }
 
 function relatedGitHubLinks(task, { compact = false } = {}) {
-  const seen = new Set();
-  const links = (task.relatedGitHubLinks ?? []).filter((link) => {
-    if (link.type === "repository" || seen.has(link.label)) return false;
-    seen.add(link.label);
-    return true;
-  });
+  const groups = groupRelatedGitHubLinks(task.relatedGitHubLinks);
+  const links = groups.flat();
   const container = document.createElement("nav");
   container.className = `github-links${compact ? " github-links-compact" : ""}`;
   container.setAttribute("aria-label", `Related GitHub links for ${task.title}`);
   const displayLabels = githubReferenceDisplayLabels(links, { related: true });
-  const children = links.map((link, index) => (
-    referenceLink(link, { compact, displayLabel: displayLabels[index] })
-  ));
+  let linkIndex = 0;
+  const children = groups.map((group) => {
+    const line = document.createElement("div");
+    line.className = "github-links-group";
+    line.replaceChildren(...group.map((link) => {
+      const anchor = referenceLink(link, {
+        compact,
+        displayLabel: displayLabels[linkIndex],
+      });
+      linkIndex += 1;
+      return anchor;
+    }));
+    return line;
+  });
   if (task.relatedGitHubLinksTruncated) {
     const more = document.createElement("span");
     more.className = "github-links-more";
     more.textContent = "+ more";
     more.title = "Additional related GitHub references are omitted from this bounded dashboard view.";
     more.setAttribute("aria-label", more.title);
-    children.push(more);
+    const finalGroup = children.at(-1);
+    if (finalGroup) finalGroup.append(more);
+    else children.push(more);
   }
   container.hidden = children.length === 0;
   container.replaceChildren(...children);

package/src/dashboard/github-links.js

@@ -52,6 +52,27 @@ export function githubReferenceDisplayLabels(links, { related = false } = {}) {
   });
 }
 
+function compareReferenceNumbers(left, right) {
+  const leftNumber = String(left.number ?? "");
+  const rightNumber = String(right.number ?? "");
+  return leftNumber.length - rightNumber.length || leftNumber.localeCompare(rightNumber);
+}
+
+export function groupRelatedGitHubLinks(links) {
+  const groups = new Map();
+  const seen = new Set();
+  for (const link of links ?? []) {
+    if (link.type === "repository" || seen.has(link.label)) continue;
+    seen.add(link.label);
+    const repository = repositoryIdentity(link);
+    if (!repository) continue;
+    const group = groups.get(repository) ?? [];
+    group.push(link);
+    groups.set(repository, group);
+  }
+  return [...groups.values()].map((group) => [...group].sort(compareReferenceNumbers));
+}
+
 export function githubReferenceAccessibleLabel(link) {
   const repository = repositoryIdentity(link);
   if (!repository) return link.label ?? link.text;

package/src/dashboard/styles.css

@@ -97,9 +97,10 @@ select { min-width: 180px; min-height: 36px; padding: 7px 32px 7px 10px; border:
 .task-title, .task-summary { overflow-wrap: anywhere; }
 .task-summary { display: grid; max-width: 82ch; margin-bottom: 12px; gap: 2px; font-size: 0.9rem; line-height: 1.45; }
 .task-summary strong { margin-top: 4px; color: var(--muted); font-size: 0.68rem; letter-spacing: 0.04em; text-transform: uppercase; }
-.github-links { display: flex; flex-wrap: wrap; gap: 7px; margin: 0 0 18px; }
+.github-links { display: grid; gap: 7px; margin: 0 0 18px; }
 .github-links[hidden] { display: none; }
 .github-links-compact { margin: -2px 0 12px; gap: 5px; }
+.github-links-group { display: flex; min-width: 0; flex-wrap: wrap; gap: inherit; }
 .github-link { color: var(--accent); font-weight: 700; text-decoration-thickness: 1px; text-underline-offset: 3px; overflow-wrap: anywhere; }
 .github-link-compact { padding: 2px 7px; border: 1px solid var(--border); border-radius: 999px; background: var(--surface-muted); font-size: 0.72rem; line-height: 1.35; text-decoration: none; }
 .github-link:hover { text-decoration-thickness: 2px; }

package/src/mcp.js

@@ -6,6 +6,8 @@ import {
   recordTask,
   reportTaskState,
   reportTaskResult,
+  dashboardAutostartEnabled,
+  readConfig,
 } from "./workspace.js";
 import { parseTaskChefMarker } from "./delegation.js";
 import { createDashboardManager } from "./dashboard-manager.js";
@@ -99,6 +101,39 @@ function toolResult(key, value, message) {
   };
 }
 
+function dashboardAutostartDiagnostic(error) {
+  const message = typeof error?.message === "string" ? error.message : "";
+  if (error?.code === "EADDRINUSE" || /port conflict|already in use/i.test(message)) {
+    return "TaskChef dashboard autostart skipped: port 127.0.0.1:3210 is unavailable; the listener was left untouched.";
+  }
+  if (/configuration|workspace|task log/i.test(message)) {
+    return "TaskChef dashboard autostart skipped: the canonical workspace is not ready.";
+  }
+  return "TaskChef dashboard autostart skipped: the dashboard could not be started.";
+}
+
+export function createDashboardAutostart({
+  workspace,
+  dashboardManager,
+  readConfiguration = readConfig,
+  log = (message) => process.stderr.write(`${message}\n`),
+} = {}) {
+  let startPromise = null;
+  return async () => {
+    startPromise ??= (async () => {
+      try {
+        const config = await readConfiguration(workspace, { checkPaths: false });
+        if (!dashboardAutostartEnabled(config)) return { action: "disabled" };
+        return await dashboardManager.ensure();
+      } catch (error) {
+        try { log(dashboardAutostartDiagnostic(error)); } catch {}
+        return { action: "failed" };
+      }
+    })();
+    return startPromise;
+  };
+}
+
 export function createTaskChefMcpServer({
   workspace = resolveWorkspacePath().workspace,
   prepare = prepareDispatch,
@@ -107,6 +142,8 @@ export function createTaskChefMcpServer({
   reportState = reportTaskState,
   link = linkTask,
   dashboardManager = createDashboardManager({ workspace }),
+  readConfiguration = readConfig,
+  logDashboardDiagnostic,
 } = {}) {
   const server = new McpServer(
     { name: "taskchef", version: TASKCHEF_VERSION },
@@ -280,5 +317,17 @@ export function createTaskChefMcpServer({
     },
   );
 
+  const originalConnect = server.connect.bind(server);
+  const autostartDashboard = createDashboardAutostart({
+    workspace,
+    dashboardManager,
+    readConfiguration,
+    ...(logDashboardDiagnostic ? { log: logDashboardDiagnostic } : {}),
+  });
+  server.connect = async (...args) => {
+    await originalConnect(...args);
+    void autostartDashboard();
+  };
+
   return server;
 }

package/src/workspace.js

@@ -43,7 +43,8 @@ const PREVIOUS_TASK_SCHEMA_VERSION = 8;
 const FIRST_TURN_HISTORY_TASK_SCHEMA_VERSION = 7;
 const LEGACY_RESULTS_TASK_SCHEMA_VERSION = 6;
 const FIRST_SELF_LINKING_TASK_SCHEMA_VERSION = 4;
-const CONFIG_FIELDS = new Set(["schemaVersion", "projects"]);
+const CONFIG_FIELDS = new Set(["schemaVersion", "projects", "dashboard"]);
+const DASHBOARD_CONFIG_FIELDS = new Set(["autostart"]);
 const PROJECT_FIELDS = new Set([
   "name",
   "path",
@@ -533,16 +534,36 @@ async function inspectProject(input, index = 0) {
 }
 
 export async function validateConfig(config, { checkPaths = true } = {}) {
-  requireExactFields(config, CONFIG_FIELDS, "taskchef.json");
+  if (!config || typeof config !== "object" || Array.isArray(config)) {
+    throw new Error("taskchef.json must be an object");
+  }
+  const unexpected = Object.keys(config).find((key) => !CONFIG_FIELDS.has(key));
+  if (unexpected) throw new Error(`taskchef.json has unsupported field: ${unexpected}`);
+  for (const required of ["schemaVersion", "projects"]) {
+    if (!(required in config)) throw new Error(`taskchef.json is missing field: ${required}`);
+  }
   if (config.schemaVersion !== CURRENT_CONFIG_SCHEMA_VERSION) {
     throw new Error("unsupported configuration schemaVersion");
   }
+  let dashboard;
+  if ("dashboard" in config) {
+    requireExactFields(config.dashboard, DASHBOARD_CONFIG_FIELDS, "taskchef.json.dashboard");
+    if (typeof config.dashboard.autostart !== "boolean") {
+      throw new Error("taskchef.json.dashboard.autostart must be a boolean");
+    }
+    dashboard = { autostart: config.dashboard.autostart };
+  }
   return {
     schemaVersion: CURRENT_CONFIG_SCHEMA_VERSION,
     projects: await normalizeProjects(config.projects, { checkPaths }),
+    ...(dashboard ? { dashboard } : {}),
   };
 }
 
+export function dashboardAutostartEnabled(config) {
+  return config?.dashboard?.autostart !== false;
+}
+
 async function ensureDispatchFile(workspaceRoot) {
   const filePath = path.join(workspaceRoot, DISPATCH_FILE_NAME);
   const exists = await managedRegularFileExists(filePath);
@@ -569,7 +590,11 @@ export async function initializeWorkspace(workspaceRoot) {
     const configExists = await managedRegularFileExists(configPath);
     const config = configExists
       ? await readConfig(root, { checkPaths: false })
-      : { schemaVersion: CURRENT_CONFIG_SCHEMA_VERSION, projects: [] };
+      : {
+        schemaVersion: CURRENT_CONFIG_SCHEMA_VERSION,
+        projects: [],
+        dashboard: { autostart: true },
+      };
     const dispatchPath = path.join(root, DISPATCH_FILE_NAME);
     if (configExists && (await managedRegularFileExists(dispatchPath))) {
       await readDispatchesUnlocked(root);
@@ -638,7 +663,7 @@ export async function addProject(workspaceRoot, input) {
     const project = await inspectProject(input);
     assertWorkspaceOutsideProject(root, project.path);
     const updated = await validateConfig({
-      schemaVersion: CURRENT_CONFIG_SCHEMA_VERSION,
+      ...config,
       projects: [...config.projects, project],
     });
     await writeJsonAtomic(path.join(root, "taskchef.json"), updated);
@@ -676,7 +701,7 @@ export async function importProjects(workspaceRoot, inputs, { replace = false }
       else projects[index] = project;
     }
     const config = await validateConfig({
-      schemaVersion: CURRENT_CONFIG_SCHEMA_VERSION,
+      ...current,
       projects,
     });
     await writeJsonAtomic(path.join(root, "taskchef.json"), config);
@@ -700,7 +725,7 @@ export async function removeProject(workspaceRoot, name) {
     const [project] = config.projects.slice(index, index + 1);
     const projects = config.projects.filter((_, projectIndex) => projectIndex !== index);
     await writeJsonAtomic(path.join(root, "taskchef.json"), {
-      schemaVersion: CURRENT_CONFIG_SCHEMA_VERSION,
+      ...config,
       projects,
     });
     return { project };