taskchef 7.2.0 → 7.4.0

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "taskchef",
-  "version": "7.2.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
 
@@ -87,17 +88,24 @@ $taskchef-delegate In payments, add structured logs for failed retries and test
 
 TaskChef prepares a UUID and marker, persists the task before native creation,
 creates the executor, and returns its task link. New executor instructions keep
-the assignment visible immediately after the marker and end with an explicit
-`$taskchef-executor` invocation. That skill 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.
+the assignment visible from the first line, then place the correlation marker
+immediately before an explicit `$taskchef-executor` invocation. That skill
+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
-<!-- taskchef_id=c0f010ff-84f2-4838-a69d-0ff1f5d721d7 -->
 Fix duplicate charges after a retry and add a regression test.
 
+<!-- taskchef_id=c0f010ff-84f2-4838-a69d-0ff1f5d721d7 -->
 Use $taskchef-executor to execute and report this delegated TaskChef assignment.
 ```
 
@@ -145,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/firstmate-taskchef-comparison.md

@@ -108,7 +108,7 @@ also insert an interpretation layer between user and worker.
 
 ### TaskChef
 
-**Fact:** `prepare_dispatch` allocates a TaskChef UUID and exact first-line
+**Fact:** `prepare_dispatch` allocates a TaskChef UUID and exact correlation
 marker. `record_task` persists the marked instruction before native task
 creation. The executor then reads its own `CODEX_THREAD_ID` and calls
 `link_task`; the dispatcher neither searches recent tasks nor repairs identity.

package/docs/spec.md

@@ -18,7 +18,7 @@ is dated research, not contract.
 | **Delegated task** | One independently useful outcome represented by one TaskChef task UUID and snapshot. |
 | **Executor** | The native Codex task created to own and perform one delegated task. |
 | **Task record** | One complete JSON object in `tasks.jsonl`; it contains immutable intent/project fields and mutable identity/result fields. |
-| **Marker** | The exact first instruction line `<!-- taskchef_id=<lowercase full UUID> -->`; new instructions begin the assignment on the next line. |
+| **Marker** | The exact correlation line `<!-- taskchef_id=<lowercase full UUID> -->`; new instructions place it after the complete assignment and immediately before the executor-skill invocation. |
 | **Record-before-create** | Persisting a link-pending task before asking Codex to create its executor. |
 | **Self-linking** | The executor's one-way registration of its own canonical Codex UUIDv7 from `CODEX_THREAD_ID`. |
 | **Link-pending** | A working task whose `threadId` is null and `updatedBy` is `dispatcher`. |
@@ -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,12 +100,20 @@ 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 returned marker as line 1, the user's
-   outcome beginning on line 2, and exactly one concise explicit
-   `$taskchef-executor` invocation at the end after one blank line. It MUST NOT
-   inline the executor protocol into a new instruction.
+3. It MUST build the instruction with the user's outcome beginning on line 1
+   and remaining uninterrupted, followed by one blank line, the returned
+   marker, and exactly one concise explicit `$taskchef-executor` invocation on
+   the final line. It MUST NOT inline the executor protocol into a new
+   instruction.
 4. It MUST call `record_task` with `threadId: null` before native creation.
 5. It MUST create exactly one native Codex executor and return immediately.
 6. The executor MUST read its own `CODEX_THREAD_ID` and call `link_task`
@@ -122,10 +130,15 @@ If native creation fails after recording, the dispatcher MUST call
 A link failure MUST remain visible and retryable; the executor MUST report it
 visibly and MUST NOT continue substantive work.
 
-Previously recorded instructions with the former blank line and inline
-executor protocol MUST remain marker-readable and executable. Their
+Previously recorded instructions with a first-line HTML marker, the older
+first-line `# taskchef_id=<full UUID>` heading, or the former blank line and
+inline executor protocol MUST remain marker-readable and executable. Their
 `report_result` calls MUST remain supported by the deprecated alias. New
-instructions MUST use the explicit executor skill contract above.
+instructions MUST use the trailing marker and explicit executor skill contract
+above. A historical first-line instruction with an executor-skill invocation
+MUST contain exactly one invocation as its final line. A former inline-protocol
+instruction MUST retain non-whitespace task-specific content beyond its known
+lifecycle paragraphs.
 
 `needs_input` MUST mean a semantic user decision or missing fact. A native
 approval prompt MUST remain live Codex state and MUST NOT be stored as
@@ -138,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.
@@ -176,7 +226,7 @@ new preparation values, though it writes no state.
 | `id` | Non-empty string; MUST equal the instruction marker. |
 | `project` | Non-empty configured project path. |
 | `title` | Non-empty string. |
-| `instruction` | Non-empty string beginning with the exact marker and at least one following instruction line. |
+| `instruction` | Non-empty string containing exactly one accepted marker and a non-empty assignment. New instructions use the required trailing marker and executor-invocation scaffold; historical first-line forms remain accepted. |
 | `threadId` | Literal null. |
 
 **Structured output:** `{ task: Task }`.
@@ -253,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.
@@ -273,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
@@ -68,10 +107,11 @@ Record-before-create makes native creation failure observable. Executor
 self-linking removes dispatcher-side polling, task search, title matching, and
 parent/child identity inference.
 
-The generated task body begins immediately after the first-line marker and
-ends with one explicit `$taskchef-executor` invocation. Older recorded tasks
-whose marker is followed by a blank line and inline protocol remain readable;
-the deprecated `report_result` alias preserves their semantic callbacks.
+The generated task begins with the complete assignment, then places its marker
+immediately before one explicit `$taskchef-executor` invocation. Older
+recorded tasks with first-line HTML or heading markers and former inline
+protocol remain readable; the deprecated `report_result` alias preserves their
+semantic callbacks.
 
 ## State reporting
 
@@ -234,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.2.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/skills/taskchef-delegate/SKILL.md

@@ -10,11 +10,18 @@ and return immediately.
 
 ## Invocation boundary
 
-A task whose initial structured `codexDelegation.input` starts with an exact
-`<!-- taskchef_id=<full UUID> -->` marker already owns that delegated
-assignment. Execute it in the current task. Do not re-dispatch it merely
-because it concerns TaskChef or a configured project. Explicit requests to
-delegate separate work remain valid.
+A task whose initial structured `codexDelegation.input` contains either the
+exact new trailing TaskChef marker plus final `$taskchef-executor` invocation,
+an exact first-line HTML marker, or the historical first-line
+`# taskchef_id=<full UUID>` heading already owns that delegated assignment.
+This includes former inline-protocol tasks that lack the skill invocation.
+An owned instruction must have exactly one accepted marker and a non-whitespace
+task-specific assignment. If it contains an executor-skill invocation, require
+exactly one as the final line. Marker-only, duplicate-marker, scaffold-only, or
+misplaced-invocation inputs are not valid delegated tasks. Execute a valid one
+in the current task. Do not re-dispatch it merely because it concerns TaskChef
+or a configured project. Explicit requests to delegate separate work remain
+valid.
 
 Use the bundled `prepare_dispatch`, `record_task`, and `report_state` MCP tools
 directly. Never fall back to shell writes. If a required tool is unavailable,
@@ -43,11 +50,13 @@ stop and report that the TaskChef plugin must be reloaded or installed.
    match and an exact native-project path. Ask instead of guessing.
 4. Build each executor instruction in this exact shape:
 
-   - Keep the preparation's exact marker as the first line.
-   - Begin the actual assignment on the second line, with no blank line after
-     the marker.
-   - End the instruction after one blank line with exactly:
+   - Begin with the actual assignment on the first line and keep its complete
+     body uninterrupted.
+   - After the assignment, add one blank line and the preparation's exact
+     marker on its own line.
+   - Immediately after the marker, end the instruction with exactly:
      `Use $taskchef-executor to execute and report this delegated TaskChef assignment.`
+   - Include exactly one marker and exactly one executor-skill invocation.
    - Do not inline executor ownership, identity, linking, or result-reporting
      protocol. The explicitly invoked executor skill owns those mechanics.
 

package/skills/taskchef-executor/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: taskchef-executor
-description: "Execute an assignment whose first instruction line is an exact TaskChef task marker, including executor ownership, self-linking, per-turn lifecycle reporting, identity safety, and final semantic state. Use when explicitly invoked by a delegated TaskChef instruction or when resuming that same executor task. Do not use to dispatch work or report on other TaskChef tasks."
+description: "Execute an assignment carrying either the new exact TaskChef marker-plus-invocation scaffold or an accepted historical first-line TaskChef marker or inline protocol. Includes executor ownership, self-linking, per-turn lifecycle reporting, identity safety, and final semantic state. Use when explicitly invoked by a new delegated instruction or when resuming the same new or historical executor task. Do not use to dispatch work or report on other TaskChef tasks."
 ---
 
 # TaskChef Executor
@@ -9,10 +9,12 @@ Own and execute the delegated assignment in the current Codex task. Do not
 re-dispatch it merely because it concerns TaskChef or a configured project.
 Explicit requests to delegate separate work remain valid.
 
-The instruction's exact first line is
-`<!-- taskchef_id=<full UUID> -->`. Treat that UUID as the TaskChef task ID.
-The assignment is the remaining instruction body; the final explicit skill
-invocation is lifecycle scaffolding, not part of the requested deliverable.
+New instructions present the complete assignment first, followed by one blank
+line, the exact `<!-- taskchef_id=<full UUID> -->` marker, and the final
+explicit skill invocation. Treat that UUID as the TaskChef task ID. The
+assignment is everything before the blank line that precedes the marker; the
+marker and invocation are lifecycle scaffolding, not part of the deliverable.
+Require exactly one marker and do not infer an ID from similar prose.
 
 ## Start every execution turn
 
@@ -66,4 +68,12 @@ Existing delegated tasks may include the former inline ownership, linking, and
 re-dispatching. Prefer `report_state` when available. If an older installed
 TaskChef exposes only `report_result`, follow its inline protocol; after an
 upgrade, the deprecated `report_result` alias remains available for exact
-legacy retries.
+legacy retries. Also accept historical instructions whose exact HTML marker is
+the first line, with or without the former blank line, and the older exact
+first-line `# taskchef_id=<full UUID>` heading. These compatibility forms do
+not change the identity or lifecycle rules above. For either first-line form,
+the assignment follows the marker. Ignore the final executor invocation and
+any recognizable former inline ownership, linking, working-state, or
+result-reporting paragraphs as lifecycle scaffolding; execute the remaining
+task-specific body. Require non-whitespace task-specific content and never
+treat an invocation by itself as an assignment.

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/delegation.js

@@ -9,11 +9,34 @@ export const EXECUTOR_WORKING_PARAGRAPH = "After a successful initial link, and
 /** @deprecated Historical v7 inline-prompt snapshot. New delegations use taskchef-executor. */
 export const EXECUTOR_RESULT_PARAGRAPH = "Before ending, read this exact Codex thread again and call TaskChef report_state for the same current working turn with status completed, needs_input, or failed and a concise summary. Use needs_input only for a semantic decision or information the user must provide; a native approval prompt is live Codex state, not a TaskChef result. Do not include secrets, transcripts, or raw command output.";
 export const EXECUTOR_SKILL_INVOCATION = "Use $taskchef-executor to execute and report this delegated TaskChef assignment.";
+const HISTORICAL_RESULT_WITH_TURN_PARAGRAPH = "Before ending, call the TaskChef report_result MCP tool with the marked task ID, this executor's self-linked thread ID, the current turn ID from an exact native read of that same thread, completed, needs_input, or failed, and a concise summary. Never reuse a prior turn ID after a follow-up. Use needs_input only for a semantic decision or information the user must provide; a native approval prompt is live Codex state, not a TaskChef result. Do not include secrets, transcripts, or raw command output.";
+const HISTORICAL_RESULT_PARAGRAPH = "Before ending, call the TaskChef report_result MCP tool with completed, needs_input, or failed and a concise summary. Use needs_input only for a semantic decision or information the user must provide; a native approval prompt is live Codex state, not a TaskChef result. Do not include secrets, transcripts, or raw command output.";
+const HISTORICAL_EXECUTOR_SCAFFOLD_LINES = new Set([
+  EXECUTOR_OWNERSHIP_PARAGRAPH,
+  EXECUTOR_LINK_PARAGRAPH,
+  EXECUTOR_WORKING_PARAGRAPH,
+  EXECUTOR_RESULT_PARAGRAPH,
+  HISTORICAL_RESULT_WITH_TURN_PARAGRAPH,
+  HISTORICAL_RESULT_PARAGRAPH,
+]);
+const HISTORICAL_INLINE_PROTOCOLS = [
+  [EXECUTOR_OWNERSHIP_PARAGRAPH, EXECUTOR_LINK_PARAGRAPH, EXECUTOR_WORKING_PARAGRAPH, EXECUTOR_RESULT_PARAGRAPH],
+  [EXECUTOR_OWNERSHIP_PARAGRAPH, EXECUTOR_LINK_PARAGRAPH, HISTORICAL_RESULT_WITH_TURN_PARAGRAPH],
+  [EXECUTOR_OWNERSHIP_PARAGRAPH, HISTORICAL_RESULT_PARAGRAPH],
+  [EXECUTOR_OWNERSHIP_PARAGRAPH],
+];
+
+function hasTaskSpecificContent(lines) {
+  return lines.some((line) => (
+    line.trim().length > 0 && !HISTORICAL_EXECUTOR_SCAFFOLD_LINES.has(line)
+  ));
+}
 
 const UUID_SOURCE = "[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}";
 const UUID_PATTERN = new RegExp(`^${UUID_SOURCE}$`);
 const CODEX_UUID_V7_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
 const TASKCHEF_MARKER_PATTERN = new RegExp(`^<!-- taskchef_id=(${UUID_SOURCE}) -->$`);
+const LEGACY_TASKCHEF_MARKER_PATTERN = new RegExp(`^# taskchef_id=(${UUID_SOURCE})$`);
 
 function requireObject(value, name) {
   if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`${name} must be an object`);
@@ -89,10 +112,66 @@ export function taskChefMarker(taskId) {
 
 export function parseTaskChefMarker(instruction) {
   if (typeof instruction !== "string") return null;
-  const firstLine = instruction.split(/\r?\n/, 1)[0];
-  const currentMatch = firstLine.match(TASKCHEF_MARKER_PATTERN);
-  if (currentMatch === null) return null;
-  return /^[^\r\n]*\r?\n[\s\S]+$/.test(instruction) ? currentMatch[1] : null;
+  const lines = instruction.split(/\r\n|\r|\n/);
+  const hasHistoricalAssignment = () => {
+    const rest = lines.slice(1);
+    const executorSkillInvocationIndices = rest.flatMap((line, index) => (
+      line === EXECUTOR_SKILL_INVOCATION ? [index] : []
+    ));
+    if (executorSkillInvocationIndices.length > 0) {
+      const bodyLines = rest.slice(0, -2);
+      return executorSkillInvocationIndices.length === 1
+        && executorSkillInvocationIndices[0] === rest.length - 1
+        && lines.at(-1) === EXECUTOR_SKILL_INVOCATION
+        && lines.at(-2) === ""
+        && bodyLines.length > 0
+        && bodyLines[0].trim().length > 0
+        && bodyLines.at(-1).trim().length > 0
+        && hasTaskSpecificContent(bodyLines)
+        && !bodyLines.some((line) => HISTORICAL_EXECUTOR_SCAFFOLD_LINES.has(line));
+    }
+
+    const containsInlineScaffold = rest.some((line) => HISTORICAL_EXECUTOR_SCAFFOLD_LINES.has(line));
+    if (!containsInlineScaffold) return rest.join("\n").trim().length > 0;
+    return HISTORICAL_INLINE_PROTOCOLS.some((protocol) => {
+      const prefix = ["", ...protocol.flatMap((line) => [line, ""])];
+      if (!prefix.every((line, index) => rest[index] === line)) return false;
+      const bodyLines = rest.slice(prefix.length);
+      return hasTaskSpecificContent(bodyLines)
+        && !bodyLines.some((line) => HISTORICAL_EXECUTOR_SCAFFOLD_LINES.has(line));
+    });
+  };
+  const currentMatches = lines.flatMap((line, index) => {
+    const match = line.match(TASKCHEF_MARKER_PATTERN);
+    return match === null ? [] : [{ id: match[1], index }];
+  });
+  const legacyMatches = lines.flatMap((line, index) => {
+    const match = line.match(LEGACY_TASKCHEF_MARKER_PATTERN);
+    return match === null ? [] : [{ id: match[1], index }];
+  });
+  if (currentMatches.length + legacyMatches.length !== 1) return null;
+
+  if (legacyMatches.length === 1) {
+    const [{ id, index }] = legacyMatches;
+    if (index !== 0) return null;
+    return hasHistoricalAssignment() ? id : null;
+  }
+
+  const [{ id, index }] = currentMatches;
+  if (index === 0) {
+    return hasHistoricalAssignment() ? id : null;
+  }
+  const executorSkillReferences = instruction.match(/\$taskchef-executor\b/gi) ?? [];
+  const isTrailingScaffold = index === lines.length - 2
+    && index >= 2
+    && lines[0].trim().length > 0
+    && lines.at(-3) === ""
+    && lines.at(-4).trim().length > 0
+    && lines.at(-1) === EXECUTOR_SKILL_INVOCATION
+    && hasTaskSpecificContent(lines.slice(0, index - 1))
+    && !lines.slice(0, index - 1).some((line) => HISTORICAL_EXECUTOR_SCAFFOLD_LINES.has(line))
+    && executorSkillReferences.length === 1;
+  return isTrailingScaffold ? id : null;
 }
 
 export function prepareDelegation(instruction, { taskId = randomUUID() } = {}) {
@@ -101,14 +180,25 @@ export function prepareDelegation(instruction, { taskId = randomUUID() } = {}) {
     throw new Error("instruction must begin with useful task content on its first line");
   }
   const body = rawBody.replace(/(?:(?:\r\n|\r|\n)[^\S\r\n]*)+$/, "");
-  if (parseTaskChefMarker(body) !== null) throw new Error("instruction already contains a TaskChef marker");
+  if (body.split(/\r\n|\r|\n/).some((line) => (
+    TASKCHEF_MARKER_PATTERN.test(line) || LEGACY_TASKCHEF_MARKER_PATTERN.test(line)
+  ))) {
+    throw new Error("instruction already contains a TaskChef marker");
+  }
   if (/\$taskchef-executor\b/i.test(body)) {
     throw new Error("instruction contains a reserved TaskChef executor skill reference");
   }
+  const bodyLines = body.split(/\r\n|\r|\n/);
+  if (!hasTaskSpecificContent(bodyLines)) {
+    throw new Error("instruction must contain task-specific content, not only TaskChef lifecycle scaffolding");
+  }
+  if (bodyLines.some((line) => HISTORICAL_EXECUTOR_SCAFFOLD_LINES.has(line))) {
+    throw new Error("instruction contains reserved historical TaskChef lifecycle scaffolding");
+  }
   const id = requireUuid(taskId);
   return {
     id,
-    instruction: `${taskChefMarker(id)}\n${body}\n\n${EXECUTOR_SKILL_INVOCATION}`,
+    instruction: `${body}\n\n${taskChefMarker(id)}\n${EXECUTOR_SKILL_INVOCATION}`,
   };
 }
 

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",
     {
@@ -114,7 +162,7 @@ export function createTaskChefMcpServer({
     },
     async (input) => {
       if (parseTaskChefMarker(input.instruction) !== input.id) {
-        throw new Error("record_task instruction must start with its exact TaskChef marker");
+        throw new Error("record_task instruction must contain its exact TaskChef marker in an accepted scaffold");
       }
       const task = await record(workspace, input);
       return toolResult("task", task, `Recorded TaskChef task ${task.id}.`);

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";

package/src/workspace.js

@@ -737,7 +737,7 @@ async function validateDispatchShape(dispatch, name = "task") {
     id,
     project,
     title: requireString(dispatch.title, `${name}.title`).trim(),
-    instruction: requireString(dispatch.instruction, `${name}.instruction`).trim(),
+    instruction: requireString(dispatch.instruction, `${name}.instruction`),
     threadId: dispatch.threadId === null
       ? null
       : normalizeDurableThreadId(dispatch.threadId, `${name}.threadId`),