taskchef 7.22.0 → 7.22.2

package/.codex-plugin/plugin.json

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

package/README.md

@@ -241,9 +241,27 @@ 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; activating the next TaskChef MCP
-process normally restores it. TaskChef adds no OS-persistent component.
+The in-process dashboard closes on MCP transport close, stdin EOF, SIGINT,
+SIGTERM, or detected loss of the MCP process's original parent. Activating a
+newer TaskChef MCP can also retire an older compatible MCP-owned dashboard for
+the same canonical workspace through an authenticated loopback handoff. These
+guards reduce unnecessary orphans but do not claim that Codex supplies a
+restart or child-process cleanup guarantee. TaskChef adds no daemon or other
+OS-persistent component, and dashboard availability remains best-effort while
+Codex is closed.
+
+Authenticated handoff requires the older listener to use the same dashboard
+protocol and to have written TaskChef's private mode-0600 ownership record in
+that canonical workspace. A nonce-bound HMAC challenge proves the listener has
+the matching secret before TaskChef sends a separately authenticated graceful
+shutdown request. The secret is never returned by `/api/health`, sent in a
+request, or logged. Standalone, different-workspace, newer, malformed,
+unverified, and spoofed listeners are left untouched. Versions predating this
+protocol cannot be taken over safely and may require one final manual cleanup.
+The ownership record is durable metadata: shutdown retains it, and the next
+MCP owner atomically replaces it after binding. This avoids both a live
+credentialless retirement window and an old process deleting its replacement's
+proof.
 
 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
@@ -403,6 +421,15 @@ protocol `serverVersion`, `mcp` launcher, canonical workspace, and URL.
 Exact-compatible MCP servers may be reused; standalone and unknown listeners
 remain untouched.
 
+If autostart reports a **verified older TaskChef** listener, the port occupant
+passed the bounded TaskChef identity check but could not complete authenticated
+handoff. For a release older than the ownership protocol, stop that one known
+legacy MCP process once through the application/session that launched it, then
+activate the installed plugin again. Do not kill an arbitrary port owner. A
+listener from a handoff-capable prior release should retire automatically; if
+it does not, retain it for diagnosis because TaskChef deliberately refuses to
+weaken the ownership proof.
+
 ## Development
 
 ```sh

package/docs/spec.md

@@ -272,7 +272,10 @@ 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.
+HTTP server. The first owned start writes a private dashboard ownership record
+in the canonical workspace. The record remains after shutdown and the next
+owner atomically replaces it before reporting startup success.
+Exact-compatible reuse does not write it.
 
 **Input:** empty object.
 
@@ -298,13 +301,42 @@ 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, canonical workspace, and `mcp` launcher identity. A standalone,
-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. This keeps dashboard child
-operations in the MCP host environment and prevents an agent-shell or foreground
-CLI dashboard from being mistaken for the canonical MCP-owned runtime.
+version, canonical workspace, and `mcp` launcher identity. Exact-compatible
+reuse MUST remain non-destructive and MUST NOT require ownership metadata. A
+manager that reuses another same-version MCP listener MUST monitor that listener
+for the remainder of its own lifetime and perform ordinary singleton startup if
+the reused owner exits, so overlapping plugin reloads converge on the surviving
+MCP process without signaling or terminating either process. A temporary
+different or unknown occupant remains untouched and does not disable that
+non-destructive availability monitor.
+
+An older TaskChef version MAY be retired only when all of these facts hold: its
+health identity is exact and reports the same canonical workspace, `mcp`
+launcher, and dashboard-server version; its semantic version is older than the
+requesting TaskChef version; a private regular mode-0600 owner record in that
+same workspace exactly matches the listener; and a fresh nonce-bound HMAC
+challenge proves control of that record's secret. Only after that proof MAY the
+new process send a separately nonce-bound authenticated loopback shutdown
+request. Shutdown nonces MUST be single-use. The secret MUST NOT appear in
+health responses, requests, diagnostics, or logs. Shutdown MUST retain the
+durable owner record so retirement cannot expose a credentialless live-listener
+window or delete a replacement's record. An owner accepting handoff MUST retire its in-memory dashboard manager
+so later tool calls cannot restart the older listener. Concurrent handoffs MUST
+converge on one listener and exact-compatible reuse.
+
+A standalone, unknown, malformed, different-workspace, newer, incompatible,
+unproven, spoofed, or legacy listener without valid ownership metadata MUST
+produce a concise actionable conflict and MUST NOT receive a shutdown request,
+signal, or process-level termination attempt. TaskChef MUST NOT discover or
+kill port owners. A startup or owner-record-write failure MUST leave no owned
+listener. The MCP server MUST close its owned dashboard on explicit MCP close,
+transport close, stdin EOF, SIGINT, SIGTERM, or detected replacement of its
+original parent process. Parent-loss detection is a local best-effort guard,
+not a Codex restart guarantee. Signal and parent-loss shutdown MUST bound the
+wait for an in-flight transport startup before closing the MCP server, so a
+never-settling startup cannot retain the dashboard indefinitely. This keeps dashboard child operations in the MCP
+host environment and prevents an agent-shell or foreground CLI dashboard from
+being mistaken for the canonical MCP-owned runtime.
 
 The packaged `$taskchef-dashboard` skill MUST call this tool, report `started`
 or `reused`, and return the canonical clickable URL. It MAY use an available
@@ -603,6 +635,12 @@ 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.
 
+Releases predating authenticated dashboard handoff are legacy listeners. A
+verified legacy listener MUST be reported distinctly from an unknown port
+conflict but MUST remain untouched; one final manual cleanup MAY be required
+when upgrading from such a release. Once both sides implement the same control
+protocol, compatible prior-version handoff is automatic.
+
 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

package/mcp/server.js

@@ -1,19 +1,5 @@
 #!/usr/bin/env node
 
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { createTaskChefMcpServer } from "../src/mcp.js";
+import { runTaskChefMcpProcess } from "../src/mcp-process.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);
+await runTaskChefMcpProcess();

package/package.json

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

package/src/dashboard/actions.js

@@ -20,7 +20,7 @@ export async function archiveTaskFromControl(event, task, {
   confirmAction = globalThis.confirm,
   fetchAction = globalThis.fetch,
   onArchived = () => {},
-  showMessage,
+  showUpdate,
 } = {}) {
   event.stopPropagation();
   const accepted = confirmAction(
@@ -39,15 +39,15 @@ export async function archiveTaskFromControl(event, task, {
     );
     const result = await response.json();
     if (!response.ok) {
-      showMessage(result.message ?? "Codex could not archive this chat.");
+      showUpdate(result.message ?? "Codex could not archive this chat.", { failed: true });
       return false;
     }
     onArchived(task.threadId);
     archived = true;
-    showMessage(result.message ?? "Archived the Codex chat. TaskChef history remains available.");
+    showUpdate(result.message ?? "Archived the Codex chat. TaskChef history remains available.");
     return true;
   } catch {
-    showMessage("Codex chat archiving is temporarily unavailable. Try again.");
+    showUpdate("Codex chat archiving is temporarily unavailable. Try again.", { failed: true });
     return false;
   } finally {
     if (!archived) control.disabled = false;

package/src/dashboard/app.js

@@ -1,4 +1,5 @@
 import {
+  MAX_NOTIFICATIONS,
   canArchiveTask,
   canManuallyTransitionTask,
   clearNotifications,
@@ -55,6 +56,7 @@ let dateRefreshTimer = null;
 let detailRequestGeneration = 0;
 let copyTaskIdGeneration = 0;
 let copyTaskIdTimer = null;
+let archiveUpdateSerial = 0;
 const relativeTimes = new RelativeTimeController();
 
 const elements = {
@@ -362,6 +364,22 @@ function renderNotifications(additions = []) {
   }
 }
 
+export function showArchiveUpdate(task, message, { failed = false } = {}) {
+  const notification = Object.freeze({
+    id: `archive:${task.id}:${Date.now()}:${archiveUpdateSerial += 1}`,
+    taskId: task.id,
+    title: task.title,
+    status: task.status,
+    event: failed ? "archive_failed" : "archive_succeeded",
+    turnRef: null,
+    turnId: null,
+    timestamp: new Date().toISOString(),
+    summary: message,
+  });
+  state.notifications = [notification, ...state.notifications].slice(0, MAX_NOTIFICATIONS);
+  renderNotifications([notification]);
+}
+
 function detailRow(term, value) {
   const dt = document.createElement("dt");
   dt.textContent = term;
@@ -597,7 +615,6 @@ async function submitManualTransition(targetStatus, event) {
     if (current === result.task) replaceCurrentTask(result.task);
     renderDialog(current);
     render();
-    showMessage(result.task.summary);
     elements.dialogTitle.focus?.();
     return;
   }
@@ -959,7 +976,7 @@ elements.archiveTask.addEventListener("click", async (event) => {
   try {
     await archiveTaskFromControl(event, task, {
       onArchived: (threadId) => state.archivedThreadIds.add(threadId),
-      showMessage,
+      showUpdate: (message, options) => showArchiveUpdate(task, message, options),
     });
   } finally {
     state.archivePendingThreadIds.delete(task.threadId);

package/src/dashboard/state.js

@@ -30,6 +30,8 @@ const NOTIFICATION_TITLES = new Map([
   ["failed", "Task failed"],
   ["manual_completed", "Task manually completed"],
   ["manual_failed", "Task manually failed"],
+  ["archive_succeeded", "Chat archived"],
+  ["archive_failed", "Chat archive failed"],
   ["unresolved", "Task updated"],
 ]);
 

package/src/dashboard-manager.js

@@ -8,11 +8,23 @@ import {
   createDashboardServer,
   dashboardAuthority,
 } from "./dashboard.js";
+import {
+  DASHBOARD_CONTROL_CHALLENGE_PATH,
+  DASHBOARD_CONTROL_SHUTDOWN_PATH,
+  createDashboardControlNonce,
+  createDashboardControlSecret,
+  dashboardControlProof,
+  dashboardOwnerMetadata,
+  readDashboardOwner,
+  verifyDashboardControlProof,
+  writeDashboardOwner,
+} from "./dashboard-ownership.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;
+const REUSE_MONITOR_INTERVAL_MS = 250;
 
 function expectedIdentity(workspace, taskchefVersion, serverVersion, launcher) {
   return {
@@ -34,11 +46,109 @@ function isExactIdentity(value, expected) {
     && expectedKeys.every((key) => value[key] === expected[key]);
 }
 
-function listenerConflict(url, detail) {
-  return new Error(
+function listenerConflict(url, detail, {
+  staleTaskchefVersion,
+  handoffRaceEligible = false,
+  retryAuthentication = false,
+} = {}) {
+  const error = 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.",
   );
+  error.code = "TASKCHEF_DASHBOARD_CONFLICT";
+  if (staleTaskchefVersion) error.staleTaskchefVersion = staleTaskchefVersion;
+  if (handoffRaceEligible) error.handoffRaceEligible = true;
+  if (retryAuthentication) error.retryAuthentication = true;
+  return error;
+}
+
+export function priorCompatibleVersion(candidate, current) {
+  const parse = (value) => {
+    const match = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/.exec(value);
+    if (!match) return null;
+    const prerelease = match[4]?.split(".") ?? null;
+    if (prerelease?.some((identifier) => /^\d+$/.test(identifier)
+        && identifier.length > 1 && identifier.startsWith("0"))) return null;
+    return { core: match.slice(1, 4).map(BigInt), prerelease };
+  };
+  const left = parse(candidate);
+  const right = parse(current);
+  if (!left || !right) return false;
+  for (let index = 0; index < left.core.length; index += 1) {
+    if (left.core[index] !== right.core[index]) return left.core[index] < right.core[index];
+  }
+  if (left.prerelease === null || right.prerelease === null) {
+    return left.prerelease !== null && right.prerelease === null;
+  }
+  const length = Math.max(left.prerelease.length, right.prerelease.length);
+  for (let index = 0; index < length; index += 1) {
+    const leftPart = left.prerelease[index];
+    const rightPart = right.prerelease[index];
+    if (leftPart === undefined || rightPart === undefined) return leftPart === undefined;
+    if (leftPart === rightPart) continue;
+    const leftNumeric = /^\d+$/.test(leftPart);
+    const rightNumeric = /^\d+$/.test(rightPart);
+    if (leftNumeric && rightNumeric) return BigInt(leftPart) < BigInt(rightPart);
+    if (leftNumeric !== rightNumeric) return leftNumeric;
+    return leftPart < rightPart;
+  }
+  return false;
+}
+
+function publicOwnerIdentity(owner) {
+  return {
+    schemaVersion: 1,
+    service: "taskchef-dashboard",
+    taskchefVersion: owner.taskchefVersion,
+    serverVersion: owner.serverVersion,
+    workspace: owner.workspace,
+    launcher: owner.launcher,
+  };
+}
+
+function requestDashboardJson({ host, port, path: requestPath, method = "GET", body, timeoutMs }) {
+  return new Promise((resolve, reject) => {
+    const encoded = body === undefined ? null : Buffer.from(JSON.stringify(body));
+    const request = http.request({
+      host,
+      port,
+      path: requestPath,
+      method,
+      headers: {
+        Accept: "application/json",
+        Host: dashboardAuthority(host, port),
+        ...(encoded ? {
+          "Content-Type": "application/json",
+          "Content-Length": encoded.length,
+        } : {}),
+      },
+    }, (response) => {
+      const chunks = [];
+      let total = 0;
+      response.on("data", (chunk) => {
+        total += chunk.length;
+        if (total > DASHBOARD_HEALTH_MAX_BYTES) request.destroy(
+          new Error("dashboard control response exceeds the identity limit"),
+        );
+        else chunks.push(chunk);
+      });
+      response.on("end", () => {
+        let value;
+        try { value = JSON.parse(Buffer.concat(chunks, total).toString("utf8")); } catch {
+          reject(new Error("dashboard control returned invalid JSON"));
+          return;
+        }
+        resolve({ statusCode: response.statusCode, value });
+      });
+    });
+    const deadline = setTimeout(() => request.destroy(
+      new Error("dashboard control request timed out"),
+    ), timeoutMs);
+    request.on("close", () => clearTimeout(deadline));
+    request.on("error", reject);
+    if (encoded) request.write(encoded);
+    request.end();
+  });
 }
 
 export function readDashboardIdentity({
@@ -111,11 +221,30 @@ export function createDashboardManager({
   launcher = "mcp",
   createServer = createDashboardServer,
   readIdentity = readDashboardIdentity,
+  readOwner = readDashboardOwner,
+  writeOwner = writeDashboardOwner,
+  reuseMonitorIntervalMs = REUSE_MONITOR_INTERVAL_MS,
 } = {}) {
   let canonicalWorkspace;
   let ownedServer = null;
+  let ownedSecret = null;
   let ensurePromise = null;
   let closePromise = null;
+  let reuseMonitor = null;
+  let reuseRecovery = null;
+  let retired = false;
+
+  const stopReuseMonitor = () => {
+    if (reuseMonitor) clearInterval(reuseMonitor);
+    reuseMonitor = null;
+  };
+
+  const closeOwned = async () => {
+    const server = ownedServer;
+    ownedServer = null;
+    ownedSecret = null;
+    await server?.close();
+  };
 
   const publicResult = (action) => ({
     action,
@@ -126,6 +255,97 @@ export function createDashboardManager({
     serverVersion,
   });
 
+  const authenticatePriorOwner = async (identity) => {
+    let owner;
+    try {
+      owner = await readOwner(canonicalWorkspace);
+    } catch (error) {
+      throw listenerConflict(
+        `http://${dashboardAuthority(host, port)}/`,
+        `is a verified older TaskChef ${identity.taskchefVersion} listener without usable authenticated handoff metadata.`,
+        {
+          staleTaskchefVersion: identity.taskchefVersion,
+          handoffRaceEligible: error?.code === "ENOENT",
+          retryAuthentication: error?.code === "ENOENT",
+        },
+      );
+    }
+    if (owner.host !== host || owner.port !== port
+        || !isExactIdentity(identity, publicOwnerIdentity(owner))) {
+      throw listenerConflict(
+        `http://${dashboardAuthority(host, port)}/`,
+        "has ownership metadata that does not exactly match the listener identity.",
+        { staleTaskchefVersion: identity.taskchefVersion },
+      );
+    }
+    const challengeNonce = createDashboardControlNonce();
+    const challenge = await requestDashboardJson({
+      host,
+      port,
+      path: `${DASHBOARD_CONTROL_CHALLENGE_PATH}?nonce=${challengeNonce}`,
+      timeoutMs: HEALTH_TIMEOUT_MS,
+    }).catch(() => null);
+    if (challenge?.statusCode !== 200
+        || challenge.value?.schemaVersion !== 1
+        || challenge.value?.nonce !== challengeNonce
+        || !verifyDashboardControlProof(
+          owner.secret, "challenge", challengeNonce, challenge.value?.proof,
+        )) {
+      throw listenerConflict(
+        `http://${dashboardAuthority(host, port)}/`,
+        "did not prove control of its private TaskChef ownership credential.",
+        {
+          staleTaskchefVersion: identity.taskchefVersion,
+          handoffRaceEligible: challenge === null,
+        },
+      );
+    }
+    return owner;
+  };
+
+  const retirePriorOwner = async (identity) => {
+    const owner = await authenticatePriorOwner(identity);
+    const shutdownNonce = createDashboardControlNonce();
+    const shutdown = await requestDashboardJson({
+      host,
+      port,
+      path: DASHBOARD_CONTROL_SHUTDOWN_PATH,
+      method: "POST",
+      body: {
+        nonce: shutdownNonce,
+        proof: dashboardControlProof(owner.secret, "shutdown", shutdownNonce),
+      },
+      timeoutMs: HEALTH_TIMEOUT_MS,
+    }).catch(() => null);
+    if (shutdown?.statusCode !== 202 || shutdown.value?.accepted !== true) {
+      throw listenerConflict(
+        `http://${dashboardAuthority(host, port)}/`,
+        "refused authenticated TaskChef version handoff.",
+        {
+          staleTaskchefVersion: identity.taskchefVersion,
+          handoffRaceEligible: shutdown === null || shutdown?.statusCode === 409,
+        },
+      );
+    }
+    for (let attempt = 0; attempt < 40; attempt += 1) {
+      try {
+        await readIdentity({ host, port, timeoutMs: 100 });
+      } catch (error) {
+        if (listenerAbsent(error) || error?.code === "ECONNRESET") return;
+      }
+      await new Promise((resolve) => setTimeout(resolve, 25));
+    }
+    throw listenerConflict(
+      `http://${dashboardAuthority(host, port)}/`,
+      "accepted authenticated handoff but did not release the listener.",
+      {
+        staleTaskchefVersion: identity.taskchefVersion,
+        handoffRaceEligible: true,
+        retryAuthentication: true,
+      },
+    );
+  };
+
   const probe = async () => {
     const url = `http://${dashboardAuthority(host, port)}/`;
     let identity;
@@ -136,6 +356,43 @@ export function createDashboardManager({
       throw listenerConflict(url, `is occupied but did not return a compatible identity (${error.message}).`);
     }
     const expected = expectedIdentity(canonicalWorkspace, taskchefVersion, serverVersion, launcher);
+    if (isExactIdentity(identity, expected)) return true;
+    const compatiblePrior = identity?.schemaVersion === 1
+      && identity?.service === "taskchef-dashboard"
+      && identity?.workspace === canonicalWorkspace
+      && identity?.launcher === "mcp"
+      && identity?.serverVersion === serverVersion
+      && priorCompatibleVersion(identity?.taskchefVersion, taskchefVersion);
+    if (compatiblePrior) {
+      try {
+        await retirePriorOwner(identity);
+        return false;
+      } catch (handoffError) {
+        if (!handoffError?.handoffRaceEligible) throw handoffError;
+        let raceError = handoffError;
+        for (let attempt = 0; attempt < 40; attempt += 1) {
+          try {
+            const replacement = await readIdentity({ host, port, timeoutMs: 100 });
+            if (isExactIdentity(replacement, expected)) return true;
+            if (!isExactIdentity(replacement, identity)) throw raceError;
+            if (raceError.retryAuthentication) {
+              try {
+                await retirePriorOwner(identity);
+                return false;
+              } catch (error) {
+                if (!error?.handoffRaceEligible) throw error;
+                raceError = error;
+              }
+            }
+          } catch (error) {
+            if (listenerAbsent(error) || error?.code === "ECONNRESET") return false;
+            throw error;
+          }
+          await new Promise((resolve) => setTimeout(resolve, 25));
+        }
+        throw raceError;
+      }
+    }
     if (!isExactIdentity(identity, expected)) {
       throw listenerConflict(
         url,
@@ -150,6 +407,14 @@ export function createDashboardManager({
     if (ownedServer) return publicResult("reused");
     if (await probe()) return publicResult("reused");
     try {
+      const secret = createDashboardControlSecret();
+      const control = {
+        secret,
+        onShutdown: () => {
+          retired = true;
+          return closeOwned();
+        },
+      };
       ownedServer = await createServer({
         workspace: canonicalWorkspace,
         host,
@@ -157,7 +422,23 @@ export function createDashboardManager({
         taskchefVersion,
         serverVersion,
         launcher,
+        control,
       });
+      ownedSecret = secret;
+      try {
+        await writeOwner(canonicalWorkspace, dashboardOwnerMetadata({
+          workspace: canonicalWorkspace,
+          host,
+          port: ownedServer.port,
+          taskchefVersion,
+          serverVersion,
+          launcher,
+          secret,
+        }));
+      } catch (error) {
+        await closeOwned().catch(() => {});
+        throw error;
+      }
       return publicResult("started");
     } catch (error) {
       if (error?.code !== "EADDRINUSE") throw error;
@@ -166,22 +447,57 @@ export function createDashboardManager({
     }
   };
 
+  const monitorExactReuse = () => {
+    if (reuseMonitor || ownedServer || closePromise || retired) return;
+    reuseMonitor = setInterval(() => {
+      if (ownedServer || closePromise || retired || reuseRecovery) return;
+      reuseRecovery = (async () => {
+        try {
+          const identity = await readIdentity({ host, port, timeoutMs: HEALTH_TIMEOUT_MS });
+          const expected = expectedIdentity(
+            canonicalWorkspace, taskchefVersion, serverVersion, launcher,
+          );
+          if (isExactIdentity(identity, expected)) return;
+          // A replacement listener with any other identity is never touched. Keep
+          // watching so this process can recover normally if that occupant exits.
+        } catch (error) {
+          if (!listenerAbsent(error) && error?.code !== "ECONNRESET") return;
+          const result = await ensureOnce();
+          if (result.action === "started" || ownedServer) stopReuseMonitor();
+        }
+      })().catch(() => {
+        // Startup diagnostics remain available through an explicit ensure call.
+      }).finally(() => {
+        reuseRecovery = null;
+      });
+    }, reuseMonitorIntervalMs);
+    reuseMonitor.unref?.();
+  };
+
   return {
     async ensure() {
-      if (closePromise) throw new Error("TaskChef dashboard manager is shutting down");
+      if (closePromise || retired) throw new Error("TaskChef dashboard manager is shutting down");
       if (ensurePromise) {
         await ensurePromise;
         return publicResult("reused");
       }
       ensurePromise = ensureOnce().finally(() => { ensurePromise = null; });
-      return ensurePromise;
+      const result = await ensurePromise;
+      if (result.action === "reused" && !ownedServer) monitorExactReuse();
+      return result;
     },
     async close() {
       closePromise ??= (async () => {
+        stopReuseMonitor();
         await ensurePromise?.catch(() => {});
-        const server = ownedServer;
-        ownedServer = null;
-        await server?.close();
+        await reuseRecovery?.catch(() => {});
+        const secret = ownedSecret;
+        if (secret) await closeOwned();
+        else {
+          const server = ownedServer;
+          ownedServer = null;
+          await server?.close();
+        }
       })();
       return closePromise;
     },

package/src/dashboard-ownership.js

@@ -0,0 +1,140 @@
+import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
+import { constants } from "node:fs";
+import { open, rename, unlink } from "node:fs/promises";
+import path from "node:path";
+
+export const DASHBOARD_CONTROL_VERSION = 1;
+export const DASHBOARD_OWNER_FILE = ".taskchef-dashboard-owner.json";
+export const DASHBOARD_CONTROL_CHALLENGE_PATH = "/api/control/challenge";
+export const DASHBOARD_CONTROL_SHUTDOWN_PATH = "/api/control/shutdown";
+
+const OWNER_MAX_BYTES = 4_096;
+const SECRET_PATTERN = /^[a-f0-9]{64}$/;
+const NONCE_PATTERN = /^[a-f0-9]{32,128}$/;
+const LOOPBACK_HOSTS = new Set(["127.0.0.1", "::1"]);
+
+function ownerPath(workspace) {
+  return path.join(workspace, DASHBOARD_OWNER_FILE);
+}
+
+function exactKeys(value, keys) {
+  return value && typeof value === "object" && !Array.isArray(value)
+    && Object.keys(value).sort().join("\0") === [...keys].sort().join("\0");
+}
+
+export function createDashboardControlSecret() {
+  return randomBytes(32).toString("hex");
+}
+
+export function createDashboardControlNonce() {
+  return randomBytes(24).toString("hex");
+}
+
+export function validDashboardControlSecret(secret) {
+  return typeof secret === "string" && SECRET_PATTERN.test(secret);
+}
+
+export function dashboardControlProof(secret, action, nonce) {
+  return createHmac("sha256", Buffer.from(secret, "hex"))
+    .update(`taskchef-dashboard-control-v${DASHBOARD_CONTROL_VERSION}:${action}:${nonce}`)
+    .digest("hex");
+}
+
+export function validDashboardControlNonce(nonce) {
+  return typeof nonce === "string" && NONCE_PATTERN.test(nonce);
+}
+
+export function verifyDashboardControlProof(secret, action, nonce, proof) {
+  if (!validDashboardControlSecret(secret) || !validDashboardControlNonce(nonce)
+      || typeof proof !== "string" || !SECRET_PATTERN.test(proof)) return false;
+  const expected = Buffer.from(dashboardControlProof(secret, action, nonce), "hex");
+  const supplied = Buffer.from(proof, "hex");
+  return expected.length === supplied.length && timingSafeEqual(expected, supplied);
+}
+
+export function dashboardOwnerMetadata({
+  workspace,
+  host,
+  port,
+  taskchefVersion,
+  serverVersion,
+  launcher,
+  secret,
+}) {
+  return {
+    schemaVersion: 1,
+    service: "taskchef-dashboard-owner",
+    controlVersion: DASHBOARD_CONTROL_VERSION,
+    workspace,
+    host,
+    port,
+    taskchefVersion,
+    serverVersion,
+    launcher,
+    secret,
+  };
+}
+
+function validOwner(value) {
+  const keys = [
+    "schemaVersion", "service", "controlVersion", "workspace", "host", "port",
+    "taskchefVersion", "serverVersion", "launcher", "secret",
+  ];
+  return exactKeys(value, keys)
+    && value.schemaVersion === 1
+    && value.service === "taskchef-dashboard-owner"
+    && value.controlVersion === DASHBOARD_CONTROL_VERSION
+    && typeof value.workspace === "string"
+    && LOOPBACK_HOSTS.has(value.host)
+    && Number.isInteger(value.port) && value.port >= 0 && value.port <= 65_535
+    && typeof value.taskchefVersion === "string"
+    && typeof value.serverVersion === "string"
+    && value.launcher === "mcp"
+    && typeof value.secret === "string" && SECRET_PATTERN.test(value.secret);
+}
+
+export async function readDashboardOwner(workspace) {
+  const filePath = ownerPath(workspace);
+  const handle = await open(filePath, constants.O_RDONLY | constants.O_NOFOLLOW);
+  try {
+    const info = await handle.stat();
+    if (!info.isFile() || (info.mode & 0o777) !== 0o600) {
+      throw new Error("dashboard owner record is not a private regular file");
+    }
+    if (typeof process.getuid === "function" && info.uid !== process.getuid()) {
+      throw new Error("dashboard owner record has a different owner");
+    }
+    if (info.size > OWNER_MAX_BYTES) throw new Error("dashboard owner record is too large");
+    const buffer = Buffer.alloc(OWNER_MAX_BYTES + 1);
+    const { bytesRead } = await handle.read(buffer, 0, buffer.length, 0);
+    if (bytesRead > OWNER_MAX_BYTES) throw new Error("dashboard owner record is too large");
+    const value = JSON.parse(buffer.subarray(0, bytesRead).toString("utf8"));
+    if (!validOwner(value) || value.workspace !== workspace) {
+      throw new Error("dashboard owner record is invalid");
+    }
+    return value;
+  } finally {
+    await handle.close();
+  }
+}
+
+export async function writeDashboardOwner(workspace, value) {
+  if (!validOwner(value) || value.workspace !== workspace) {
+    throw new Error("dashboard owner record does not match its canonical workspace");
+  }
+  const filePath = ownerPath(workspace);
+  const temporary = `${filePath}.${process.pid}.${randomBytes(8).toString("hex")}.tmp`;
+  try {
+    const handle = await open(temporary, "wx", 0o600);
+    try {
+      await handle.writeFile(`${JSON.stringify(value)}\n`, { encoding: "utf8" });
+      await handle.sync();
+    } finally {
+      await handle.close();
+    }
+    await rename(temporary, filePath);
+  } catch (error) {
+    await unlink(temporary).catch(() => {});
+    throw error;
+  }
+}

package/src/dashboard.js

@@ -25,6 +25,14 @@ import { DASHBOARD_SERVER_VERSION, TASKCHEF_VERSION } from "./version.js";
 import { taskGitHubProjection } from "./dashboard/github-links.js";
 import { CODEX_CHAT_ARCHIVE_ENABLED } from "./dashboard/state.js";
 import { createUsageTracker } from "./usage-tracker.js";
+import {
+  DASHBOARD_CONTROL_CHALLENGE_PATH,
+  DASHBOARD_CONTROL_SHUTDOWN_PATH,
+  dashboardControlProof,
+  validDashboardControlNonce,
+  validDashboardControlSecret,
+  verifyDashboardControlProof,
+} from "./dashboard-ownership.js";
 
 const TASKS_FILE_NAME = "tasks.jsonl";
 const STATIC_ROOT = fileURLToPath(new URL("./dashboard/", import.meta.url));
@@ -544,6 +552,7 @@ export async function createDashboardServer({
   taskchefVersion = TASKCHEF_VERSION,
   serverVersion = DASHBOARD_SERVER_VERSION,
   usageTracker = null,
+  control = null,
 } = {}) {
   if (!LOOPBACK_HOSTS.has(host)) {
     throw new Error("dashboard host must be a loopback address");
@@ -557,6 +566,11 @@ export async function createDashboardServer({
   if (!new Set(["mcp", "standalone"]).has(launcher)) {
     throw new Error("dashboard launcher must be mcp or standalone");
   }
+  if (control !== null && (launcher !== "mcp"
+      || !validDashboardControlSecret(control?.secret)
+      || typeof control?.onShutdown !== "function")) {
+    throw new Error("dashboard control requires a valid MCP ownership controller");
+  }
   const monitor = new DashboardMonitor(workspace, monitorOptions);
   await monitor.start();
   const taskUsageTracker = usageTracker ?? createUsageTracker({ workspace: monitor.workspace });
@@ -574,6 +588,7 @@ export async function createDashboardServer({
   }
   const clients = new Set();
   const archiveRequests = new Set();
+  const controlNonces = new Set();
   let allowedAuthority;
   let allowedOrigin;
 
@@ -615,6 +630,41 @@ export async function createDashboardServer({
       return;
     }
 
+    if (url.pathname === DASHBOARD_CONTROL_CHALLENGE_PATH && method === "GET") {
+      const nonce = url.searchParams.get("nonce");
+      if (!control || !validDashboardControlNonce(nonce)) {
+        sendJson(response, control ? 400 : 404, { message: "Not found." });
+        return;
+      }
+      sendJson(response, 200, {
+        schemaVersion: 1,
+        nonce,
+        proof: dashboardControlProof(control.secret, "challenge", nonce),
+      });
+      return;
+    }
+
+    if (url.pathname === DASHBOARD_CONTROL_SHUTDOWN_PATH && method === "POST") {
+      if (!control) {
+        sendJson(response, 404, { message: "Not found." });
+        return;
+      }
+      const body = await readBoundedJsonBody(request);
+      const nonce = body?.nonce;
+      if (!verifyDashboardControlProof(control.secret, "shutdown", nonce, body?.proof)) {
+        sendJson(response, 403, { message: "Dashboard control authentication failed." });
+        return;
+      }
+      if (controlNonces.has(nonce)) {
+        sendJson(response, 409, { message: "Dashboard control credential was already used." });
+        return;
+      }
+      controlNonces.add(nonce);
+      sendJson(response, 202, { schemaVersion: 1, accepted: true });
+      setImmediate(() => { void control.onShutdown().catch(() => {}); });
+      return;
+    }
+
     if (url.pathname === "/api/snapshot" && (method === "GET" || method === "HEAD")) {
       if (method === "HEAD") {
         response.writeHead(200, securityHeaders("application/json; charset=utf-8"));
@@ -882,8 +932,10 @@ export async function createDashboardServer({
       monitor.off("monitorError", errorListener);
       monitor.close();
       for (const client of clients) client.close();
-      await new Promise((resolve, reject) => server.close((error) =>
+      const closed = new Promise((resolve, reject) => server.close((error) =>
         error ? reject(error) : resolve()));
+      server.closeAllConnections?.();
+      await closed;
     },
   };
 }

package/src/mcp-process.js

@@ -0,0 +1,79 @@
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+import { createTaskChefMcpServer } from "./mcp.js";
+import { installParentLossMonitor } from "./process-lifecycle.js";
+
+const CONNECTION_SHUTDOWN_GRACE_MS = 1_000;
+
+export async function runTaskChefMcpProcess({
+  server = createTaskChefMcpServer(),
+  transport = new StdioServerTransport(),
+  processObject = process,
+  installParentMonitor = installParentLossMonitor,
+} = {}) {
+  let shutdownPromise = null;
+  let parentMonitor = null;
+  let resolveTerminal;
+  let resolveConnectionSettled;
+  const originalProtocolClose = server.server?.onclose;
+  const terminal = new Promise((resolve) => { resolveTerminal = resolve; });
+  const connectionSettled = new Promise((resolve) => { resolveConnectionSettled = resolve; });
+  const removeLifecycleListeners = () => {
+    processObject.off("SIGINT", shutdown);
+    processObject.off("SIGTERM", shutdown);
+    processObject.stdin.off("end", shutdown);
+    processObject.stdin.off("close", shutdown);
+    if (server.server?.onclose === protocolClose) server.server.onclose = originalProtocolClose;
+  };
+  const protocolClose = () => {
+    try { originalProtocolClose?.(); } finally { void shutdown(); }
+  };
+  if (server.server) server.server.onclose = protocolClose;
+  const shutdown = () => {
+    shutdownPromise ??= (async () => {
+      try {
+        await Promise.resolve().then(() => transport.close?.()).catch(() => {});
+        let connectionTimer;
+        await Promise.race([
+          connectionSettled,
+          new Promise((resolve) => {
+            connectionTimer = setTimeout(resolve, CONNECTION_SHUTDOWN_GRACE_MS);
+          }),
+        ]);
+        clearTimeout(connectionTimer);
+        await server.close();
+      } catch (error) {
+        processObject.stderr.write(`TaskChef MCP shutdown failed: ${error.message}\n`);
+        processObject.exitCode = 1;
+      } finally {
+        parentMonitor?.close();
+        removeLifecycleListeners();
+        resolveTerminal();
+      }
+    })();
+    return shutdownPromise;
+  };
+  processObject.once("SIGINT", shutdown);
+  processObject.once("SIGTERM", shutdown);
+  processObject.stdin.once("end", shutdown);
+  processObject.stdin.once("close", shutdown);
+  parentMonitor = installParentMonitor({ onParentLoss: shutdown });
+  const connection = server.connect(transport).then(
+    () => ({ connected: true, error: null }),
+    (error) => ({ connected: false, error }),
+  ).finally(resolveConnectionSettled);
+  const outcome = await Promise.race([
+    connection,
+    terminal.then(() => ({ terminated: true })),
+  ]);
+  if (outcome.terminated) return;
+  if (outcome.error) {
+    if (shutdownPromise) await shutdownPromise;
+    else {
+      parentMonitor.close();
+      removeLifecycleListeners();
+    }
+    throw outcome.error;
+  }
+  await terminal;
+}

package/src/mcp.js

@@ -123,6 +123,9 @@ function toolResult(key, value, message) {
 
 function dashboardAutostartDiagnostic(error) {
   const message = typeof error?.message === "string" ? error.message : "";
+  if (typeof error?.staleTaskchefVersion === "string") {
+    return `TaskChef dashboard autostart skipped: verified older TaskChef ${error.staleTaskchefVersion} listener could not complete authenticated handoff; it was left untouched.`;
+  }
   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.";
   }
@@ -176,10 +179,16 @@ export function createTaskChefMcpServer({
 
   const originalClose = server.close.bind(server);
   let closePromise = null;
+  let closing = false;
   server.close = async () => {
+    closing = true;
     closePromise ??= (async () => {
-      await dashboardManager.close();
-      await originalClose();
+      const results = await Promise.allSettled([
+        dashboardManager.close(),
+        originalClose(),
+      ]);
+      const failure = results.find((result) => result.status === "rejected");
+      if (failure) throw failure.reason;
     })();
     return closePromise;
   };
@@ -349,8 +358,13 @@ export function createTaskChefMcpServer({
   });
   server.connect = async (...args) => {
     await autostartDashboard();
+    if (closing) throw new Error("TaskChef MCP server is shutting down");
     try {
       await originalConnect(...args);
+      if (closing) {
+        await originalClose();
+        throw new Error("TaskChef MCP server shut down during transport startup");
+      }
     } catch (error) {
       await Promise.allSettled([
         Promise.resolve().then(() => dashboardManager.close()),

package/src/process-lifecycle.js

@@ -0,0 +1,29 @@
+const DEFAULT_PARENT_CHECK_INTERVAL_MS = 1_000;
+
+export function installParentLossMonitor({
+  onParentLoss,
+  parentPid = process.ppid,
+  readParentPid = () => process.ppid,
+  intervalMs = DEFAULT_PARENT_CHECK_INTERVAL_MS,
+  schedule = setInterval,
+  cancel = clearInterval,
+} = {}) {
+  if (typeof onParentLoss !== "function") throw new Error("parent-loss callback is required");
+  let stopped = false;
+  let notified = false;
+  const check = () => {
+    if (stopped || notified || readParentPid() === parentPid) return;
+    notified = true;
+    void Promise.resolve().then(onParentLoss).catch(() => {});
+  };
+  const timer = schedule(check, intervalMs);
+  timer.unref?.();
+  return {
+    check,
+    close() {
+      if (stopped) return;
+      stopped = true;
+      cancel(timer);
+    },
+  };
+}