taskchef 7.22.4 → 7.22.5

package/.codex-plugin/plugin.json

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

package/README.md

@@ -16,6 +16,7 @@ request -> recorded TaskChef task -> Codex executor -> request/result turn timel
 | --- | --- |
 | Install, configure, dispatch, inspect, and recover | This README |
 | Follow the normative agent contract and MCP interfaces | [Specification](docs/spec.md) |
+| Understand dashboard start, upgrade, and shutdown | [Dashboard lifecycle](docs/dashboard-lifecycle.md) |
 | Understand implementation flows and trust boundaries | [Workflows](docs/workflows.md) |
 | Compare TaskChef with FirstMate | [FirstMate comparison research](docs/firstmate-taskchef-comparison.md) |
 | Review deferred ideas | [Backlog](BACKLOG.md) |
@@ -61,6 +62,8 @@ 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:
@@ -238,28 +241,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 dashboard inside the existing TaskChef MCP process on
-`127.0.0.1:3210`, or reuses a listener only when its bounded `/api/health`
-identity proves the exact TaskChef/dashboard-server version and the same
-canonical workspace. The response says `started` or `reused` and includes the
-stable URL, canonical workspace, and versions.
-
-The in-process dashboard closes on MCP transport close, stdin EOF, SIGINT,
-SIGTERM, or detected loss of the MCP process's original parent. Activating a
-newer TaskChef MCP can also retire an older compatible MCP-owned dashboard for
-the same canonical workspace through an authenticated loopback handoff. These
-guards reduce unnecessary orphans but do not claim that Codex supplies a
-restart or child-process cleanup guarantee. TaskChef adds no daemon or other
-OS-persistent component, and dashboard availability remains best-effort while
-Codex is closed.
-
-Authenticated handoff requires the older listener to use the same dashboard
-protocol and 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 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,
+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.
+
+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
+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
@@ -330,9 +341,10 @@ pricing modes. ccusage 20.0.20 may omit GPT-5.6 cache-write charges, so TaskChef
 labels that analyzer limitation instead of presenting the estimate as complete.
 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
-before its tool transport connects. Health identity records an `mcp` launcher,
-and MCP recovery reuses only another exact-compatible MCP-launched dashboard;
+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;
 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
@@ -419,14 +431,14 @@ does not necessarily reload Codex. Then run `$taskchef-dashboard` (or call
 
 - the expected released TaskChef version;
 - the expected dashboard protocol `serverVersion`;
-- the `mcp` dashboard launcher;
+- the `session` dashboard launcher;
 - 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`, `mcp` launcher, canonical workspace, and URL.
-Exact-compatible MCP servers may be reused; standalone and unknown listeners
+protocol `serverVersion`, `session` launcher, canonical workspace, and URL.
+Exact-compatible session servers may be reused; standalone and unknown listeners
 remain untouched.
 
 If autostart reports a **verified older TaskChef** listener, the port occupant

package/docs/dashboard-lifecycle.md

@@ -0,0 +1,168 @@
+# 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.
+
+## Ownership 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.
+
+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.
+
+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.
+
+## Start and reuse
+
+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.
+
+## MCP reload and plugin upgrade
+
+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.
+
+## 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 |

package/docs/spec.md

@@ -57,9 +57,15 @@ is dated research, not contract.
 
 ## Workspace contract
 
-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 MUST manage only `AGENTS.md`, `taskchef.json`, `tasks.jsonl`, the
+optional `.taskchef-usage.json` cache, and the optional dashboard lifecycle
+records `.taskchef-dashboard-owner.json` and
+`.taskchef-dashboard-handoff.json` inside the dispatcher workspace. It MUST
+preserve unrelated paths. The owner record MUST be a retained mode-`0600`
+current-listener identity and control credential that is atomically replaced by
+a new owner. The handoff record MUST be a retained mode-`0600`, secret-free,
+credential-signed final lease snapshot that is atomically overwritten by the
+next finalized handoff.
 
 `taskchef.json` MUST have schema version 2, the following required fields, and
 an optional exact `dashboard` object:
@@ -191,8 +197,9 @@ port conflicts, and dashboard errors MUST NOT prevent tool registration or MCP
 availability. They MUST emit only a bounded non-sensitive diagnostic through
 the MCP process logging channel. MCP initialization MUST NOT open a browser.
 If transport connection fails after dashboard startup, the MCP server MUST
-best-effort close both its owned dashboard and partially attached transport,
-then propagate the original connection failure even when cleanup also fails.
+best-effort close its manager and partially attached transport, then propagate
+the original connection failure even when cleanup also fails. Closing that
+individual MCP MUST NOT directly close a valid Codex-session dashboard.
 
 At the start of every dispatcher turn, the dispatcher SHOULD call
 `ensure_dashboard` best-effort. Failure MUST NOT block direct TaskChef answers,
@@ -282,12 +289,11 @@ object. Validation, marker, identity, uniqueness, freshness, or filesystem
 failures are surfaced as tool errors and MUST NOT partially mutate the log.
 
 ### `ensure_dashboard`
-
-**Caller:** dispatcher. **Mutation:** starts at most one in-process loopback
-HTTP server. The first owned start writes a private dashboard ownership record
-in the canonical workspace. The record remains after shutdown and the next
-owner atomically replaces it before reporting startup success.
-Exact-compatible reuse does not write it.
+**Caller:** dispatcher. **Mutation:** starts or reuses the authenticated
+Codex-session-scoped loopback dashboard. The first start writes a private
+dashboard ownership record in the canonical workspace. The record remains
+after shutdown and the next owner atomically replaces it before reporting
+startup success.
 
 **Input:** empty object.
 
@@ -296,7 +302,7 @@ Exact-compatible reuse does not write it.
 ```text
 { dashboard: {
   action: "started" | "reused",
-  launcher: "mcp",
+  launcher: "session",
   url: "http://127.0.0.1:3210/",
   workspace: string,
   taskchefVersion: string,
@@ -304,51 +310,98 @@ Exact-compatible reuse does not write it.
 } }
 ```
 
-MCP initialization MUST complete its best-effort dashboard start before exposing
-the MCP transport. Calls MUST serialize within one MCP process. The first call
-starts an owned dashboard or reuses an exact compatible MCP-launched listener;
-later and concurrent calls are idempotent and report reuse after the single start. The stable default MUST
-bind only to `127.0.0.1:3210` and MUST NOT accept a model-supplied workspace,
-host, or port.
-
-Before reuse, TaskChef MUST query a bounded loopback identity endpoint and
-require the exact fixed service/schema, TaskChef version, dashboard-server
-version, canonical workspace, and `mcp` launcher identity. Exact-compatible
-reuse MUST remain non-destructive and MUST NOT require ownership metadata. A
-manager that reuses another same-version MCP listener MUST monitor that listener
-for the remainder of its own lifetime and perform ordinary singleton startup if
-the reused owner exits, so overlapping plugin reloads converge on the surviving
-MCP process without signaling or terminating either process. A temporary
-different or unknown occupant remains untouched and does not disable that
-non-destructive availability monitor.
-
-An older TaskChef version MAY be retired only when all of these facts hold: its
-health identity is exact and reports the same canonical workspace, `mcp`
-launcher, and dashboard-server version; its semantic version is older than the
-requesting TaskChef version; a private regular mode-0600 owner record in that
-same workspace exactly matches the listener; and a fresh nonce-bound HMAC
-challenge proves control of that record's secret. Only after that proof MAY the
-new process send a separately nonce-bound authenticated loopback shutdown
-request. Shutdown nonces MUST be single-use. The secret MUST NOT appear in
-health responses, requests, diagnostics, or logs. Shutdown MUST retain the
-durable owner record so retirement cannot expose a credentialless live-listener
-window or delete a replacement's record. An owner accepting handoff MUST retire its in-memory dashboard manager
-so later tool calls cannot restart the older listener. Concurrent handoffs MUST
-converge on one listener and exact-compatible reuse.
-
-A standalone, unknown, malformed, different-workspace, newer, incompatible,
-unproven, spoofed, or legacy listener without valid ownership metadata MUST
-produce a concise actionable conflict and MUST NOT receive a shutdown request,
-signal, or process-level termination attempt. TaskChef MUST NOT discover or
-kill port owners. A startup or owner-record-write failure MUST leave no owned
-listener. The MCP server MUST close its owned dashboard on explicit MCP close,
-transport close, stdin EOF, SIGINT, SIGTERM, or detected replacement of its
-original parent process. Parent-loss detection is a local best-effort guard,
-not a Codex restart guarantee. Signal and parent-loss shutdown MUST bound the
-wait for an in-flight transport startup before closing the MCP server, so a
-never-settling startup cannot retain the dashboard indefinitely. This keeps dashboard child operations in the MCP
-host environment and prevents an agent-shell or foreground CLI dashboard from
-being mistaken for the canonical MCP-owned runtime.
+MCP initialization MUST complete its best-effort ensure before exposing the
+MCP transport. Calls MUST serialize within one MCP process. The first call
+starts a dashboard session process or reuses the exact current listener; later
+and concurrent calls are idempotent. The stable default MUST bind only to
+`127.0.0.1:3210` and MUST NOT accept a model-supplied workspace, host, port,
+session PID, or credential.
+
+Exact reuse MUST require the fixed service/schema, TaskChef version,
+dashboard-server version, canonical workspace, and `session` launcher identity.
+It MUST additionally prove the private owner credential and use a fresh,
+single-use, action-bound HMAC to register the MCP's original Codex parent PID.
+The registration acknowledgement and every transferred lease set MUST carry a
+separate response HMAC bound to the request nonce and complete accepted result.
+The independent dashboard MUST survive closure of an individual MCP transport.
+The session manager MUST require an explicit nonzero port because a detached
+child cannot safely return an ephemeral bound port without an additional IPC
+ownership channel. Direct foreground server callers MAY continue to bind port
+zero when they retain the returned listener.
+
+The dashboard MUST track only explicitly registered PIDs using non-signalling
+existence probes. Once every registered PID is absent for the grace period, it
+MUST gracefully close its HTTP listener and exit. A new authenticated live
+registration during the grace period MUST cancel expiry. This is a local
+best-effort session guard, not a Codex restart guarantee.
+
+An older TaskChef version MAY be retired only when its exact health identity
+reports the same canonical workspace and an `mcp` or `session` launcher; a
+private regular mode-0600 owner record exactly matches that listener; and a
+fresh nonce-bound HMAC challenge proves control of the record's secret. Only
+then MAY the new MCP send an action- and nonce-bound authenticated loopback
+handoff. Before retiring a prior `session` listener, an idempotent prepare
+action MUST fence new registrations, register the activating Codex PID,
+validate and return the bounded live PID lease set while the old listener
+remains running. Only a separate authenticated commit after the caller verifies
+that result MAY schedule shutdown. A lost prepare response MUST be retryable,
+and an abandoned preparation MUST expire without shutting down the listener. A
+full, failed, or malformed transfer MUST leave the
+listener running and MUST NOT acknowledge a concurrent registration that will
+be absent from the returned set. A prior `mcp` listener MAY instead receive a
+separately authenticated graceful shutdown request.
+A commit MUST begin a short bounded finalization grace that allows concurrent
+authenticated activators to join. Its response MUST contain a credential-bound
+proof of the final immutable complete lease snapshot. The listener MUST remain
+available for a bounded commit-response retry window before shutdown, so a
+surviving activator can recover if the elected one exits before launch. An
+activator observing the authenticated old-owner listener gap MUST wait for the
+elected replacement and MUST NOT bind an older version into that gap.
+The finalized transferable snapshot MUST reserve one bounded lease slot for a
+distinct recovery activator. If that complete union cannot fit, commit MUST fail
+without stopping the old listener. When different compatible newer versions
+race, a higher version that loses the bind MUST authenticate and replace the
+lower winner rather than accepting it as final.
+Before acknowledging commit, the retiring session MUST atomically persist the
+credential-bound final snapshot in a private mode-`0600` same-workspace record
+that contains no secret. A replacement MAY use that record only after verifying
+its exact workspace, listener identity, handoff identifier when known, bounded
+PID set, and HMAC with the private owner credential. It MUST ignore the record
+once replacement ownership is published, but MUST NOT unlink it after that
+transition because a newer handoff may already have atomically replaced it. The
+single retained record MUST be overwritten only by a newer finalized handoff
+and MUST remain unusable against a different owner identity or credential.
+Owner and handoff publication MUST sync the completed private file, atomically
+rename it, and sync the containing canonical workspace directory before
+reporting success. Finalization MUST fence further handoff joins before taking
+and persisting the immutable snapshot.
+The new MCP MAY then start its current `session` version and MUST NOT downgrade
+a newer listener. Concurrent startup and handoff MUST converge on one
+authenticated listener. Single-use control nonces MUST be retained in a fixed,
+time-bounded replay cache that refuses overflow while entries remain valid.
+
+The credential MUST NOT appear in health responses, requests, diagnostics, or
+logs. A standalone, unknown, malformed, different-workspace, newer, unproven,
+spoofed, or legacy listener without valid ownership metadata MUST produce a
+concise actionable conflict and MUST NOT receive a shutdown request, signal,
+or process-level termination attempt. TaskChef MUST NOT discover or kill port
+owners. An invalid workspace, initial task log, or ownership write MUST leave
+no newly owned listener.
+
+Detached session startup MUST use a private child readiness acknowledgement
+sent only after listener bind and atomic ownership publication. Startup errors
+MUST propagate through that channel. A bounded readiness timeout MUST
+cooperatively cancel the exact child so late initialization cannot strand an
+unreported listener. Ownership publication MUST check cancellation before its
+atomic replacement, and the listener MUST retain the port until that write
+commits or aborts on every shutdown path so an older writer cannot overwrite a
+successor's credential.
+
+MCP EOF, explicit close, protocol close, SIGINT, SIGTERM, transport-start
+failure, and MCP-parent loss MUST still bound MCP shutdown. They MUST close the
+MCP manager and transport without directly closing the independently hosted
+session dashboard. Foreground `taskchef dashboard` remains `standalone`, is
+never adopted by MCP, and follows its foreground process lifetime.
 
 The packaged `$taskchef-dashboard` skill MUST call this tool, report `started`
 or `reused`, and return the canonical clickable URL. It MAY use an available
@@ -358,6 +411,9 @@ back to the link without failing. It MUST NOT inspect task outcomes or dispatch.
 **Annotations:** `readOnlyHint: false`, `destructiveHint: false`,
 `openWorldHint: false`.
 
+The complete operational rationale and limits are documented in
+[Dashboard lifecycle](dashboard-lifecycle.md).
+
 ### `prepare_dispatch`
 
 **Caller:** dispatcher. **Mutation:** none.
@@ -643,8 +699,8 @@ identity or infer semantic results.
 
 TaskChef MUST NOT install or require daemons, launchd agents, login items,
 system services, cron jobs, hooks, privileged components, or elevated/system
-permissions for dashboard availability. Availability is best-effort while the
-owning Codex/plugin MCP process is alive and is not guaranteed while Codex is
+permissions for dashboard availability. Availability is best-effort while a
+registered Codex session process is alive and is not guaranteed while Codex is
 closed.
 
 Releases predating authenticated dashboard handoff are legacy listeners. A
@@ -656,6 +712,6 @@ protocol, compatible prior-version handoff is automatic.
 Installing or replacing plugin files MUST NOT be described as activating the
 new MCP code. Release verification MUST install the plugin, activate or reload
 the new MCP process, ensure the dashboard, and verify the expected TaskChef
-version, dashboard protocol `serverVersion`, `mcp` launcher, canonical workspace,
-and canonical URL. Exact-compatible MCP-listener reuse remains valid; installation MUST NOT be
+version, dashboard protocol `serverVersion`, `session` launcher, canonical workspace,
+and canonical URL. Exact-compatible session-listener reuse remains valid; installation MUST NOT be
 claimed to reload Codex automatically.

package/docs/workflows.md

@@ -4,7 +4,8 @@ This developer and advanced-agent guide explains how the current implementation
 moves data through TaskChef. The [specification](spec.md) is normative; the
 [README](../README.md) owns user operation. The
 [FirstMate comparison](firstmate-taskchef-comparison.md) is non-normative
-research.
+research. The [dashboard lifecycle](dashboard-lifecycle.md) owns the focused
+start, upgrade, shutdown, and security rationale.
 
 ## Implementation map
 
@@ -15,12 +16,14 @@ research.
 | `skills/taskchef-bootstrap/SKILL.md` | Initialize the workspace and maintain the Codex project index. |
 | `skills/taskchef-dashboard/SKILL.md` | Ensure or recover the canonical dashboard and return its URL. |
 | `skills/taskchef-copilot/SKILL.md` | Explain normalized cached briefs and coordinate safe next actions. |
-| `src/mcp.js` | Dashboard ensure, four primary lifecycle tools, one deprecated alias, shutdown ownership, and MCP annotations. |
+| `src/mcp.js` | Dashboard ensure, four primary lifecycle tools, one deprecated alias, MCP cleanup, and annotations. |
 | `src/delegation.js` | UUID marker, concise executor-skill invocation shape, and creation-failure handling. |
 | `src/workspace.js` | Current schemas, validation, locking, atomic JSONL writes, linking, and result freshness. |
 | `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/dashboard-manager.js` | Concurrent session ensure, authenticated reuse and upgrade handoff, and safe conflicts. |
+| `src/dashboard-session-process.js` | Independent loopback server, private ownership publication, signals, and Codex-session lease. |
+| `src/dashboard-session.js` | Exact registered-PID liveness checks and grace-period expiry. |
 | `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. |
 
@@ -40,19 +43,25 @@ sequenceDiagram
   participant D as Dispatcher
   participant M as TaskChef MCP
   participant H as Loopback health
-  participant S as Dashboard server
+  participant S as Dashboard session process
   M->>M: Read dashboard.autostart (absent means true)
   M->>M: Best-effort ensure before MCP transport connects
   D->>M: ensure_dashboard()
   M->>M: Serialize concurrent ensure calls
   M->>H: GET 127.0.0.1:3210/api/health
-  alt Exact service, versions, canonical workspace, and MCP launcher
+  alt Exact service, versions, canonical workspace, and session launcher
     H-->>M: Bounded compatible identity
+    M->>S: Authenticate owner and register Codex parent PID
     M-->>D: reused, URL, workspace, versions
   else No listener
     H--xM: Connection refused
-    M->>S: Start in this MCP process on 127.0.0.1:3210
-    S-->>M: Owned server
+    M->>S: Launch session process on 127.0.0.1:3210
+    S-->>M: Private owner metadata and bounded identity
+    M-->>D: started, URL, workspace, versions
+  else Verified older TaskChef listener for this workspace
+    M->>S: Authenticated prepare, lease join, and commit
+    S-->>M: Signed final leases and bounded retry before shutdown
+    M->>S: Launch installed session version
     M-->>D: started, URL, workspace, versions
   else Standalone, unknown, stale, or different workspace
     H-->>M: Missing or incompatible identity
@@ -63,14 +72,15 @@ sequenceDiagram
   Note over D: Created-thread directive, when any, precedes final dashboard link
 ```
 
-When the MCP transport or plugin process closes, it closes only the server it
-started. A foreground `taskchef dashboard` listener identifies itself as
-standalone and is never reused as the canonical MCP dashboard, because its
-archive child process may inherit a different host environment. No TaskChef
-path terminates an incompatible listener or installs OS persistence.
+When one MCP transport or plugin process closes, the dashboard remains while a
+registered Codex session PID is alive. After every registered PID disappears
+for the grace period, the dashboard closes and exits. A foreground
+`taskchef dashboard` listener identifies itself as standalone and is never
+reused as the canonical session dashboard. No TaskChef path terminates an
+incompatible listener or installs OS persistence.
 
-Autostart and explicit ensures share the same manager promise, so concurrent
-initialization and recovery calls produce at most one owned listener. An
+Autostart and explicit ensures share the same manager promise, while
+cross-process port races converge through authenticated reuse. An
 explicit `dashboard.autostart: false` skips only activation-time ensure. Any
 failure is reduced to a fixed stderr diagnostic; tool registration and MCP
 availability continue. Activation never opens a browser.
@@ -82,13 +92,15 @@ The practical release handoff ends in this order:
 1. Install the released plugin.
 2. Activate or reload its new TaskChef MCP process.
 3. Run `$taskchef-dashboard` or call `ensure_dashboard`.
-4. Verify the expected TaskChef version, protocol `serverVersion`, `mcp`
+4. Verify the expected TaskChef version, protocol `serverVersion`, `session`
    launcher, canonical workspace, and canonical URL returned by the dashboard identity.
 
 Replacing plugin files alone cannot execute autostart because old code remains
-in the already-running MCP process. Installation does not necessarily reload
-Codex. An exact-compatible MCP dashboard may be reused; a standalone or unknown
-listener is never terminated or replaced.
+in an already-running MCP process. Installation does not necessarily reload
+Codex. Activation of the installed MCP authenticates and retires a verified
+older TaskChef listener before starting the installed session version. An
+exact-compatible session dashboard may be reused; a newer, standalone, or
+unknown listener is never terminated or replaced.
 
 ## Normal delegation and self-linking