taskchef 7.22.5 → 7.23.0

package/.codex-plugin/plugin.json

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

package/README.md

@@ -327,10 +327,10 @@ app-callable archive interface or guarantees CLI compatibility. The dormant
 server path also rejects requests before discovering or invoking the CLI.
 
 Task details also show whole-task and per-turn token usage when `ccusage` can
-map the linked Codex thread. A completed turn briefly shows “Tokens:
-calculating…” while TaskChef performs bounded deferred reconciliation, because
+map the linked Codex thread. A completed turn briefly shows “Calculating token
+usage…” while TaskChef performs bounded deferred reconciliation, because
 the terminal lifecycle callback precedes Codex's final output write. Historical
-tasks may show a trustworthy task total while older turns remain “Tokens
+tasks may show a trustworthy task total while older turns remain “Token usage
 unavailable” when no cumulative turn boundaries were recorded. Input, cached
 input, output, reasoning, and total counts retain ccusage's categories. Dollar
 figures are labeled API-equivalent estimates; provenance identifies the online

package/docs/dashboard-lifecycle.md

@@ -25,6 +25,15 @@ workspace resolution, and startup isolation, but none of those requires the
 HTTP listener to share one MCP transport's lifetime. The session process keeps
 those benefits without retaining the obsolete per-transport ownership.
 
+## Token usage presentation
+
+The detail view distinguishes an active turn whose final usage is pending from
+a terminal turn whose usage is being calculated. Available usage keeps both
+the token total and API-equivalent USD estimate; an available cumulative value
+shown during a newer active turn is labeled as known so far.
+
+![Pending token usage in the task detail view](images/dashboard-token-pending.jpg)
+
 ## Start and reuse
 
 Unless `dashboard.autostart` is explicitly `false`, MCP activation runs the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "taskchef",
-  "version": "7.22.5",
+  "version": "7.23.0",
   "description": "A non-blocking interactive dispatcher for visible Codex tasks.",
   "license": "MIT",
   "author": "Favo Yang",
@@ -32,6 +32,7 @@
     "docs/images/notification-event-snapshots.jpg",
     "docs/images/result-history-dashboard.jpg",
     "docs/images/interrupted-turn-recovery.jpg",
+    "docs/images/dashboard-token-pending.jpg",
     "index.js",
     "mcp",
     "scripts/benchmark-dispatch-prepare.js",

package/src/dashboard/app.js

@@ -49,6 +49,7 @@ const state = {
   notifications: [],
   seenNotificationIds: new Set(),
   initialized: false,
+  detailNavigation: null,
   manualTransition: null,
   selectedTask: null,
 };
@@ -80,6 +81,7 @@ const elements = {
   dismissDashboardMessage: document.querySelector("#dismiss-dashboard-message"),
   emptyState: document.querySelector("#empty-state"),
   notifications: document.querySelector("#notifications"),
+  notificationHost: document.querySelector("#notification-host"),
   notificationAnnouncer: document.querySelector("#notification-announcer"),
   manualTransitionPanel: document.querySelector("#manual-transition-panel"),
   manualTransitionError: document.querySelector("#manual-transition-error"),
@@ -103,6 +105,7 @@ function referenceLink(link, { compact = false, displayLabel } = {}) {
   anchor.href = link.url;
   anchor.target = "_blank";
   anchor.rel = "noopener noreferrer";
+  anchor.dataset.focusKey = `link:${link.url}`;
   const label = link.label ?? link.text;
   anchor.textContent = displayLabel ?? label;
   const accessibleLabel = githubReferenceAccessibleLabel(link);
@@ -211,6 +214,7 @@ function timestampControl(value, { accessibleName, key, prefix = "" }) {
   const control = document.createElement("button");
   control.type = "button";
   control.className = "timestamp-toggle";
+  control.dataset.focusKey = `timestamp:${key}`;
   const time = document.createElement("time");
   control.append(time);
   relativeTimes.register(key, value, ({ exact, iso, label }) => {
@@ -323,10 +327,16 @@ function notificationToast(notification) {
   text.append(metadata);
   describedBy.push(metadata.id);
   text.setAttribute("aria-describedby", describedBy.join(" "));
-  text.addEventListener("click", () => {
+  text.addEventListener("click", async () => {
     const current = findCurrentTask(state.tasks, notification.taskId);
-    if (current) openDialog(current);
-    else showMessage("This task is no longer present in the current snapshot.");
+    state.notifications = dismissNotification(state.notifications, notification.id);
+    renderNotifications();
+    if (current) {
+      await openDialog(current, {
+        focus: true,
+        highlightTurnRef: notification.turnRef ?? notification.turnId,
+      });
+    } else showMessage("This task is no longer present in the current snapshot.");
   });
   const dismiss = document.createElement("button");
   dismiss.type = "button";
@@ -356,7 +366,31 @@ function renderNotifications(additions = []) {
   elements.toastList.replaceChildren(
     ...state.notifications.map(notificationToast),
   );
-  elements.notifications.hidden = state.notifications.length === 0;
+  const notificationHost = elements.dialog.open ? elements.dialog : elements.notificationHost;
+  const movingLayer = elements.notifications.parentNode !== notificationHost;
+  if ((movingLayer || additions.length > 0) && state.notifications.length > 0) {
+    try {
+      elements.notifications.hidePopover?.();
+    } catch {
+      // The notification layer is not open yet.
+    }
+  }
+  if (movingLayer) notificationHost.append(elements.notifications);
+  if (state.notifications.length === 0) {
+    try {
+      elements.notifications.hidePopover?.();
+    } catch {
+      // The notification layer is already closed.
+    }
+    elements.notifications.hidden = true;
+  } else {
+    elements.notifications.hidden = false;
+    try {
+      elements.notifications.showPopover?.();
+    } catch {
+      // Re-rendering an already-open manual popover needs no further action.
+    }
+  }
   if (additions.length > 0) {
     elements.notificationAnnouncer.textContent = additions
       .map(notificationAnnouncement)
@@ -406,24 +440,31 @@ function usageBreakdownText(usage) {
   ].join(" · ");
 }
 
-function usagePresentation(usage, { wholeTask = false } = {}) {
+export function usagePresentation(usage, { wholeTask = false } = {}) {
   const container = document.createElement("div");
-  container.className = `usage-summary usage-${usage?.status ?? "calculating"}`;
-  if (!usage || usage.status === "calculating") {
-    const indicator = document.createElement("span");
-    indicator.className = "usage-spinner";
-    indicator.setAttribute("aria-hidden", "true");
+  container.className = `usage-summary usage-${usage?.status ?? "unavailable"}`;
+  if (usage?.status === "pending" || usage?.status === "calculating") {
     const text = document.createElement("span");
-    text.textContent = "Tokens: calculating…";
-    container.replaceChildren(indicator, text);
+    text.className = "usage-shimmer";
+    text.textContent = usage.status === "pending"
+      ? "Tokens pending · available when turn finishes"
+      : "Calculating token usage…";
+    container.replaceChildren(text);
     return container;
   }
-  if (usage.status !== "available") {
-    container.textContent = `Tokens unavailable${usage.reason ? ` — ${usage.reason}` : "."}`;
+  if (usage?.status !== "available") {
+    const headline = document.createElement("strong");
+    headline.textContent = "Token usage unavailable";
+    container.append(headline);
+    if (usage?.reason) {
+      const reason = document.createElement("span");
+      reason.textContent = usage.reason;
+      container.append(reason);
+    }
     return container;
   }
   const headline = document.createElement("strong");
-  headline.textContent = `${tokenFormatter.format(usage.totalTokens)} tokens · ${formatEstimatedCost(usage.estimatedCostUsd)}`;
+  headline.textContent = `${tokenFormatter.format(usage.totalTokens)} tokens · ${formatEstimatedCost(usage.estimatedCostUsd)}${usage.knownSoFar ? " · known so far" : ""}`;
   const breakdown = document.createElement("span");
   breakdown.textContent = usageBreakdownText(usage);
   container.append(headline, breakdown);
@@ -449,7 +490,7 @@ function usageStillCalculating(task) {
       .some((turn) => turn.status === "calculating"));
 }
 
-function turnTimeline(task) {
+function turnTimeline(task, { highlightTurnRef = null } = {}) {
   if (task.turns.length === 0) {
     const empty = document.createElement("p");
     empty.className = "result-history-empty";
@@ -467,6 +508,11 @@ function turnTimeline(task) {
     status.className = `status status-${turnStatus}`;
     status.textContent = turnStatus.replaceAll("_", " ");
     const turnKey = turn.turnRef ?? turn.turnId ?? `no-turn:${index}`;
+    item.dataset.turnRef = turnKey;
+    if (highlightTurnRef !== null && turnKey === highlightTurnRef) {
+      item.className += " result-history-notified";
+      item.tabIndex = -1;
+    }
     const timestamp = timestampControl(presentation.updatedAt, {
       accessibleName: `Turn updated time for ${turnStatus.replaceAll("_", " ")}`,
       key: `detail:${task.id}:turn:${turnKey}`,
@@ -495,11 +541,13 @@ function turnTimeline(task) {
     const turnMetadata = document.createElement("p");
     turnMetadata.className = "result-history-turn";
     turnMetadata.textContent = `Turn ref ${turn.turnRef ?? "not recorded"}; Codex turn ${turn.turnId ?? "unavailable"}`;
-    const turnUsage = task.usage?.turns?.[turn.turnRef ?? turn.turnId] ?? (
-      turn.result === null
-        ? { status: "calculating" }
-        : { status: "unavailable", reason: "No reliable turn boundary is available." }
-    );
+    const recordedUsage = task.usage?.turns?.[turn.turnRef ?? turn.turnId];
+    const turnUsage = turn.result === null
+      ? { status: "pending" }
+      : recordedUsage ?? {
+        status: "unavailable",
+        reason: "No reliable turn boundary is available.",
+      };
     item.append(
       header,
       requestLabel,
@@ -513,6 +561,39 @@ function turnTimeline(task) {
   });
 }
 
+function descendantPath(root, descendant) {
+  const path = [];
+  let current = descendant;
+  while (current && current !== root) {
+    const parent = current.parentNode;
+    if (!parent) return null;
+    const index = Array.prototype.indexOf.call(parent.children, current);
+    if (index < 0) return null;
+    path.unshift(index);
+    current = parent;
+  }
+  return current === root ? path : null;
+}
+
+function descendantAtPath(root, path) {
+  let current = root;
+  for (const index of path ?? []) {
+    current = current?.children?.[index];
+    if (!current) return null;
+  }
+  return current;
+}
+
+function descendantWithFocusKey(root, focusKey) {
+  if (!root || !focusKey) return null;
+  if (root.dataset?.focusKey === focusKey) return root;
+  for (const child of root.children ?? []) {
+    const match = descendantWithFocusKey(child, focusKey);
+    if (match) return match;
+  }
+  return null;
+}
+
 function manualTransitionPending() {
   return state.manualTransition?.stage === "pending";
 }
@@ -648,7 +729,7 @@ async function submitManualTransition(targetStatus, event) {
   elements.manualTransitionError.focus();
 }
 
-function renderDialog(task) {
+function renderDialog(task, { highlightTurnRef = null } = {}) {
   if (state.selectedTask?.id !== task.id) {
     copyTaskIdGeneration += 1;
     clearTimeout(copyTaskIdTimer);
@@ -657,11 +738,27 @@ function renderDialog(task) {
   const preservedResults = state.selectedTask?.id === task.id
     ? state.selectedTask.results
     : null;
+  const preservedUsage = state.selectedTask?.id === task.id
+    ? state.selectedTask.usage
+    : null;
   const detailedTask = {
     ...task,
     turns: mergeProjectedTurns(task, state.selectedTask?.turns ?? []),
     results: task.results ?? preservedResults ?? [],
+    usage: task.usage ?? preservedUsage ?? null,
   };
+  const focusedElement = elements.dialogResults.contains?.(document.activeElement)
+    ? document.activeElement
+    : null;
+  let focusedTurn = focusedElement;
+  while (focusedTurn && focusedTurn !== elements.dialogResults && !focusedTurn.dataset?.turnRef) {
+    focusedTurn = focusedTurn.parentNode;
+  }
+  const focusedTurnRef = focusedTurn?.dataset?.turnRef ?? null;
+  const focusedDescendantKey = focusedElement?.dataset?.focusKey ?? null;
+  const focusedDescendantPath = focusedTurn && focusedElement
+    ? descendantPath(focusedTurn, focusedElement)
+    : null;
   state.selectedTask = detailedTask;
   renderProject(elements.dialogProject, task);
   elements.dialogTitle.textContent = task.title;
@@ -673,11 +770,48 @@ function renderDialog(task) {
   elements.dialogRelatedLinks.hidden = (
     (task.relatedGitHubLinks?.length ?? 0) === 0 && !task.relatedGitHubLinksTruncated
   );
-  elements.dialogResults.replaceChildren(...turnTimeline(detailedTask));
+  const timeline = turnTimeline(detailedTask, { highlightTurnRef });
+  elements.dialogResults.replaceChildren(...timeline);
+  const highlightedTurn = timeline.find((item) => item.dataset.turnRef === highlightTurnRef) ?? null;
+  const replacedFocusedTurn = timeline.find((item) => item.dataset.turnRef === focusedTurnRef) ?? null;
+  if (replacedFocusedTurn) {
+    const pathMatchedElement = descendantAtPath(replacedFocusedTurn, focusedDescendantPath);
+    const replacedFocusedElement = (
+      pathMatchedElement?.dataset?.focusKey === focusedDescendantKey
+        ? pathMatchedElement
+        : null
+    ) ?? descendantWithFocusKey(replacedFocusedTurn, focusedDescendantKey);
+    if (replacedFocusedElement && replacedFocusedElement !== replacedFocusedTurn) {
+      replacedFocusedElement.focus?.();
+    } else {
+      replacedFocusedTurn.tabIndex = -1;
+      replacedFocusedTurn.focus?.();
+    }
+  }
+  const currentTurnRef = task.turnRef ?? task.latestTurn?.turnRef ?? null;
+  const preservedUsageIsPriorGeneration = task.usage == null
+    && preservedUsage != null
+    && currentTurnRef != null
+    && preservedUsage.generationTurnRef !== currentTurnRef;
+  const taskUsage = detailedTask.usage?.task
+    && (detailedTask.usage.status === "available" || task.status === "working")
+    && (!preservedUsageIsPriorGeneration || task.status === "working")
+    ? {
+      status: "available",
+      ...detailedTask.usage.task,
+      knownSoFar: task.status === "working",
+    }
+    : detailedTask.usage?.status === "calculating" || preservedUsageIsPriorGeneration
+      ? { ...detailedTask.usage, status: task.status === "working" ? "pending" : "calculating" }
+      : detailedTask.usage ?? {
+        status: task.status === "working"
+          ? "pending"
+          : task.threadId
+            ? "calculating"
+            : "unavailable",
+      };
   elements.dialogUsage.replaceChildren(usagePresentation(
-    task.usage?.status === "available" && task.usage.task
-      ? { status: "available", ...task.usage.task }
-      : task.usage ?? { status: task.threadId ? "calculating" : "unavailable" },
+    taskUsage,
     { wholeTask: true },
   ));
   elements.dialogInstruction.textContent = task.instruction;
@@ -722,12 +856,31 @@ function renderDialog(task) {
     archived ? `${task.title} is archived in Codex` : `Archive ${task.title} in Codex`,
   );
   renderManualTransition(detailedTask);
+  return highlightedTurn;
 }
 
-async function openDialog(task) {
+async function openDialog(task, {
+  focus = false,
+  highlightTurnRef = null,
+  preserveNavigation = false,
+} = {}) {
+  if (focus) {
+    state.detailNavigation = {
+      focusPending: true,
+      highlightTurnRef,
+      taskId: task.id,
+    };
+  } else if (!preserveNavigation) state.detailNavigation = null;
+  const navigation = state.detailNavigation?.taskId === task.id
+    ? state.detailNavigation
+    : null;
+  const activeHighlightTurnRef = navigation?.highlightTurnRef ?? highlightTurnRef;
   const requestGeneration = ++detailRequestGeneration;
-  renderDialog(task);
-  if (!elements.dialog.open) elements.dialog.showModal();
+  renderDialog(task, { highlightTurnRef: activeHighlightTurnRef });
+  if (!elements.dialog.open) {
+    elements.dialog.showModal();
+    renderNotifications();
+  }
   const load = async (attempt = 0) => {
     try {
       const response = await fetch(`/api/tasks/${encodeURIComponent(task.id)}`);
@@ -738,14 +891,34 @@ async function openDialog(task) {
         && state.selectedTask?.id === task.id
         && elements.dialog.open
       ) {
-        renderDialog(detail.task);
+        const activeNavigation = state.detailNavigation?.taskId === task.id
+          ? state.detailNavigation
+          : null;
+        const highlightedTurn = renderDialog(detail.task, {
+          highlightTurnRef: activeNavigation?.highlightTurnRef ?? activeHighlightTurnRef,
+        });
+        if (activeNavigation?.focusPending) {
+          (highlightedTurn ?? elements.dialogTitle).focus?.();
+          activeNavigation.focusPending = false;
+        }
         if (usageStillCalculating(detail.task) && attempt < MAX_USAGE_POLL_ATTEMPTS) {
           setTimeout(() => load(attempt + 1), USAGE_POLL_INTERVAL_MS);
         }
       }
     } catch {
-      if (state.selectedTask?.id === task.id) {
+      if (
+        requestGeneration === detailRequestGeneration
+        && state.selectedTask?.id === task.id
+        && elements.dialog.open
+      ) {
         showMessage("Task activity timeline is temporarily unavailable.");
+        const activeNavigation = state.detailNavigation?.taskId === task.id
+          ? state.detailNavigation
+          : null;
+        if (activeNavigation?.focusPending) {
+          elements.dialogTitle.focus?.();
+          activeNavigation.focusPending = false;
+        }
       }
     }
   };
@@ -869,7 +1042,7 @@ function applySnapshot(snapshot) {
   );
   if (state.selectedTask) {
     const updated = state.tasks.find((task) => task.id === state.selectedTask.id);
-    if (updated && elements.dialog.open) openDialog(updated);
+    if (updated && elements.dialog.open) openDialog(updated, { preserveNavigation: true });
   }
   renderNotifications(reconciled.additions);
   render();
@@ -924,6 +1097,8 @@ elements.dialog.addEventListener("cancel", (event) => {
 });
 elements.dialog.addEventListener("close", () => {
   if (!manualTransitionPending()) state.manualTransition = null;
+  state.detailNavigation = null;
+  renderNotifications();
 });
 elements.moreTaskActions.addEventListener("click", () => {
   const task = state.selectedTask;

package/src/dashboard/index.html

@@ -87,14 +87,16 @@
       </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>
-      <p id="notification-announcer" class="visually-hidden" role="status" aria-live="polite"></p>
-      <div id="toast-list" class="toast-list"></div>
-    </aside>
+    <div id="notification-host">
+      <aside id="notifications" class="notifications" aria-label="Task notifications" popover="manual">
+        <div class="notifications-heading">
+          <strong>Updates</strong>
+          <button id="clear-notifications" class="text-button" type="button">Clear all</button>
+        </div>
+        <p id="notification-announcer" class="visually-hidden" role="status" aria-live="polite"></p>
+        <div id="toast-list" class="toast-list"></div>
+      </aside>
+    </div>
 
     <dialog id="task-dialog" aria-labelledby="dialog-title">
       <div class="dialog-header">

package/src/dashboard/styles.css

@@ -134,7 +134,7 @@ time, .timestamp-missing { font-size: 0.75rem; }
 .dashboard-message span { flex: 1; }
 .dashboard-message .icon-button { flex: none; padding: 4px 7px; color: inherit; }
 
-.notifications { position: fixed; right: 20px; bottom: 20px; z-index: 3; width: min(380px, calc(100vw - 40px)); padding: 14px; border: 1px solid var(--border); border-radius: 10px; background: var(--surface); box-shadow: var(--shadow); }
+.notifications { position: fixed; inset: auto 20px 20px auto; width: min(380px, calc(100vw - 40px)); margin: 0; padding: 14px; border: 1px solid var(--border); border-radius: 10px; background: var(--surface); color: var(--text); box-shadow: var(--shadow); }
 .notifications-heading { display: flex; justify-content: space-between; align-items: center; margin-bottom: 8px; }
 .toast-list { display: grid; gap: 7px; max-height: 50vh; overflow: auto; }
 .toast { display: flex; align-items: flex-start; gap: 8px; padding: 10px; border-radius: 7px; background: var(--surface-muted); }
@@ -170,6 +170,7 @@ dialog section + section { margin-top: 24px; }
 .result-history { display: grid; gap: 10px; }
 .result-history-item { padding: 13px 14px; border: 1px solid var(--border); border-radius: 8px; background: var(--surface-muted); }
 .result-history-latest { border-color: var(--accent); background: var(--accent-soft); box-shadow: inset 3px 0 var(--accent); }
+.result-history-notified { outline: 3px solid color-mix(in srgb, var(--accent) 35%, transparent); outline-offset: 2px; }
 .result-history-header { display: flex; align-items: center; justify-content: space-between; gap: 12px; margin-bottom: 9px; }
 .result-history-header .timestamp-toggle { margin-left: auto; }
 .result-history-source { color: var(--muted); font-size: 0.72rem; font-weight: 700; }
@@ -181,10 +182,24 @@ dialog section + section { margin-top: 24px; }
 .usage-panel { margin-top: 8px; }
 .usage-summary { display: grid; gap: 3px; margin: 10px 0 4px; color: var(--muted); font-size: 0.8rem; }
 .usage-summary strong { color: var(--text); font-size: 0.9rem; }
-.usage-calculating { display: flex; align-items: center; gap: 7px; }
-.usage-spinner { width: 12px; height: 12px; border: 2px solid var(--border); border-top-color: var(--accent); border-radius: 50%; animation: usage-spin 0.8s linear infinite; }
-@keyframes usage-spin { to { transform: rotate(360deg); } }
-@media (prefers-reduced-motion: reduce) { .usage-spinner { animation: none; border-top-color: var(--border); background: var(--accent); } }
+.usage-pending, .usage-calculating { display: flex; align-items: center; }
+.usage-shimmer {
+  color: var(--muted);
+  background: linear-gradient(100deg, var(--muted) 35%, var(--text) 50%, var(--muted) 65%);
+  background-size: 250% 100%;
+  background-position: 100% 0;
+  background-clip: text;
+  -webkit-background-clip: text;
+  -webkit-text-fill-color: transparent;
+  animation: usage-shimmer 2.8s ease-in-out infinite;
+}
+@keyframes usage-shimmer {
+  0% { background-position: 100% 0; }
+  72%, 100% { background-position: -100% 0; }
+}
+@media (prefers-reduced-motion: reduce) {
+  .usage-shimmer { background: none; animation: none; -webkit-text-fill-color: currentcolor; }
+}
 pre { max-height: 280px; margin: 0; padding: 14px; overflow: auto; border-radius: 7px; background: var(--surface-muted); white-space: pre-wrap; overflow-wrap: anywhere; font: 0.86rem/1.55 ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; }
 .metadata { display: grid; grid-template-columns: minmax(100px, 150px) 1fr; margin: 0; font-size: 0.88rem; }
 .metadata dt, .metadata dd { padding: 7px 0; border-bottom: 1px solid var(--border); overflow-wrap: anywhere; }