taskchef 7.19.1 → 7.21.0

package/.codex-plugin/plugin.json

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

package/README.md

@@ -25,6 +25,12 @@ request -> recorded TaskChef task -> Codex executor -> request/result turn timel
 TaskChef requires Node.js 18 or newer, Git, Codex desktop, and local access to
 the projects that will receive work.
 
+Install [`ccusage`](https://github.com/ccusage/ccusage) separately when you want
+the optional dashboard token and API-equivalent cost estimates. TaskChef calls
+its structured offline Codex report and does not parse Codex rollout files
+itself. Lifecycle reporting and the dashboard continue to work when `ccusage`
+is absent or incompatible.
+
 ```sh
 codex plugin marketplace add favoyang/codex-plugins
 codex plugin add taskchef@favoyang-plugins
@@ -49,7 +55,8 @@ The canonical workspace is `~/.agents/taskchef`. TaskChef owns only:
 ```text
 AGENTS.md       managed dispatcher instructions plus user additions
 taskchef.json   schema-2 Codex project index, dashboard preference, and delegation metadata
-tasks.jsonl     one task snapshot per line (schema 9; schema 4-8 migration supported)
+tasks.jsonl     one task snapshot per line (schema 10; schema 4-9 migration supported)
+.taskchef-usage.json   optional mode-0600 ccusage snapshot and turn-boundary cache
 ```
 
 Index or inspect Codex projects conversationally:
@@ -263,12 +270,36 @@ The loopback dashboard watches `tasks.jsonl`, groups current states, and opens
 linked Codex tasks. List snapshots and SSE events carry only the latest
 request/result pair; opening task details fetches the full newest-first activity
 timeline, including clearly labeled interrupted turns.
-Task details also offer **Archive chat** for every linked task whose current
+Task details offer infrequent administrative actions without cluttering task
+cards. Selecting **More task actions** (`…`) reveals the action list immediately
+beside the disclosure and changes it to a back/hide control. The list contains
+**Copy Task ID**, direct **Mark completed** and **Mark failed** actions for a
+`working` or `needs_input` task, and **Archive chat** whenever archival is
+eligible. The menu disclosure is the deliberate first step; choosing a terminal
+outcome submits it immediately without a second confirmation. There is no
+free-form reason: the audit turn records a fixed summary, timestamp, dashboard
+provenance, optimistic preconditions, and a unique action ID while preserving
+every executor turn. Terminal tasks cannot be rewritten. Stale or concurrent
+changes are rejected and the dialog refreshes to the current task. A stalled
+local request is aborted after a bounded wait so the dialog cannot remain
+permanently locked; retry keeps the same idempotency identity.
+
+The More actions list offers **Archive chat** for every linked task whose current
 TaskChef state is not `working`. After confirmation, TaskChef invokes only the
 Codex CLI at the canonical ChatGPT or Codex desktop app location under
 `/Applications`, to archive the exact thread UUID. The Codex chat leaves active chat lists while the TaskChef record
 and its activity timeline remain unchanged. If the bundled CLI is unavailable,
 the dashboard does not fall back to another `codex` executable from `PATH`.
+
+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
+the terminal lifecycle callback precedes Codex's final output write. Historical
+tasks may show a trustworthy task total while older turns remain “Tokens
+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; zero-priced unknown models show
+cost unavailable rather than a misleading `$0.00`.
 The header shows the running TaskChef package version reported by the same
 bounded health identity used for compatible-listener checks.
 The canonical port is owned by a dashboard initialized in the TaskChef MCP host
@@ -286,12 +317,13 @@ revision, so reconnects and non-semantic rewrites do not replay a notice and a
 later task state cannot rewrite an older notice. A notice remains readable if
 its task disappears; selecting it then explains that current details are no
 longer available.
-It does not mutate TaskChef data and prints its local URL. A foreground
-dashboard identifies itself as standalone and is never reused on the canonical
-MCP port. If a standalone, unknown, different-workspace, or stale-version
-process owns port 3210, 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`.
+Apart from an explicit manual state selection from the task-detail menu, it does not mutate
+TaskChef data and prints its local URL. A foreground dashboard identifies
+itself as standalone and is never reused on the canonical MCP port. If a
+standalone, unknown, different-workspace, or stale-version process owns port
+3210, 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, canonical workspace, and launcher.
@@ -304,6 +336,8 @@ or secrets.
 
 ![Task detail activity timeline](docs/images/result-history-dashboard.jpg)
 
+![Deferred ccusage token consumption in task details](docs/images/ccusage-token-consumption.png)
+
 ![Interrupted turn followed by active recovery](docs/images/interrupted-turn-recovery.jpg)
 
 ## Common recovery
@@ -319,9 +353,9 @@ taskchef doctor
 
 `doctor` is read-only. `workspace init` creates missing files and refreshes
 managed instructions. `workspace migrate` explicitly upgrades supported schema
-4-8 task lines to schema 9 under the workspace lock. It validates task and turn
+4-9 task lines to schema 10 under the workspace lock. It validates task and turn
 counts plus the complete source and converted log before writing, creates an
-exclusive `tasks.jsonl.pre-v9-*.bak`
+exclusive `tasks.jsonl.pre-v10-*.bak`
 backup, atomically replaces the log, validates the result, and becomes an
 idempotent no-op after migration. If replacement fails, the original remains
 or the reported backup can be restored; unsupported or invalid input is rejected
@@ -332,7 +366,7 @@ executor so its first action can retry `link_task`. Do not guess an identity
 or edit `tasks.jsonl`. If native task creation failed, the record is retained
 as `failed` with a retained fallback `turnRef` and null thread and Codex turn IDs.
 
-Schemas other than 4, 5, 6, 7, 8, and 9 remain unsupported. Retain such a workspace
+Schemas other than 4, 5, 6, 7, 8, 9, and 10 remain unsupported. Retain such a workspace
 unchanged and create a current workspace; the migration command deliberately
 does not guess how to convert unknown formats.
 

package/docs/spec.md

@@ -28,7 +28,7 @@ is dated research, not contract.
 | **Last semantic result** | The final result-history entry, exposed through the derived `lastResult` compatibility alias. |
 | **Turn reference** | Required lifecycle identity for one executor prompt. It is the native Codex turn ID when available, otherwise a retained client-generated UUID. |
 | **Current turn ID** | Optional Codex metadata for the reported prompt; null when native turn reading is unavailable. |
-| **Dashboard** | The loopback, read-only UI derived from validated workspace snapshots and bounded native actions. |
+| **Dashboard** | The loopback UI derived from validated workspace snapshots, with optional local usage projections, bounded native actions, and an explicit audited manual-outcome mutation. |
 | **Skill** | One packaged agent procedure: `taskchef-bootstrap`, `taskchef-dashboard`, `taskchef-delegate`, `taskchef-executor`, or `taskchef-copilot`. |
 
 ## Components and ownership
@@ -50,13 +50,15 @@ is dated research, not contract.
   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.
+- The dashboard MUST be read-only with respect to dispatcher files except for
+  the explicit audited manual-transition operation defined below.
 - `docs/spec.md` is the single normative behavior source. Other documents
   MUST link here rather than redefine the contract.
 
 ## Workspace contract
 
-TaskChef MUST manage only `AGENTS.md`, `taskchef.json`, and `tasks.jsonl`
+TaskChef MUST manage only `AGENTS.md`, `taskchef.json`, `tasks.jsonl`, and the
+optional `.taskchef-usage.json` cache
 inside the dispatcher workspace. It MUST preserve unrelated paths.
 
 `taskchef.json` MUST have schema version 2, the following required fields, and
@@ -81,8 +83,8 @@ is backward-compatible and means `true`; new workspaces SHOULD write
 disable the explicit `ensure_dashboard` tool.
 
 `tasks.jsonl` MUST contain zero or more newline-terminated schema-4 through
-schema-9 records, one per line. Schemas 4 through 8 are supported
-migration/read formats; every new record and state mutation MUST write schema 9. Other schemas
+schema-10 records, one per line. Schemas 4 through 9 are supported
+migration/read formats; every new record and state mutation MUST write schema 10. Other schemas
 or unsupported fields MUST be rejected without conversion.
 Reads and writes MUST reject symlinked managed files. Mutations
 MUST hold the shared workspace lock and replace state atomically; read-only
@@ -94,7 +96,7 @@ Every record MUST contain exactly these fields:
 
 | Field | Contract |
 | --- | --- |
-| `schemaVersion` | Integer `9`; schema-4/5/6/7/8 records remain readable until explicit migration or their next mutation. |
+| `schemaVersion` | Integer `10`; schema-4/5/6/7/8/9 records remain readable until explicit migration or their next mutation. |
 | `id` | Unique safe TaskChef ID; delegation uses a lowercase full UUID. |
 | `project` | Immutable configured-project snapshot. |
 | `title` | Non-empty display title. |
@@ -106,16 +108,64 @@ Every record MUST contain exactly these fields:
 | `turnRef` | Null before reporting begins; otherwise the required lifecycle identity of the current turn. Self-linking journeys use a native or fallback UUID. Migrated low-level `report_result` compatibility records may retain an opaque ref equal to their opaque `turnId`. |
 | `turnId` | Optional Codex metadata. When non-null it equals `turnRef`; null indicates fallback identity. |
 | `updatedAt` | ISO 8601 timestamp not earlier than `createdAt` or the prior `updatedAt`; clock rollback cannot backdate a transition. |
-| `updatedBy` | `dispatcher` or `mcp`. |
-| `turns` | Ordered oldest-first array of `{turnRef, turnId, requestSummary, startedAt, result}`. Every `turnRef` is required. `requestSummary` is null only for migrated/compatibility turns. `result` is null only for the latest working turn, a semantic `{status, summary, updatedAt}` result, or the fixed TaskChef `interrupted` outcome. New self-linking turn refs are unique. A migrated low-level opaque record may retain one final reused native-derived ref for its legacy ambiguity. |
+| `updatedBy` | `dispatcher`, `mcp`, or `dashboard`. `dashboard` is valid only when the latest turn is a manual dashboard transition. |
+| `turns` | Ordered oldest-first array of `{turnRef, turnId, requestSummary, startedAt, result, provenance}`. Every `turnRef` is required. `requestSummary` is null only for migrated/compatibility turns. `result` is null only for the latest working turn, a semantic `{status, summary, updatedAt}` result, or the fixed TaskChef `interrupted` outcome. `provenance` is `{kind: legacy}` or `{kind: mcp}` for ordinary turns, or the audited manual-transition record defined below. New self-linking and manual turn refs are unique. A migrated low-level opaque record may retain one final reused native-derived ref for its legacy ambiguity. |
 
 Returned Task objects MUST additionally expose `latestTurn` as null for an empty
 timeline or the final `turns` entry. They MUST derive `results` only from
 semantic `needs_input`, `completed`, and `failed` turn results and `lastResult`
 from the final derived semantic result. Interrupted outcomes MUST be excluded.
-These projections MUST NOT be persisted in schema 9 and remain compatibility
+These projections MUST NOT be persisted in schema 10 and remain compatibility
 aliases for existing callers.
 
+## Optional usage projection
+
+TaskChef MAY invoke an installed `ccusage` executable as an optional local
+adapter using `ccusage codex session --json --offline`. TaskChef MUST NOT parse,
+store, or serve raw Codex rollout files, prompts, responses, transcripts, or
+reasoning. Analyzer absence, timeout, malformed output, unknown pricing, or an
+unresolved thread MUST NOT block lifecycle tools or dashboard loading.
+
+Dashboard-manual turns are administrative events, not Codex executions. They
+MUST immediately report per-turn usage as unavailable, MUST NOT schedule or
+store a cumulative usage boundary, and MUST NOT receive a token or cost delta.
+A later executor turn MUST use the nearest preceding reliable executor
+boundary, skipping any intervening dashboard-manual turns.
+
+The mode-0600 `.taskchef-usage.json` cache stores only normalized cumulative
+token boundaries, per-turn deltas, model names, estimated cost, source version,
+and freshness. It is independent of task-log schema versions so legacy logs remain
+readable. Writes MUST use the workspace lock and atomic replacement. Symlinked
+or unsupported cache files MUST be rejected. Writes MUST compact the derived
+cache to recent task projections, recent per-turn results, and the latest
+cumulative boundary. An oversized legacy cache MUST be treated as rebuildable
+derived data so it cannot permanently disable usage reporting.
+
+A linked Codex thread MAY map to multiple ccusage session segments. TaskChef
+MUST aggregate only records whose primary durable thread UUID is that exact
+identity; a UUID appearing only as a nested suffix MUST NOT be attributed to
+the parent or child TaskChef task. It MUST retain input, cached-input, output,
+reasoning-output, and total fields without adding cached or reasoning subsets
+into totals a second time.
+
+After a terminal report, TaskChef MUST mark the turn `calculating` and perform
+bounded deferred reconciliation without delaying the lifecycle response.
+Per-turn usage MUST be a non-negative delta between adjacent reliable cumulative
+boundaries. A first recorded turn MAY use zero as its baseline. Historical
+turns without boundaries and decreasing or ambiguous snapshots MUST be labeled
+`unavailable`, never zero or estimated. A historical task MAY still show its
+resolvable cumulative total. A boundary is reliable only after two consecutive
+samples agree. Exhausted unstable sampling and a newer turn beginning before
+stabilization MUST leave that turn unavailable and MUST NOT establish a delta
+baseline. Zero is valid for the first turn only when TaskChef observed that turn
+in progress before its terminal report; a first historical terminal turn MUST
+remain unavailable even when its cumulative task total is resolvable.
+
+Every available projection MUST identify ccusage, its version when available,
+and freshness. Dollar values MUST be labeled API-equivalent estimates. Positive
+token usage with a zero or missing analyzer cost MUST display cost unavailable,
+not `$0.00`.
+
 Task IDs and non-null thread identities MUST be unique. The immutable intent
 fields MUST NOT change after recording.
 
@@ -307,7 +357,7 @@ new preparation values, though it writes no state.
 
 **Structured output:** `{ task: Task }`.
 
-The returned task has schema 9, `working`, null summary/turn/thread/latestTurn/lastResult,
+The returned task has schema 10, `working`, null summary/turn/thread/latestTurn/lastResult,
 empty `turns` and derived `results` arrays,
 `updatedBy: dispatcher`, and equal creation/update timestamps. Duplicate IDs,
 unknown projects, malformed markers, and invalid input fail. Repeating a
@@ -384,8 +434,8 @@ MUST contain no crash output, transcript, user text, or inferred failure cause.
 temporary compatibility alias. It implicitly accepts a fresh supplied turn and
 stores its semantic result in a request-unknown turn, including for supported schema-4/5/6 records and
 low-level opaque direct records. It does not accept `working`. New executor
-instructions MUST use `report_state`. Successful mutation upgrades schema 4-8
-to schema 9; unsupported schemas remain rejected. Legacy callers that omit
+instructions MUST use `report_state`. Successful mutation upgrades schema 4-9
+to schema 10; unsupported schemas remain rejected. Legacy callers that omit
 `turnRef` remain compatible when `turnId` is non-null.
 
 ## Copilot and dashboard
@@ -433,6 +483,41 @@ 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.
+The task-detail dashboard MAY offer manual terminal outcomes only for current
+`working` or `needs_input` tasks. It MUST permit exactly `completed` and
+`failed`, MUST NOT rewrite a terminal task, and MUST keep this infrequent
+administrative action out of list cards. A keyboard-accessible **More task
+actions** disclosure MUST reveal its action list immediately beside it and
+change from an ellipsis to an accessible back/hide control while expanded. The
+list MUST group **Copy Task ID**, **Mark completed**, and **Mark failed** for
+eligible tasks, plus **Archive chat** when archival is eligible. Opening the
+list is the deliberate disclosure step; choosing a terminal outcome submits it
+immediately without a second confirmation. Escape MUST close the idle list,
+pending controls MUST be
+disabled, and failure feedback MUST remain in the dialog. Pending state MUST
+focus and announce a stable status inside the dialog. Failed MUST have
+destructive styling. The client MUST bound and abort a stalled manual-transition
+request, restore the dialog controls, and preserve the action ID so a retry can
+resolve idempotently if the server committed before the timeout.
+
+`POST /api/tasks/:id/manual-transition` MUST require the exact loopback origin,
+`application/json`, a bounded body, and exactly this versioned shape:
+`{schemaVersion: 1, actionId, expected: {status, turnRef, threadId, updatedAt},
+targetStatus}`. The server MUST compare every expected field while holding the
+workspace lock. A stale request, invalid transition, or reused action ID with a
+different operation MUST return a conflict without mutation. Replaying the
+same committed action ID and operation MUST return the current task as an
+idempotent success. The operation MUST atomically append one new manual turn;
+it MUST NOT overwrite executor history. An active unfinished turn MUST first
+receive the standard interrupted timeline outcome. The manual turn MUST have a
+new server-generated `turnRef`, null `turnId`, one monotonic timestamp for its
+start, result, and task update, `updatedBy: dashboard`, and deterministic
+request/result summaries. It MUST record provenance
+`{kind: dashboard_manual, actionId, fromStatus, toStatus, expectedTurnRef,
+expectedThreadId, expectedUpdatedAt}`. No free-form reason is collected or
+persisted. A committed write remains successful if the subsequent best-effort
+monitor refresh or notification delivery fails.
+
 The task-detail dashboard MAY offer Codex chat archival only when the stored
 thread ID is a canonical Codex UUID and the current TaskChef state is not
 `working`. It MUST revalidate both conditions for the POST request, require the
@@ -478,15 +563,15 @@ its displayed summary when present, event time, and missing-task state.
 
 ## Task-log migration
 
-`workspace migrate` MUST explicitly convert every supported schema-4/5/6/7/8 record
+`workspace migrate` MUST explicitly convert every supported schema-4/5/6/7/8/9 record
 under the shared lock. Each legacy semantic result becomes a request-unknown
 completed turn; a newer working state becomes a final unfinished turn, and a
 schema-7/8 timeline is preserved. Each non-null legacy `turnId` becomes the
 same `turnRef`; each null legacy `turnId` receives one durably persisted UUID.
 Migration MUST validate the complete source, record/turn counts, turn-ref
-invariants, and complete schema-9 candidate before changing the task log,
+invariants, and complete schema-10 candidate before changing the task log,
 create and read back an exclusive recovery backup, atomically replace the log,
-and validate the installed result. A fully schema-9 log MUST be an idempotent
+and validate the installed result. A fully schema-10 log MUST be an idempotent
 no-op without another backup. Invalid/unsupported input MUST remain untouched;
 failures after backup creation MUST report the backup path and MUST never
 partially rewrite individual lines.

package/docs/workflows.md

@@ -21,6 +21,8 @@ research.
 | `src/cli.js` | Administration, normalized cached briefs, inspection, diagnostics, and dashboard startup. |
 | `src/dashboard.js` | Versioned health identity, validated compact snapshots, SSE fan-out, on-demand details, and bounded open actions. |
 | `src/dashboard-manager.js` | Concurrent singleton ensure, exact listener reuse, conflicts, and owned shutdown. |
+| `src/usage.js` | Optional bounded ccusage execution, exact primary-thread mapping, normalized aggregation, and the private usage cache. |
+| `src/usage-tracker.js` | Deferred sampling, cumulative boundaries, historical availability, and per-turn deltas. |
 
 The MCP process resolves `TASKCHEF_WORKSPACE` once and never accepts a model
 supplied path. The CLI resolves `--workspace`, then the environment, then the
@@ -114,7 +116,7 @@ sequenceDiagram
   D->>D: Choose one configured and native project
   D->>M: record_task(id, project, title, instruction, null)
   M->>W: recordTask()
-  W->>W: Lock, validate, append schema-9 snapshot
+  W->>W: Lock, validate, append schema-10 snapshot
   W-->>M: working link-pending task
   M-->>D: task
   D->>C: Create executor with marked instruction
@@ -258,7 +260,7 @@ sequenceDiagram
   W->>W: Acquire workspace lock and validate turnRefB is new
   W->>W: Close unfinished turnA as interrupted
   W->>W: Append turnB with requestB and null result
-  W->>F: One atomic schema-9 replacement
+  W->>F: One atomic schema-10 replacement
   W-->>M: working task projected from turnB
   M-->>E: Idempotent recovery success
   E->>M: late semantic result for turnA
@@ -394,16 +396,17 @@ all, and ordinary rerendering do not re-announce retained history. Toast action
 labels remain concise while `aria-describedby` connects the visible summary,
 event time, and missing-task explanation for assistive technology.
 
-## Schema 4-8 migration
+## Schema 4-9 migration
 
 `taskchef workspace migrate` acquires the same workspace lock as lifecycle
 writers, validates the complete legacy log, converts schema-4/5/6 results into
 request-unknown completed turns and preserves a newer working turn, then validates the
 complete candidate. Before replacement it writes and reads back an exclusive
-`tasks.jsonl.pre-v9-*.bak` file. Schema-7/8 timelines gain a durable `turnRef`:
+`tasks.jsonl.pre-v10-*.bak` file. Schema-7/8 timelines gain a durable `turnRef`:
 non-null `turnId` values are copied exactly and null IDs receive persisted UUIDs.
 Task and turn counts plus all refs are validated before and after the atomic
-replacement. A second run sees only schema 9 and returns unchanged without
+replacement. Schema-9 turns gain explicit legacy or MCP provenance. A second
+run sees only schema 10 and returns unchanged without
 another backup. Unsupported or malformed input fails before backup/rewrite;
 after a later filesystem failure, the reported backup is the recovery source.
 
@@ -420,9 +423,10 @@ summary is cryptographically authenticated; this is a local single-user trust
 model. Managed files, instructions, project snapshots, MCP inputs, and dashboard
 requests are validated at every action boundary.
 
-Configuration schema 2 and task schemas 4 through 9 are accepted. Schemas
-4-8 are read/migration compatibility until an explicit migration or lifecycle
-mutation upgrades each record to schema 9. Schema 9 persists `turns`, including
+Configuration schema 2 and task schemas 4 through 10 are accepted. Schemas
+4-9 are read/migration compatibility until an explicit migration or lifecycle
+mutation upgrades each record to schema 10. Schema 10 persists `turns`, including
 timeline-only interrupted outcomes, and derives semantic-only `results` and
-`lastResult` plus `latestTurn` for compact compatibility. Other schemas
+`lastResult` plus `latestTurn` for compact compatibility. It also records turn
+provenance and the optimistic preconditions for manual dashboard outcomes. Other schemas
 are rejected without rewrite.

package/index.js

@@ -12,6 +12,7 @@ export {
   initializeWorkspace,
   linkTask,
   listProjects,
+  manuallyTransitionTask,
   migrateTaskLog,
   prepareDispatch,
   readConfig,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "taskchef",
-  "version": "7.19.1",
+  "version": "7.21.0",
   "description": "A non-blocking interactive dispatcher for visible Codex tasks.",
   "license": "MIT",
   "author": "Favo Yang",
@@ -27,6 +27,7 @@
     "docs/workflows.md",
     "docs/firstmate-taskchef-comparison.md",
     "docs/images/dashboard-identity.jpg",
+    "docs/images/ccusage-token-consumption.png",
     "docs/images/notification-event-snapshots.jpg",
     "docs/images/result-history-dashboard.jpg",
     "docs/images/interrupted-turn-recovery.jpg",

package/src/dashboard/actions.js

@@ -53,3 +53,84 @@ export async function archiveTaskFromControl(event, task, {
     if (!archived) control.disabled = false;
   }
 }
+
+export async function manuallyTransitionTaskFromControl(event, task, targetStatus, actionId, {
+  clearTimer = globalThis.clearTimeout,
+  fetchAction = globalThis.fetch,
+  setTimer = globalThis.setTimeout,
+  timeoutMs = 10_000,
+} = {}) {
+  event?.stopPropagation?.();
+  const controller = new AbortController();
+  const timeout = setTimer(() => controller.abort(), timeoutMs);
+  try {
+    const response = await fetchAction(
+      `/api/tasks/${encodeURIComponent(task.id)}/manual-transition`,
+      {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          schemaVersion: 1,
+          actionId,
+          expected: {
+            status: task.status,
+            turnRef: task.turnRef,
+            threadId: task.threadId,
+            updatedAt: task.updatedAt,
+          },
+          targetStatus,
+        }),
+          signal: controller.signal,
+        },
+    );
+    const result = await response.json();
+    return response.ok
+      ? { ok: true, ...result }
+      : {
+        ok: false,
+        code: result.code ?? "dashboard_error",
+        message: result.message ?? "Task state could not be changed.",
+        task: result.task ?? null,
+      };
+  } catch {
+    return {
+      ok: false,
+      code: controller.signal.aborted ? "request_timeout" : "network_error",
+      message: controller.signal.aborted
+        ? "Task state change timed out. Try again."
+        : "Task state changes are temporarily unavailable. Try again.",
+      task: null,
+    };
+  } finally {
+    clearTimer(timeout);
+  }
+}
+
+export function handleManualTransitionEscape(event, {
+  active,
+  pending,
+  cancel,
+}) {
+  if (event.key !== "Escape" || !active) return false;
+  event.preventDefault();
+  event.stopPropagation();
+  if (!pending) cancel();
+  return true;
+}
+
+export function focusManualTransitionStatus(panel) {
+  const status = panel.querySelector('[data-manual-focus="pending"]');
+  status?.focus();
+  return status !== null;
+}
+
+export function restoreTaskActionMenuFocus(panel, activeElement, fallback) {
+  if (!activeElement || !panel.contains(activeElement)) return null;
+  if (!activeElement.hidden && !activeElement.disabled) return activeElement;
+  const copyTaskId = panel.querySelector('[data-manual-focus="copy"]');
+  const destination = copyTaskId && !copyTaskId.hidden && !copyTaskId.disabled
+    ? copyTaskId
+    : fallback;
+  destination?.focus();
+  return destination ?? null;
+}