taskchef 8.7.1 → 9.0.0

package/docs/advanced-guide.md

@@ -1,497 +0,0 @@
-# TaskChef advanced guide
-
-Detailed setup, operation, recovery, and development reference for TaskChef.
-
-## Install
-
-TaskChef requires Node.js 18 or newer, Git, Codex desktop, and local access to
-the projects that will receive work.
-
-TaskChef uses its own accounting engine for token usage and API-equivalent cost
-estimates. Usage requires Node.js 22.18+ and readable local Codex records.
-It includes linked subagents and uses the same pricing data as the board.
-Lifecycle reporting and the dashboard continue to work when usage is unavailable.
-
-```sh
-codex plugin marketplace add favoyang/codex-plugins
-codex plugin add taskchef@favoyang-plugins
-```
-
-The plugin provides five skills and a local MCP server. Its skills use the CLI
-bundled with the plugin, so a global npm installation is not needed for the
-dispatcher workflow. To run `taskchef` directly from a terminal, install the
-CLI separately:
-
-```sh
-npm install --global taskchef
-```
-
-TaskChef installs no hooks, schedules, daemons, login items, system services,
-or background identity search and needs no elevated permissions.
-
-## Bootstrap and index projects
-
-For the first run, ask the bootstrap skill to create and verify the per-user
-dispatcher and import saved local Codex projects:
-
-```text
-$taskchef-bootstrap Set up TaskChef and index my local Codex projects.
-```
-
-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 10; schema 4-9 migration supported)
-.taskchef-usage.json   optional mode-0600 normalized usage cache
-```
-
-To inspect or manually adjust the project index later, use the bootstrap skill:
-
-```text
-$taskchef-bootstrap List my indexed Codex projects.
-$taskchef-bootstrap Index /workspace/payments as payments. It owns authorization, capture, refunds, and retries.
-$taskchef-bootstrap Reindex after the Codex projects I added today.
-```
-
-TaskChef indexes existing Codex projects for delegation. The index stores
-canonical paths and routing metadata; it never indexes repository contents or
-creates another kind of project. For a folder already saved as a local Codex
-project, the bootstrap skill requires an exact canonical-path match before
-writing and verifying its TaskChef index entry. For a new folder, or an existing
-folder not yet saved by Codex, it creates the directory only when explicitly
-requested, opens the canonical path with the validated Codex Desktop CLI's
-`codex app <path>` mechanism, re-lists native projects, and requires the same
-exact match before indexing it. An open request without a verified native
-project is reported as partial setup, not delegation-ready.
-
-Update one indexed project with taskchef project update; repeated
---github-repo values replace that entry's complete repository list while
-leaving every other project untouched. project list --json returns stable
-configuration and project-set hashes for postcondition checks.
-
-Whole-index replacement, project removal, and restore are preview-bound. Run
-them with --dry-run, inspect the exact diff, then apply with the returned
-hashes, counts, plan hash, and exact removed-name confirmation after the user
-approves every removed project. TaskChef creates private snapshots under
-backups/ before mutations and actual dashboard startup. Use taskchef backup
-list, create, verify, restore, and prune; restore never runs automatically and
-creates a pre-restore safety snapshot. If the live configuration is missing or
-malformed, preview an explicit config or state restore, then bind the apply to
-the preview's raw-state hash and plan with --confirm-unreadable-current.
-
-The dispatcher also reconciles saved Codex projects automatically before each
-delegation batch. You do not need a separate reindex step when adding a native
-Codex project. Manual reindexing compares exact same-host canonical paths from
-one native schema-2 project snapshot.
-Reconciliation adds eligible paths and identity bindings atomically, isolates
-per-project failures, and preserves existing curated names, descriptions, and
-complete repository lists. It does not delete missing projects. Duplicate
-native IDs, duplicate canonical targets, and identity/path moves remain
-diagnostics rather than guesses.
-
-Configuration schema 2 accepts an optional strict `projectIndex` containing
-local native identity bindings, explicit exclusions, and bounded routing hints.
-Removing a project records an exclusion so reconciliation cannot silently
-re-add it; `include_project` clears an exact exclusion before a later reconcile.
-Aliases come only from explicit selection or correction. Repository ownership
-requires an inspected exact origin, and report-derived responsibilities retain
-their accepted task/thread/turn provenance. Forgetting keeps bounded suppression
-so an old report retry cannot recreate a removed hint. Older TaskChef releases
-reject this optional field; use a compatible backup before downgrading.
-
-Codex CLI resolution follows the same contract as
-`workspace init --register-codex`: an explicit `--codex-cli` path wins, then
-`TASKCHEF_CODEX_CLI`; either must be executable and support `app --help`.
-Without an override, TaskChef prefers a validated `codex` PATH candidate under
-`Contents/Resources`; otherwise it validates only the first executable `codex`
-in PATH order. It does not assume an arbitrary shell command or hard-code an
-application bundle location.
-
-Or use the CLI:
-
-```sh
-taskchef project add /workspace/payments --name payments \
-  --description "Authorization, capture, refunds, and retries."
-taskchef project list
-```
-
-The CLI command writes TaskChef metadata only; it does not query Codex. Before
-using it directly, verify that `/workspace/payments` exactly matches the
-canonical path of an existing local Codex project. The bootstrap skill performs
-that native-project check for you.
-
-A project may advertise several GitHub repositories with repeated
-`--github-repo`. Explicit values replace automatic origin detection and form
-the complete advertised list, so include the origin when it should remain
-routable. A managed `*-workspace` should advertise every relevant child or
-subrepository canonical GitHub URL, plus the workspace repository itself when
-applicable, so issue and pull-request links select the correct Codex project.
-TaskChef accepts Git roots and ordinary local folders on the same execution
-host. Unsupported configuration schemas are rejected and are never rewritten
-automatically.
-
-## Dispatch
-
-Open the TaskChef dispatcher project and ask for an outcome:
-
-```text
-In payments, fix duplicate charges after a retry, add a regression test, and report what changed.
-```
-
-From another project, invoke the delegation skill explicitly:
-
-```text
-$taskchef-delegate In payments, add structured logs for failed retries and test them.
-```
-
-The dispatcher lists native projects once per batch, reconciles that snapshot,
-then prepares a UUID and marker for each outcome, persists the task before native creation,
-creates the executor, and returns its task link. New executor instructions keep
-the assignment visible from the first line, add a concise local reporting
-authorization paragraph, leave one blank line, then place
-an explicit `$taskchef-executor` invocation immediately before the final
-correlation marker. That skill reads the executor's own `CODEX_THREAD_ID`, self-links, and
-reports lifecycle state. Independent outcomes may become separate executors;
-dependent work should stay together.
-
-Activating the TaskChef MCP process best-effort ensures the dashboard by
-default. The managed workspace instructions also retry it at the start of each
-dispatcher turn. A startup failure never blocks MCP tools, an answer, report,
-or delegation. Every dispatcher response ends with
-the stable [TaskChef Dashboard](http://127.0.0.1:3210/) link; a created-task
-directive remains on the preceding line so dispatch still returns immediately.
-
-For example, TaskChef generates this shape:
-
-```text
-Fix duplicate charges after a retry and add a regression test.
-
-Report this task and its follow-ups to my local TaskChef dashboard. Relevant private-repository links and concise work, test, and deployment results are authorized; exclude secrets.
-
-Use $taskchef-executor to execute and report this delegated TaskChef assignment.
-<!-- taskchef_id=c0f010ff-84f2-4838-a69d-0ff1f5d721d7 -->
-```
-
-### Model roles
-
-TaskChef can apply personal Orchestrator, Planner, Implementer, and Reviewer
-model preferences from `~/.codex/agents/`. Every delegated task uses the
-Orchestrator preference for its visible parent. For repository work, a combined
-investigate-or-plan-and-implement request runs fresh Planner, Implementer, and
-Reviewer subagents in that order. A direct implementation, or a later request
-to implement prior investigation, skips the Planner and runs a fresh Implementer
-and Reviewer in the same visible task. Explicit model choices take precedence
-for the role they target.
-
-## Work with and report executors
-
-Open an executor as an ordinary Codex task. Each executor reports `working`
-when a turn starts and one semantic outcome before that same turn ends:
-
-- `completed`: the requested outcome is complete;
-- `needs_input`: a real user decision or missing fact blocks progress;
-- `failed`: the executor or creation attempt ended unsuccessfully.
-
-A native approval prompt is live Codex state, not `needs_input`.
-When work starts, the executor reports a concise request summary. TaskChef
-appends a `turns` entry that pairs that request with a null result while working,
-then fills the same entry with the semantic outcome. A follow-up therefore shows
-its own request with “In progress,” never the preceding turn's result. Returned
-tasks still derive `results` and `lastResult` as compatibility projections.
-Every entry has a required `turnRef`, which is the lifecycle identity. When
-Codex exposes a native turn ID, both `turnRef` and `turnId` contain that value.
-Otherwise the executor retains a fresh UUID in `turnRef` and stores
-`turnId: null`; native turn lookup is never a prerequisite for work or reporting.
-If Codex crashes, an MCP call is lost, or the app restarts before that terminal
-report, the next newer `working` report atomically marks the unfinished turn
-`interrupted` and appends the new active turn. `interrupted` is TaskChef-authored
-timeline evidence, not semantic `failed`, and it never enters `results` or
-`lastResult`. TaskChef stores only a fixed interruption summary; it does not
-store transcripts, hidden reasoning, crash output, or other non-semantic events.
-
-Delegated tasks created by earlier TaskChef versions remain compatible: their
-inline executor protocol still parses, self-links, and may use the deprecated
-`report_result` alias. The v7 inline-paragraph named exports remain as deprecated
-historical snapshots, but new delegations use the executor skill and `report_state`.
-
-## View tasks and ask copilot
-
-The dashboard is the primary monitoring and browsing UI. Ask copilot when you
-want a concise explanation or recommendation:
-
-```text
-$taskchef-copilot Summarize recent delegated work and tell me what needs attention.
-```
-
-Copilot starts from TaskChef's normalized cached brief. It uses live Codex
-metadata only when you explicitly request fresh/live verification or a focused
-task presents a meaningful contradiction, and it never polls. It can identify
-the exact executor, explain or draft a same-assignment follow-up, and—with your
-explicit authorization—continue that existing task. It never automatically
-retries failures, interrupts working tasks, or redelegates an executor. New
-independent work still belongs to `$taskchef-delegate`. In the dispatcher, an
-explicit instruction to answer, resume, or continue a named existing task
-routes to copilot; it re-reads that exact task before sending.
-
-The former `$taskchef-report` skill is not packaged as an alias because a
-second discoverable skill would preserve ambiguous behavior. Explicit
-historical invocations are understood as requests for `$taskchef-copilot` and
-receive a brief rename notice.
-
-File-backed inspection is also available:
-
-```sh
-taskchef task brief
-taskchef task brief c0f010ff
-taskchef task brief --project payments
-taskchef task list
-taskchef task list --project payments
-taskchef task show c0f010ff
-taskchef task summary
-```
-
-Add `--json` for structured output. `task brief` returns the stable schema-1
-cached coordination model and omits terminal tasks older than seven days from
-overviews unless `--all` is supplied. Focused task and project briefs retain
-their full selected scope. Task IDs accept a full UUID or an unambiguous
-eight-character prefix.
-
-## Dashboard
-
-The dashboard normally starts when the TaskChef MCP activates, and the
-dispatcher retries startup at the beginning of each turn. Its final response
-includes the dashboard link even if startup fails. If the dashboard is
-unavailable, use the packaged recovery skill to start or open it:
-
-```text
-$taskchef-dashboard Ensure and open the TaskChef dashboard.
-```
-
-MCP activation and `$taskchef-dashboard` call the input-free `ensure_dashboard`
-MCP tool. It starts at most one loopback dashboard scoped to the running Codex
-session on `127.0.0.1:3210`, or reuses a listener only when its bounded
-`/api/health` identity reports the exact TaskChef/dashboard-server version,
-canonical workspace, and recognized launcher. The response says `started` or
-`reused` and includes the stable URL, canonical workspace, versions, and actual
-launcher.
-
-The dashboard is launched by MCP but is not hosted by one MCP transport. It
-therefore survives an individual MCP close, stdin EOF, signal, or plugin reload.
-Only a listener launched as `session` registers each same-version MCP's original
-Codex parent PID in its in-memory lease. After every registered Codex session
-PID disappears for a grace period, the dashboard closes and exits. Activating
-an installed newer TaskChef MCP recognizes and
-gracefully stops an older TaskChef dashboard for the same canonical workspace,
-waits boundedly for the port, then starts the installed version in that ensure.
-Lease state is not transferred across versions; the replacement initially knows
-only the activating session. These are best-effort
-local guards, not a claim that Codex supplies a restart guarantee. TaskChef adds
-no daemon or OS-persistent component. See the complete
-[dashboard lifecycle](dashboard-lifecycle.md).
-
-TaskChef uses a trusted, single-user localhost model. Exact structured health is
-sufficient service recognition; it is not cryptographic authentication. Simple
-session and shutdown controls require exact Host and Origin, JSON content, a
-non-simple request header, and an exact bounded body to block ordinary
-cross-site browser requests. Each control names the exact health identity the
-caller observed; the listener refuses a stale identity and the caller probes the
-port again before deciding what to do. Unknown, malformed, different-workspace,
-unrelated, and newer listeners remain untouched. A release using the former HMAC control
-protocol refuses the new simple shutdown request, so the first upgrade across
-that boundary may require stopping that verified legacy TaskChef listener once
-before ensuring again.
-
-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
-fields:
-
-```json
-"dashboard": { "autostart": false }
-```
-
-The manual `$taskchef-dashboard` recovery skill remains available when
-autostart is disabled or fails. It reports whether the compatible dashboard was
-started or reused and always returns its canonical clickable URL. It may open
-the returned localhost URL in an available in-app browser, but browser failure
-does not make dashboard recovery fail.
-
-For manual development, run the foreground CLI:
-
-```sh
-taskchef dashboard
-taskchef dashboard --port 3211
-```
-
-The loopback dashboard watches `tasks.jsonl`, groups current states, and opens
-linked Codex tasks. 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 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** and direct **Mark completed** and **Mark failed** actions.
-Working and needs-input tasks offer either terminal outcome; completed tasks
-offer **Mark failed**, and failed tasks offer **Mark completed**. The menu
-disclosure is the deliberate first step; choosing an 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. Same-state terminal rewrites remain invalid. 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 archive implementation is retained behind a disabled capability gate, and
-the **Archive chat** control is hidden. The bundled `codex archive` command can
-reject a valid idle desktop-app thread even when the dashboard runs in the MCP
-host environment, while Codex's native app archive operation succeeds. TaskChef
-will keep the feature disabled until Codex exposes a reliable supported
-app-callable archive interface or guarantees CLI compatibility. The dormant
-server path also rejects requests before discovering or invoking the CLI.
-
-Task details show chat totals and native per-turn usage from saved Codex records.
-Historical tasks are read when needed, rather than scanned at startup. A turn
-without a matching native Codex turn ID shows usage unavailable; its chat total
-can still be shown. Missing logs and parent links make the known subtotal
-incomplete. Input, cached input, output, reasoning, and total counts use Codex's
-categories. Cached input and reasoning are subsets, not additional tokens.
-Dollar figures are API-equivalent estimates, using the board's pricing table.
-Unknown prices show cost unavailable or a known priced subtotal. Existing saved
-usage projections remain readable. A partial scan cannot replace a larger known
-historical subtotal; missing model prices cannot erase a saved priced subtotal.
-`.taskchef-usage.json` holds the web view's
-normalized projections; the underlying engine reuses the board disk caches.
-
-The same detail view reports lifecycle wall-clock elapsed time independently of
-token accounting. Each terminal turn shows **Elapsed** from `startedAt` to
-`result.updatedAt`; **Total reported work** sums only valid terminal-turn
-durations, excluding idle gaps and unfinished work. A working turn shows live
-**Elapsed so far** without contributing to the total. This is reported
-wall-clock elapsed time, not model compute time, and malformed or reversed
-timestamp ranges are shown as unavailable.
-The header shows the running TaskChef package version reported by the same
-bounded health identity used for compatible-listener checks.
-The Settings page identifies TaskChef as the usage provider.
-The canonical port is normally owned by a dashboard session process initialized
-by the TaskChef MCP before its tool transport connects. MCP recovery reuses an
-exact-compatible same-workspace dashboard and reports its actual launcher;
-a foreground `taskchef dashboard` process is intentionally standalone so its
-child commands cannot silently inherit an agent-shell sandbox.
-Task and result times are relative through 29 days (with minute detail for the
-first six hours), then use a locale-aware calendar date. Each time is a keyboard-
-accessible toggle for its full locale-aware date and time, and one shared
-30-second timer keeps relative labels current without reloading the page.
-The Updates panel captures immutable event-time lifecycle notices. It identifies
-them by task, turn when available, and lifecycle event rather than dashboard
-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.
-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`. An exact-current, healthy same-workspace listener with a
-recognized `standalone`, `mcp`, or `session` launcher may be reused on the
-canonical MCP port; ensure reports its actual launcher, and only `session`
-listeners register Codex PID leases. If an unknown, malformed, or
-different-workspace process owns port 3210, TaskChef reports a concise conflict
-and never kills that process. A recognized older same-workspace TaskChef
-listener receives a simple guarded graceful shutdown request. If it lacks the
-compatible callback or refuses the request, it remains running and ensure
-reports a conflict. The foreground CLI similarly asks you to stop a conflicting
-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.
-It exposes no task data, credentials, environment variables, process control,
-or secrets.
-
-![TaskChef dashboard identity and version](images/dashboard-identity.jpg)
-
-![Immutable event-time dashboard notifications](images/notification-event-snapshots.jpg)
-
-![Task detail activity timeline](images/result-history-dashboard.jpg)
-
-![Deferred ccusage token consumption in task details](images/ccusage-token-consumption.png)
-
-![Interrupted turn followed by active recovery](images/interrupted-turn-recovery.jpg)
-
-## Common recovery
-
-Check the managed workspace:
-
-```sh
-taskchef doctor
-taskchef workspace init
-taskchef workspace migrate
-taskchef doctor
-```
-
-`doctor` is read-only. `workspace init` creates missing files and refreshes
-managed instructions. `workspace migrate` explicitly upgrades supported schema
-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-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
-before a backup or rewrite.
-
-If a new record has no thread ID, the executor is link-pending. Reopen that
-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, 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.
-
-## Boundaries
-
-TaskChef dispatches; it is not a scheduler, supervisor, worker runtime, or
-merge coordinator. Executor identity is a cooperative assertion inside a local
-single-user trust boundary. The [specification](spec.md) defines the
-required contract; [workflows](workflows.md) ties it to current code.
-
-## Update
-
-```sh
-codex plugin marketplace upgrade favoyang-plugins
-codex plugin add taskchef@favoyang-plugins
-```
-
-Replacing or installing plugin files cannot execute autostart by itself. After
-installation, activate or reload the new TaskChef MCP process; installation
-does not necessarily reload Codex. Then run `$taskchef-dashboard` (or call
-`ensure_dashboard`) and verify the returned dashboard identity has all of:
-
-- the expected released TaskChef version;
-- the expected dashboard protocol `serverVersion`;
-- the reported dashboard launcher (`session` for a newly started canonical dashboard);
-- the canonical TaskChef workspace path;
-- the canonical `http://127.0.0.1:3210/` URL.
-
-The release-install sequence is therefore: install plugin, activate or reload
-the new MCP process, ensure the dashboard, then verify TaskChef version,
-protocol `serverVersion`, reported launcher, canonical workspace, and URL.
-Exact-compatible same-workspace servers with a recognized launcher may be
-reused; unknown listeners remain untouched.
-
-If autostart reports a **verified older TaskChef** listener, the port occupant
-passed the bounded TaskChef identity check but refused the simple graceful
-shutdown request. Releases using the former HMAC control protocol form a
-one-time compatibility boundary: stop that verified legacy TaskChef listener
-through the application/session that launched it, then activate the installed
-plugin and ensure again. Do not kill an arbitrary port owner.
-
-## Development
-
-```sh
-npm ci
-npm test
-npm pack --dry-run
-```
-
-Merges to `main` run semantic-release and update the shared plugin
-marketplace. Removing unsupported schemas is a major-version change.

package/docs/dashboard-lifecycle.md

@@ -1,149 +0,0 @@
-# Dashboard lifecycle
-
-This document defines how the canonical TaskChef dashboard starts, survives MCP
-reloads, changes version, and stops. The [specification](spec.md) is normative;
-the [README](../README.md) covers user operation, and
-[workflows](workflows.md) maps these guarantees to implementation.
-
-## Process model
-
-The canonical dashboard is a loopback-only process scoped to a running Codex
-application session. TaskChef MCP activation launches it, but one MCP transport
-does not own it. It can therefore survive an individual MCP EOF, signal,
-transport close, or plugin reload while another TaskChef MCP transport in the
-same Codex session remains active.
-
-TaskChef does not install a daemon, login item, lifecycle hook, or privileged
-service. A foreground `taskchef dashboard` remains a separate `standalone`
-launcher.
-
-## Start and reuse
-
-Unless `dashboard.autostart` is explicitly `false`, MCP activation runs the same
-serialized ensure operation exposed by `ensure_dashboard`. Failure is isolated
-from MCP startup and emits a bounded diagnostic.
-
-The canonical session manager requires an explicit nonzero port and normally
-binds `127.0.0.1:3210`. Its deterministic lifecycle is:
-
-1. No listener: start the installed dashboard and wait until its health endpoint
-   is reachable.
-2. Exact current identity for the canonical workspace: reuse it after another
-   health probe. A `session` listener first registers the activating Codex PID
-   in its in-memory lease.
-3. Exact older TaskChef identity for the canonical workspace: request graceful
-   shutdown, wait a bounded time for port release, then start the installed
-   version within the same ensure operation.
-4. Recognized newer TaskChef identity: refuse to downgrade it.
-5. Unknown, malformed, different-workspace, or unrelated listener: report a
-   clear conflict without sending a control request or process signal.
-
-Health is an exact bounded structured identity containing the service marker,
-schema, TaskChef version, dashboard server version, canonical workspace, and
-launcher. It is sufficient service recognition in TaskChef's trusted,
-single-user localhost model. It is not cryptographic authentication.
-
-Concurrent activations can all observe a free port. Only one detached process
-can bind it; other activators inspect and reuse or replace the winner according
-to the same rules. A detached child reports readiness over inherited IPC after
-the server has bound, completed initialization, and created its first in-memory
-lease. A bounded timeout cancels failed or slow startup.
-
-## MCP reload and plugin upgrade
-
-Closing an MCP transport does not close the dashboard. Each exact same-version
-reuse registers the activating Codex PID. The dashboard checks these in-memory
-leases with non-signalling existence probes and closes after all registered PIDs
-are gone for the configured grace period.
-
-Lease state is deliberately not transferred across versions. A replacement
-dashboard initially knows only the activating session. A later ensure from
-another session registers that session, and can restart the dashboard if the
-first lease has already expired. This accepted consequence keeps upgrade
-behavior deterministic and avoids durable or cross-version ownership state.
-
-Releases using the former HMAC control protocol do not understand the simple
-shutdown request. The first upgrade from such a release reports that the
-recognized older listener refused graceful shutdown and leaves it running. Stop
-that verified TaskChef listener through its existing lifecycle, then activate
-or ensure the newly installed plugin again. TaskChef never adds a generic
-process-kill fallback to cross this one-time compatibility boundary.
-
-## Local control boundary
-
-The dashboard listens only on `127.0.0.1` or `::1` and has no browser login.
-Its health identity contains no task data, credentials, environment variables,
-or process-control details.
-
-The session-registration and graceful-shutdown endpoints are intentionally
-small localhost controls. They require the exact listener Host and Origin,
-JSON content type, a non-simple `X-TaskChef-Control` header, and an exact bounded
-body. Each body includes the exact structured health identity observed by the
-caller. The receiver compares it with its own identity before registering a
-session or accepting shutdown. On a mismatch the caller probes the listener
-again and applies the normal lifecycle rules to the current occupant. These
-checks block ordinary cross-site browser requests and DNS rebinding to a
-different Host. They are request-shape checks, not authentication or an
-ownership protocol.
-
-Future LAN access is outside this model. It must be a separate opt-in feature
-with password-backed user authentication and suitable transport protection.
-
-TaskChef sends graceful shutdown only after exact recognized TaskChef health for
-the same canonical workspace. It never discovers or kills a port owner, sends
-OS signals to an unknown process, uses forceful termination, searches broadly
-for processes, or requires elevated permission.
-
-## Dashboard state and presentation
-
-A newly started server creates or deduplicates a verified private workspace
-snapshot before monitors or derived-state writers start. Reuse does not create
-another startup snapshot. Snapshot failure aborts the new server.
-
-The dashboard watches task history and the project index. It warns when
-historical task snapshots reference paths absent from the current index and
-offers recovery-oriented read-only commands. It never mutates or restores
-configuration.
-
-The task dashboard offers List and Board views at every screen width. List
-remains the default and keeps its status filter, task metrics, and
-actions. Board groups tasks by recorded status, with an Unresolved column only
-when needed. The view switch precedes the project and Updated filters in both
-views. Both filters apply to Board and List; Updated offers the latest 24 hours,
-latest 7 days, and all time. Board ignores
-the remembered List status filter. Completed initially shows five cards, with
-five more available per click. Each Board card shows its project's name, title,
-current request or latest reported result, relative update time, and a chat
-shortcut when the task has a linked chat. Opening the title uses the full task
-detail view. Board columns are 340 px wide where space permits and scroll
-horizontally when needed. On phones, a column fits the viewport with a peek of
-the next. Swipe or scroll horizontally to reach every column, or focus the
-board to scroll it with a keyboard; the page still scrolls vertically through
-tasks.
-The view preference is stored locally when browser storage is available.
-
-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. The dashboard owns a bounded
-background queue for derived usage and stops that queue with the server.
-
-![Pending token usage in the task detail view](images/dashboard-token-pending.jpg)
-
-Reported work is wall-clock elapsed time derived from TaskChef lifecycle
-timestamps. It excludes idle gaps and unfinished portions of active turns from
-the terminal total. Missing, malformed, reversed, zero-width, or unsupported
-timestamp ranges display an unavailable state.
-
-## Lifecycle matrix
-
-| Event | Result |
-| --- | --- |
-| Activation with no listener | Start installed session dashboard |
-| Activation with exact current listener | Register a session lease when supported, verify health again, reuse |
-| Activation with recognized older listener | Request graceful shutdown, wait boundedly, start installed version |
-| Activation with recognized newer listener | Refuse downgrade and leave it running |
-| Activation with unknown or different-workspace listener | Report conflict and leave it untouched |
-| One MCP EOF, signal, or reload | Dashboard remains while a registered Codex PID is alive |
-| All registered Codex PIDs disappear | Dashboard closes after the grace period |
-| `dashboard.autostart: false` | Explicit ensure remains available |
-| Foreground `taskchef dashboard` | Standalone process follows foreground CLI lifetime |