taskchef 5.8.0 → 5.10.0

package/.codex-plugin/plugin.json

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

package/README.md

@@ -162,6 +162,66 @@ when its metadata is newer than the callback; missing callbacks and other
 anomalies also receive at most one targeted read. Reporting writes nothing and
 never polls.
 
+### Watch the local dashboard
+
+Run a local dashboard when you want the task history to remain visible while
+executors report results:
+
+```sh
+taskchef dashboard
+```
+
+Open the printed capability URL, which starts with `http://127.0.0.1:3210` and
+contains a one-time launch token. Do not share it: the browser exchanges it for
+a local session cookie before loading task data, then removes the token from the
+address bar. Use `--port <number>` to choose another port and `--workspace
+<path>` to override the normal workspace resolution. Press Ctrl+C in the
+terminal to stop the server.
+
+The dashboard:
+
+- orders tasks by their latest semantic or identity update;
+- filters by project, status, and latest update window (24 hours, 7 days, or
+  all time);
+- shows dismissible notifications when tasks are added or changed;
+- reveals the original instruction, latest semantic result, and task metadata;
+- opens the recorded task directly in Codex when it has a supported UUID thread
+  ID, with a project-opening fallback for unresolved or legacy identities.
+
+The server binds only to the numeric IPv4 loopback interface, requires the
+unguessable launch capability before serving instructions or results, validates
+the same task schema as the CLI, retains its last valid snapshot if the log
+becomes invalid, and never writes dispatcher-workspace files. It limits event
+streams and disconnects slow clients instead of buffering snapshots without
+bound. It watches the workspace directory
+so TaskChef's atomic log replacement remains visible, uses a low-frequency file
+metadata check to recover from missed watcher events, and streams snapshots to
+the browser with automatic reconnect. To keep untrusted history from exhausting
+the server or browser, the dashboard rejects logs above 16 MiB, histories above
+2,000 tasks, and unusually large display fields while retaining the last valid
+snapshot. The data CLI remains unaffected by these display limits.
+
+Date windows advance while the page is open, even when the task file is idle.
+They use persisted semantic/identity timestamps and identity changes observed by
+the current server. Legacy schema-v1 identity resolutions did not record an
+update timestamp, so after a dashboard restart those rare historical records
+fall back to their creation time.
+
+The dashboard uses Codex's registered `codex://threads/<thread-id>` desktop
+route for direct navigation. A task-level refresh would require native Codex
+metadata tools that are available to the report skill, not to a standalone
+browser page. TaskChef also does not submit replies from the dashboard: `codex
+resume <session> [prompt]` starts an interactive CLI session and may execute the
+prompt immediately, rather than opening a reviewed draft in the desktop app.
+Refresh and reply integrations remain deferred until Codex exposes supported
+browser-facing contracts for those actions.
+
+TaskChef task records do not contain model token usage, and the supported Codex
+task metadata surface does not expose it to this local server. The dashboard
+therefore does not estimate tokens or inspect private Codex session logs. Token
+usage can be added later if Codex exposes a supported per-task usage field or
+TaskChef executors begin reporting a structured usage value.
+
 ### Manage configured projects
 
 Use `$taskchef-bootstrap` to scan local Codex projects and refresh the managed

package/index.js

@@ -56,9 +56,18 @@ export {
 
 export {
   discoverCodexCli,
+  isCodexThreadDeepLinkId,
+  openThreadInCodex,
   openWorkspaceInCodex,
 } from "./src/codex-app.js";
 
+export {
+  DashboardMonitor,
+  createDashboardServer,
+  dashboardAuthority,
+  sortTasksByMeaningfulUpdate,
+} from "./src/dashboard.js";
+
 export { createTaskChefMcpServer } from "./src/mcp.js";
 
 export { handleInitialPromptHook } from "./src/hook.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "taskchef",
-  "version": "5.8.0",
+  "version": "5.10.0",
   "description": "A non-blocking interactive dispatcher for visible Codex tasks.",
   "license": "MIT",
   "author": "Favo Yang",
@@ -45,7 +45,7 @@
   "scripts": {
     "benchmark:dispatch": "node scripts/benchmark-dispatch-prepare.js",
     "benchmark:e2e": "node scripts/e2e-benchmark.js",
-    "test": "node --test tests/taskchef.test.js"
+    "test": "node --test tests/*.test.js"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",

package/src/cli.js

@@ -2,6 +2,7 @@ import { access, readFile, realpath } from "node:fs/promises";
 import path from "node:path";
 
 import { openWorkspaceInCodex } from "./codex-app.js";
+import { createDashboardServer } from "./dashboard.js";
 import { resolveWorkspacePath } from "./workspace-path.js";
 
 import {
@@ -409,11 +410,51 @@ async function taskSummary(args) {
   return 0;
 }
 
+function dashboardPort(args) {
+  const value = option(args, "--port", "3210");
+  if (!/^\d+$/.test(value)) throw new Error("--port must be an integer from 0 to 65535");
+  const port = Number(value);
+  if (port > 65_535) throw new Error("--port must be an integer from 0 to 65535");
+  return port;
+}
+
+async function dashboard(args) {
+  validateCommandArgs(args, 1, {
+    values: ["--port", "--workspace"],
+    switches: ["--json"],
+  });
+  const server = await createDashboardServer({
+    workspace: workspaceRoot(args),
+    port: dashboardPort(args),
+  });
+  print({
+    schemaVersion: 1,
+    url: server.url,
+    workspace: server.monitor.workspace,
+  }, args, (value) => [
+    `TaskChef dashboard: ${value.url}`,
+    `Workspace: ${value.workspace}`,
+    "Press Ctrl+C to stop.",
+  ].join("\n"));
+
+  let stop;
+  await new Promise((resolve) => {
+    stop = resolve;
+    process.once("SIGINT", stop);
+    process.once("SIGTERM", stop);
+  });
+  process.off("SIGINT", stop);
+  process.off("SIGTERM", stop);
+  await server.close();
+  return 0;
+}
+
 function usage() {
   process.stdout.write(`TaskChef workspace utility
 
 Usage:
   taskchef help
+  taskchef dashboard [--port <number>] [--json] [--workspace <path>]
   taskchef doctor [--json] [--workspace <path>]
   taskchef workspace path [--json] [--workspace <path>]
   taskchef workspace init [--register-codex] [--codex-cli <path>] [--json] [--workspace <path>]
@@ -435,6 +476,8 @@ 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.
 `);
 }
 
@@ -443,6 +486,7 @@ export async function runCli(args) {
     usage();
     return 0;
   }
+  if (args[0] === "dashboard") return dashboard(args);
   if (args[0] === "doctor") return doctor(args);
   if (args[0] === "workspace" && args[1] === "path") return workspacePath(args);
   if (args[0] === "workspace" && args[1] === "init") return initialize(args);

package/src/codex-app.js

@@ -5,6 +5,7 @@ import { promisify } from "node:util";
 
 const execFile = promisify(execFileCallback);
 const CODEX_COMMAND_TIMEOUT_MS = 10_000;
+const CODEX_THREAD_ID_PATTERN = /^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$/i;
 
 function runCodex(run, filePath, args) {
   return run(filePath, args, { timeout: CODEX_COMMAND_TIMEOUT_MS, killSignal: "SIGKILL" });
@@ -26,6 +27,10 @@ function pathCandidates(env) {
     .map((directory) => path.join(directory, process.platform === "win32" ? "codex.exe" : "codex"));
 }
 
+function isDesktopBundleCandidate(filePath) {
+  return filePath.includes(`${path.sep}Contents${path.sep}Resources${path.sep}`);
+}
+
 async function supportsAppCommand(filePath, run) {
   try {
     const { stdout, stderr } = await runCodex(run, filePath, ["app", "--help"]);
@@ -50,8 +55,16 @@ export async function discoverCodexCli({
     return { path: candidate, source: explicit !== null ? "explicit" : "environment" };
   }
 
+  const candidates = pathCandidates(env);
+  for (const pathCandidate of candidates.filter(isDesktopBundleCandidate)) {
+    const candidate = await executable(pathCandidate);
+    if (candidate && await supportsAppCommand(candidate, run)) {
+      return { path: candidate, source: "desktop-path" };
+    }
+  }
+
   let candidate = null;
-  for (const pathCandidate of pathCandidates(env)) {
+  for (const pathCandidate of candidates) {
     candidate = await executable(pathCandidate);
     if (candidate) break;
   }
@@ -59,8 +72,7 @@ export async function discoverCodexCli({
   if (!(await supportsAppCommand(candidate, run))) {
     throw new Error(`Codex CLI does not support the app command: ${candidate}`);
   }
-  const bundled = candidate.includes(`${path.sep}Contents${path.sep}Resources${path.sep}`);
-  return { path: candidate, source: bundled ? "desktop-path" : "path" };
+  return { path: candidate, source: "path" };
 }
 
 export async function openWorkspaceInCodex(workspace, options = {}) {
@@ -75,3 +87,24 @@ export async function openWorkspaceInCodex(workspace, options = {}) {
     workspace,
   };
 }
+
+export function isCodexThreadDeepLinkId(threadId) {
+  return typeof threadId === "string" && CODEX_THREAD_ID_PATTERN.test(threadId);
+}
+
+export async function openThreadInCodex(threadId, options = {}) {
+  if (!isCodexThreadDeepLinkId(threadId)) {
+    throw new Error("Codex thread ID is not supported by the desktop deep link");
+  }
+  const run = options.run ?? execFile;
+  const platform = options.platform ?? process.platform;
+  const url = `codex://threads/${encodeURIComponent(threadId)}`;
+  if (platform === "darwin") {
+    await runCodex(run, "/usr/bin/open", [url]);
+  } else if (platform === "win32") {
+    await runCodex(run, "rundll32.exe", ["url.dll,FileProtocolHandler", url]);
+  } else {
+    await runCodex(run, "xdg-open", [url]);
+  }
+  return { status: "requested", mechanism: "codex-deep-link", threadId, url };
+}

package/src/dashboard/app.js

@@ -0,0 +1,265 @@
+import {
+  findCurrentTask,
+  KNOWN_TASK_STATUSES,
+  nextDateFilterRefreshDelay,
+  reconcileNotifications,
+  taskStatusLabel,
+  taskWithinDateFilter,
+} from "./state.js";
+
+const state = {
+  tasks: [],
+  signatures: new Map(),
+  notifications: [],
+  initialized: false,
+  selectedTask: null,
+};
+let dateRefreshTimer = null;
+
+const elements = {
+  clearNotifications: document.querySelector("#clear-notifications"),
+  closeDialog: document.querySelector("#close-dialog"),
+  connectionDot: document.querySelector("#connection-dot"),
+  connectionLabel: document.querySelector("#connection-label"),
+  copyThreadId: document.querySelector("#copy-thread-id"),
+  dashboardMessage: document.querySelector("#dashboard-message"),
+  dateFilter: document.querySelector("#date-filter"),
+  dialog: document.querySelector("#task-dialog"),
+  dialogInstruction: document.querySelector("#dialog-instruction"),
+  dialogMetadata: document.querySelector("#dialog-metadata"),
+  dialogProject: document.querySelector("#dialog-project"),
+  dialogSummary: document.querySelector("#dialog-summary"),
+  dialogTitle: document.querySelector("#dialog-title"),
+  emptyState: document.querySelector("#empty-state"),
+  notifications: document.querySelector("#notifications"),
+  openProject: document.querySelector("#open-codex"),
+  projectFilter: document.querySelector("#project-filter"),
+  statusFilter: document.querySelector("#status-filter"),
+  taskCount: document.querySelector("#task-count"),
+  taskList: document.querySelector("#task-list"),
+  toastList: document.querySelector("#toast-list"),
+};
+
+function formatTime(value) {
+  if (!value) return "—";
+  return new Intl.DateTimeFormat(undefined, {
+    dateStyle: "medium",
+    timeStyle: "short",
+  }).format(new Date(value));
+}
+
+function setConnection(connected) {
+  elements.connectionDot.classList.toggle("connected", connected);
+  elements.connectionLabel.textContent = connected ? "Live" : "Reconnecting…";
+}
+
+function replaceOptions(select, values, allLabel) {
+  const selected = select.value;
+  select.replaceChildren();
+  const all = document.createElement("option");
+  all.value = "";
+  all.textContent = allLabel;
+  select.append(all);
+  for (const value of values) {
+    const option = document.createElement("option");
+    option.value = value;
+    option.textContent = value;
+    select.append(option);
+  }
+  if (values.includes(selected)) select.value = selected;
+}
+
+function notificationToast(notification) {
+  const task = findCurrentTask(state.tasks, notification.taskId);
+  if (!task) return null;
+  const toast = document.createElement("div");
+  toast.className = "toast";
+  const text = document.createElement("button");
+  text.type = "button";
+  text.className = "toast-content";
+  const title = document.createElement("strong");
+  title.textContent = notification.kind === "new" ? "New task" : "Task updated";
+  const description = document.createElement("span");
+  description.textContent = `${task.title} · ${taskStatusLabel(task)}`;
+  text.append(title, description);
+  text.addEventListener("click", () => {
+    const current = findCurrentTask(state.tasks, notification.taskId);
+    if (current) openDialog(current);
+    else showMessage("This task is no longer present in the current snapshot.");
+  });
+  const dismiss = document.createElement("button");
+  dismiss.type = "button";
+  dismiss.className = "icon-button";
+  dismiss.setAttribute("aria-label", `Dismiss notification for ${task.title}`);
+  dismiss.textContent = "×";
+  dismiss.addEventListener("click", () => {
+    state.notifications = state.notifications.filter(({ id }) => id !== notification.id);
+    renderNotifications();
+  });
+  toast.append(text, dismiss);
+  return toast;
+}
+
+function renderNotifications() {
+  elements.toastList.replaceChildren(
+    ...state.notifications.map(notificationToast).filter(Boolean),
+  );
+  elements.notifications.hidden = state.notifications.length === 0;
+}
+
+function detailRow(term, value) {
+  const dt = document.createElement("dt");
+  dt.textContent = term;
+  const dd = document.createElement("dd");
+  dd.textContent = value ?? "—";
+  return [dt, dd];
+}
+
+function openDialog(task) {
+  state.selectedTask = task;
+  elements.dialogProject.textContent = task.project.name;
+  elements.dialogTitle.textContent = task.title;
+  elements.dialogSummary.textContent = task.summary ?? "No semantic result has been reported yet.";
+  elements.dialogInstruction.textContent = task.instruction;
+  elements.copyThreadId.disabled = !task.threadId;
+  elements.dialogMetadata.replaceChildren(
+    ...detailRow("Status", taskStatusLabel(task)),
+    ...detailRow("Task ID", task.id),
+    ...detailRow("Thread ID", task.threadId),
+    ...detailRow("Turn ID", task.turnId),
+    ...detailRow("Project path", task.project.path),
+    ...detailRow("Created", formatTime(task.createdAt)),
+    ...detailRow("Updated", formatTime(
+      task.meaningfulUpdatedAt ?? task.updatedAt ?? task.createdAt,
+    )),
+    ...detailRow("Updated by", task.updatedBy),
+  );
+  if (!elements.dialog.open) elements.dialog.showModal();
+}
+
+function taskCard(task) {
+  const article = document.createElement("article");
+  article.className = "task-card";
+  const heading = document.createElement("div");
+  heading.className = "task-heading";
+  const title = document.createElement("button");
+  title.type = "button";
+  title.className = "task-title";
+  title.textContent = task.title;
+  title.addEventListener("click", () => openDialog(task));
+  const badge = document.createElement("span");
+  badge.className = `status status-${task.status ?? "unresolved"}`;
+  badge.textContent = taskStatusLabel(task);
+  heading.append(title, badge);
+  const project = document.createElement("p");
+  project.className = "task-project";
+  project.textContent = task.project.name;
+  const summary = document.createElement("p");
+  summary.className = "task-summary";
+  summary.textContent = task.summary ?? "No semantic result reported yet.";
+  const time = document.createElement("time");
+  time.dateTime = task.meaningfulUpdatedAt ?? task.updatedAt ?? task.createdAt;
+  time.textContent = `Updated ${formatTime(time.dateTime)}`;
+  article.append(heading, project, summary, time);
+  return article;
+}
+
+function render() {
+  const project = elements.projectFilter.value;
+  const status = elements.statusFilter.value;
+  const date = elements.dateFilter.value;
+  const visible = state.tasks.filter((task) =>
+    (!project || task.project.name === project)
+    && (!status || taskStatusLabel(task) === status)
+    && taskWithinDateFilter(task, date));
+  elements.taskList.replaceChildren(...visible.map(taskCard));
+  elements.emptyState.hidden = visible.length > 0;
+  elements.taskCount.textContent = `${visible.length} of ${state.tasks.length} task${state.tasks.length === 1 ? "" : "s"}`;
+  clearTimeout(dateRefreshTimer);
+  const refreshDelay = nextDateFilterRefreshDelay(visible, date);
+  dateRefreshTimer = refreshDelay === null ? null : setTimeout(render, refreshDelay);
+}
+
+function applySnapshot(snapshot) {
+  const reconciled = reconcileNotifications({
+    initialized: state.initialized,
+    notifications: state.notifications,
+    signatures: state.signatures,
+  }, snapshot.tasks, snapshot.revision);
+  state.tasks = snapshot.tasks;
+  state.signatures = reconciled.signatures;
+  state.notifications = reconciled.notifications;
+  state.initialized = true;
+  if (snapshot.healthy === false) {
+    showMessage("The task log is temporarily unavailable. Showing the last valid snapshot.");
+  } else {
+    elements.dashboardMessage.hidden = true;
+  }
+  replaceOptions(
+    elements.projectFilter,
+    [...new Set(state.tasks.map((task) => task.project.name))].sort(),
+    "All projects",
+  );
+  replaceOptions(
+    elements.statusFilter,
+    [...new Set([...KNOWN_TASK_STATUSES, ...state.tasks.map(taskStatusLabel)])],
+    "All statuses",
+  );
+  if (state.selectedTask) {
+    const updated = state.tasks.find((task) => task.id === state.selectedTask.id);
+    if (updated && elements.dialog.open) openDialog(updated);
+  }
+  renderNotifications();
+  render();
+}
+
+function showMessage(message) {
+  elements.dashboardMessage.textContent = message;
+  elements.dashboardMessage.hidden = false;
+}
+
+const events = new EventSource("/api/events");
+events.addEventListener("open", () => setConnection(true));
+events.addEventListener("error", () => setConnection(false));
+events.addEventListener("snapshot", (event) => {
+  setConnection(true);
+  applySnapshot(JSON.parse(event.data));
+});
+events.addEventListener("dashboard-error", (event) => {
+  showMessage(JSON.parse(event.data).message);
+});
+
+elements.projectFilter.addEventListener("change", render);
+elements.statusFilter.addEventListener("change", render);
+elements.dateFilter.addEventListener("change", render);
+elements.clearNotifications.addEventListener("click", () => {
+  state.notifications = [];
+  renderNotifications();
+});
+elements.closeDialog.addEventListener("click", () => elements.dialog.close());
+elements.dialog.addEventListener("click", (event) => {
+  if (event.target === elements.dialog) elements.dialog.close();
+});
+elements.copyThreadId.addEventListener("click", async () => {
+  if (!state.selectedTask?.threadId) return;
+  try {
+    await navigator.clipboard.writeText(state.selectedTask.threadId);
+    elements.copyThreadId.textContent = "Copied";
+    setTimeout(() => { elements.copyThreadId.textContent = "Copy thread ID"; }, 1_500);
+  } catch {
+    showMessage("Clipboard access is unavailable. Copy the thread ID from the metadata below.");
+  }
+});
+elements.openProject.addEventListener("click", async () => {
+  if (!state.selectedTask) return;
+  elements.openProject.disabled = true;
+  try {
+    const response = await fetch(`/api/tasks/${encodeURIComponent(state.selectedTask.id)}/open-codex`, {
+      method: "POST",
+    });
+    const result = await response.json();
+    showMessage(result.message);
+  } finally {
+    elements.openProject.disabled = false;
+  }
+});

package/src/dashboard/index.html

@@ -0,0 +1,94 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <meta name="color-scheme" content="light dark">
+    <title>TaskChef dashboard</title>
+    <link rel="stylesheet" href="/styles.css">
+    <script src="/app.js" type="module"></script>
+  </head>
+  <body>
+    <header class="site-header">
+      <div>
+        <p class="eyebrow">TaskChef</p>
+        <h1>Task dashboard</h1>
+        <p class="subtitle">Latest delegated work, updated as TaskChef reports change.</p>
+      </div>
+      <div class="connection" role="status" aria-live="polite">
+        <span id="connection-dot" class="connection-dot"></span>
+        <span id="connection-label">Connecting…</span>
+      </div>
+    </header>
+
+    <main>
+      <section class="toolbar" aria-label="Task filters">
+        <label>
+          Project
+          <select id="project-filter">
+            <option value="">All projects</option>
+          </select>
+        </label>
+        <label>
+          Status
+          <select id="status-filter">
+            <option value="">All statuses</option>
+          </select>
+        </label>
+        <label>
+          Updated
+          <select id="date-filter">
+            <option value="24h">Latest 24 hours</option>
+            <option value="7d">Latest 7 days</option>
+            <option value="all" selected>All time</option>
+          </select>
+        </label>
+        <p id="task-count" class="task-count" aria-live="polite"></p>
+      </section>
+
+      <div id="dashboard-message" class="dashboard-message" role="status" hidden></div>
+      <section aria-labelledby="tasks-heading">
+        <h2 id="tasks-heading" class="visually-hidden">Tasks</h2>
+        <div id="task-list" class="task-list"></div>
+        <div id="empty-state" class="empty-state" hidden>
+          <h2>No tasks match these filters</h2>
+          <p>Choose a different project or status to see more work.</p>
+        </div>
+      </section>
+    </main>
+
+    <aside id="notifications" class="notifications" aria-label="Task notifications" hidden>
+      <div class="notifications-heading">
+        <strong>Updates</strong>
+        <button id="clear-notifications" class="text-button" type="button">Clear all</button>
+      </div>
+      <div id="toast-list" class="toast-list" aria-live="polite"></div>
+    </aside>
+
+    <dialog id="task-dialog" aria-labelledby="dialog-title">
+      <div class="dialog-header">
+        <div>
+          <p id="dialog-project" class="eyebrow"></p>
+          <h2 id="dialog-title"></h2>
+        </div>
+        <button id="close-dialog" class="icon-button" type="button" aria-label="Close task details">×</button>
+      </div>
+      <div class="dialog-actions">
+        <button id="open-codex" class="primary-button" type="button">Open task in Codex</button>
+        <button id="copy-thread-id" class="secondary-button" type="button">Copy thread ID</button>
+      </div>
+      <section>
+        <h3>Result</h3>
+        <p id="dialog-summary" class="preserve-lines"></p>
+      </section>
+      <section>
+        <h3>Original instruction</h3>
+        <pre id="dialog-instruction"></pre>
+      </section>
+      <section>
+        <h3>Metadata</h3>
+        <dl id="dialog-metadata" class="metadata"></dl>
+      </section>
+    </dialog>
+  </body>
+</html>