taskchef 8.3.0 → 8.3.1

package/.codex-plugin/plugin.json

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

package/README.md

@@ -62,8 +62,6 @@ 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 ccusage snapshot and turn-boundary cache
-.taskchef-dashboard-owner.json   optional mode-0600 current dashboard identity and control credential; retained and atomically replaced
-.taskchef-dashboard-handoff.json   optional mode-0600 secret-free signed final lease snapshot; retained and atomically overwritten
 ```
 
 Index or inspect Codex projects conversationally:
@@ -272,40 +270,36 @@ $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 proves the exact TaskChef/dashboard-server version,
-canonical workspace, and `session` launcher. The response says `started` or
-`reused` and includes the stable URL, canonical workspace, and versions.
+`/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.
-Each MCP securely registers its original Codex parent PID; after every
-registered Codex session PID disappears for a grace period, the dashboard
-closes and exits. Activating an installed newer TaskChef MCP authenticates and
-retires a compatible older `mcp`- or `session`-owned dashboard for the same
-canonical workspace, then starts the installed version. These are best-effort
+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](docs/dashboard-lifecycle.md).
 
-Authenticated handoff requires the older listener to have written TaskChef's
-private mode-0600 ownership record in that canonical workspace. A nonce-bound
-HMAC challenge proves the listener has the matching secret before TaskChef
-sends an authenticated two-phase handoff. A session listener prepares by
-fencing ordinary joins, adding the activating Codex PID, and returning a signed
-bounded lease snapshot while remaining live. A separate authenticated commit
-allows a short concurrent-activator grace, returns the signed final immutable
-lease set, and then schedules graceful shutdown after a bounded response-retry
-window. A mode-`0600`, secret-free, signed final-snapshot record permits exact
-lease recovery if every commit response is lost; a prior MCP-owned listener
-receives a separately authenticated graceful shutdown request. The secret is never
-returned by `/api/health`, sent in a request, or logged. Standalone,
-different-workspace, newer, malformed,
-unverified, and spoofed listeners are left untouched. Versions predating this
-protocol cannot be taken over safely and may require one final manual cleanup.
-The ownership record is durable metadata: shutdown retains it, and the next
-MCP owner atomically replaces it after binding. This avoids both a live
-credentialless retirement window and an old process deleting its replacement's
-proof.
+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
@@ -382,10 +376,9 @@ The header shows the running TaskChef package version reported by the same
 bounded health identity used for compatible-listener checks.
 The Settings page shows the ccusage version reported by the executable that
 TaskChef resolves at runtime.
-The canonical port is owned by a dashboard session process initialized by the
-TaskChef MCP before its tool transport connects. Health identity records a
-`session` launcher, and MCP recovery reuses only another exact-compatible,
-authenticated session dashboard;
+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
@@ -400,11 +393,16 @@ 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 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`.
+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.
@@ -472,24 +470,22 @@ does not necessarily reload Codex. Then run `$taskchef-dashboard` (or call
 
 - the expected released TaskChef version;
 - the expected dashboard protocol `serverVersion`;
-- the `session` dashboard launcher;
+- 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`, `session` launcher, canonical workspace, and URL.
-Exact-compatible session servers may be reused; standalone and unknown listeners
-remain untouched.
+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 could not complete authenticated
-handoff. For a release older than the ownership protocol, stop that one known
-legacy MCP process once through the application/session that launched it, then
-activate the installed plugin again. Do not kill an arbitrary port owner. A
-listener from a handoff-capable prior release should retire automatically; if
-it does not, retain it for diagnosis because TaskChef deliberately refuses to
-weaken the ownership proof.
+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
 

package/docs/dashboard-lifecycle.md

@@ -5,214 +5,128 @@ 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.
 
-## Ownership model
+## Process model
 
 The canonical dashboard is a loopback-only process scoped to a running Codex
-application session. It is launched and maintained by TaskChef MCP activation,
-but it is not hosted by one MCP transport. This distinction lets the dashboard
-survive an individual MCP EOF, signal, transport close, or plugin reload while
-other TaskChef MCP transports in the same Codex session continue using it.
+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` process remains a separate
-`standalone` launcher and is never adopted as the canonical session dashboard.
+service. A foreground `taskchef dashboard` remains a separate `standalone`
+launcher.
 
-The dashboard was originally moved into the MCP runtime so the experimental
-chat-archive action could inherit the MCP host environment. That action is now
-disabled because Codex does not expose a reliable supported app-callable
-archive interface. The dashboard still benefits from MCP activation,
-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. Task cards keep the latest
-cumulative value visible during a newer active turn and label it as updating;
-pending is reserved for tasks that do not have a usage snapshot yet.
-
-The dashboard owns a small background recovery queue for derived usage. It
-deduplicates tasks, limits concurrent ccusage reads, preserves successful cache
-records, and revisits missing, interrupted, or cooldown-expired records without
-requiring a detail request. The queue starts with the dashboard, reacts to task
-log revisions, performs periodic recovery passes, and stops with the dashboard.
-Settings reports the version returned by the resolved ccusage executable.
-
-![Pending token usage in the task detail view](images/dashboard-token-pending.jpg)
-
-## Reported work presentation
-
-The task detail view reports wall-clock elapsed time from TaskChef lifecycle
-timestamps. Each terminal turn's **Elapsed** value is `result.updatedAt` minus
-`startedAt`. **Total reported work** is the sum of valid terminal-turn elapsed
-times, so idle gaps between follow-up turns and the unfinished portion of an
-active turn are excluded. A working turn shows a live **Elapsed so far** value
-from `startedAt` to the current time without adding it to the task total.
-
-Durations below one minute use whole seconds; durations below one hour use
-minutes and seconds; durations below one day use hours and minutes; longer
-durations use days and hours. Each displayed unit is floored, and positive
-sub-second durations display as `<1s`. Missing, malformed, reversed, or
-unsupported timestamp ranges display an explicit unavailable state. Zero-width
-terminal ranges are also unavailable because existing records cannot reliably
-distinguish synthesized boundaries from same-millisecond measured work. Timing
-is derived independently of `.taskchef-usage.json` and is reported wall-clock
-elapsed time, not model compute time.
-
-![Reported work across a multi-turn task](images/reported-work-duration-desktop.jpg)
+## Start and reuse
 
-![Unavailable reported work on a narrow layout](images/reported-work-duration-mobile.jpg)
+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.
 
-## Start and reuse
+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.
 
-An actual new dashboard server creates or deduplicates a verified private state
-snapshot before monitors or derived-state writers start. Reusing an existing
-listener does not create another startup snapshot. Snapshot failure aborts the
-new server start and does not weaken MCP reporting isolation.
+## MCP reload and plugin upgrade
 
-The dashboard watches both task history and the project index. It warns when
-historical task snapshots reference paths absent from the current index, and
+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.
 
-Unless `dashboard.autostart` is explicitly `false`, MCP activation runs the
-same serialized ensure operation exposed by `ensure_dashboard` before the MCP
-transport connects. An explicit ensure remains available when autostart is
-disabled. Failure is isolated from MCP tool startup and emits only a bounded,
-non-sensitive diagnostic.
-
-The canonical session manager requires an explicit nonzero port and normally
-binds `127.0.0.1:3210`; ephemeral port zero remains available only to direct
-foreground/server callers that own the returned listener. Reuse requires an
-exact bounded health identity:
-
-- TaskChef dashboard service and health schema;
-- installed TaskChef version;
-- dashboard protocol version;
-- canonical workspace;
-- `session` launcher.
-
-The MCP then authenticates the listener with the private ownership credential
-and registers its original Codex parent PID as a session lease. Registration
-success and transferred lease sets carry response HMACs bound to their fresh
-request nonce and complete result, so a different process appearing between
-the challenge and control request cannot be adopted. Concurrent starts
-serialize locally and converge across processes by authenticating the single
-listener that wins the port race.
-
-A detached child reports readiness over a private inherited IPC channel only
-after the listener is bound and the new owner record is durably published.
-Startup errors use the same channel. A bounded timeout sends a cooperative
-cancellation message, so slow or failed initialization cannot be mistaken for
-success or silently strand a late or partially constructed listener. Owner
-publication checks cancellation before atomic replacement; while publication
-is in flight, every close path retains the port until publication settles, so
-an older credential writer cannot race and overwrite a succeeding session's
-owner record.
+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.
 
-## MCP reload and plugin upgrade
+![Pending token usage in the task detail view](images/dashboard-token-pending.jpg)
 
-Closing one MCP transport does not close the session dashboard. EOF, SIGINT,
-SIGTERM, protocol close, failed transport startup, and detected MCP-parent loss
-still close that MCP process promptly, but the independently hosted dashboard
-remains while a registered Codex session PID is alive.
-
-After a plugin upgrade, installing files alone cannot execute new code. When
-the newly installed MCP activates, it compares the live identity with its own
-version. An exact current listener is reused. A verified older TaskChef
-`mcp`- or `session`-launched listener for the same canonical workspace receives
-an authenticated graceful handoff request. A session listener prepares an
-idempotent handoff by fencing new registrations, adding the activating Codex
-PID, and snapshotting its bounded live leases while it remains running. Only
-after the MCP receives and verifies that signed result does it send a separate
-authenticated commit that schedules graceful shutdown. A lost prepare response
-is safely retried; an abandoned preparation expires and reopens registration.
-A commit begins a short bounded finalization grace during which concurrent
-authenticated activators can join. The commit response then returns the final
-immutable lease snapshot with a credential-bound proof. The listener remains
-available for a bounded commit-response retry window before graceful shutdown,
-so a surviving activator can replace an elected peer that exits before launch
-without discarding the older live sessions. The replacement starts with the
-verified final leases. A full lease set refuses a distinct activating PID
-without stopping the old listener. Finalization also reserves one of the 64
-bounded lease slots for a distinct recovery activator; a 64-lease snapshot
-cannot commit retirement and leaves the old listener running. The new MCP then
-starts the current `session` version. A newer listener is never downgraded,
-including during the brief old-to-new listener gap. If different newer versions
-race, a higher contender authenticates and replaces a lower winner until the
-highest active version remains.
-
-Before acknowledging commit, the retiring session atomically records that
-signed final snapshot in the mode-`0600` workspace file
-`.taskchef-dashboard-handoff.json`. The record
-contains no control secret. It exists only so an activator that loses every
-commit response can authenticate and recover the exact finalized leases after
-the old listener closes. The single record is retained and atomically
-overwritten by the next finalized handoff; it cannot authenticate against a
-new owner identity and secret. Avoiding post-publication deletion prevents one
-replacement from removing a newer handoff generation. Invalid, permissively
-readable, foreign-workspace, or incorrectly signed records are ignored and
-never authorize takeover.
-
-Both private metadata writers sync the completed file, atomically rename it,
-and sync the canonical workspace directory before reporting publication. Final
-lease joins are fenced before the immutable snapshot and durable write begin.
-
-Versions predating authenticated ownership cannot be retired safely. Such a
-legacy listener may require one final manual cleanup. This limitation is
-intentional; TaskChef does not weaken listener safety to automate migration.
-
-## Codex session end
-
-Each MCP registers the exact PID of the Codex process that launched it. The
-dashboard checks only those registered PIDs with a non-signalling existence
-probe. When none remains alive for the configured grace period, the dashboard
-gracefully closes its HTTP listener and exits. Registering another live Codex
-session during the grace period cancels expiry.
-
-This is a best-effort local lifecycle guard, not a claim that Codex documents
-or guarantees restart cleanup. PID existence cannot prove application identity
-after an unlikely PID reuse, and abrupt operating-system termination can always
-interrupt graceful cleanup. A later MCP activation still performs authenticated
-version handoff, which is the recovery boundary for a recognized stale
-TaskChef listener.
-
-## Security boundary
-
-TaskChef writes ownership to `.taskchef-dashboard-owner.json` and finalized
-handoff metadata to `.taskchef-dashboard-handoff.json` as private regular
-mode-0600 files in the canonical workspace. The credential never appears in health responses,
-diagnostics, URLs, or logs. A fresh nonce-bound HMAC challenge proves that the
-listener and owner record share the credential. Shutdown and session
-registration use separate action-bound proofs; successful registration and
-handoff responses are also nonce- and result-bound. Nonces are single-use within
-a bounded five-minute replay window. The replay cache has a fixed capacity and
-refuses overflow while entries remain valid.
-
-TaskChef sends control requests only after all public identity and private
-ownership fields match. It never discovers or kills a port owner, sends OS
-signals to a listener, uses `kill -9`, searches broadly for processes, or
-requires elevated permission. These listeners remain untouched:
-
-- standalone dashboards;
-- unknown or spoofed services;
-- different canonical workspaces;
-- newer TaskChef versions;
-- malformed or mismatched ownership records;
-- listeners that fail the authenticated challenge;
-- uncooperative legacy listeners without the handoff protocol.
+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 | MCP transport | Canonical dashboard |
-| --- | --- | --- |
-| MCP activation, no listener | Starts | Starts current session version |
-| MCP activation, exact listener | Starts | Authenticated reuse and lease registration |
-| One MCP EOF, signal, or reload | Closes | Remains while a Codex session PID is alive |
-| Plugin upgrade activates newer MCP | Starts current version | Verified older version retires; current version starts |
-| All registered Codex session PIDs disappear | May already be closed | Graceful close after the grace period |
-| `dashboard.autostart: false` | Starts normally | No activation-time ensure; explicit ensure still works |
-| Foreground `taskchef dashboard` | Unrelated | Standalone process follows its foreground CLI lifetime |
-| Unknown or unverified port occupant | Starts normally | Occupant is untouched; ensure reports a bounded conflict |
+| 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 |