taskchef 8.6.2 → 8.7.0

package/docs/spec.md

@@ -159,75 +159,30 @@ without backup payload contents.
 
 ## Optional usage projection
 
-TaskChef MUST pin one tested `ccusage` version as an optional dependency. It
-MUST prefer that package-local executable and MAY use an exact-version,
-cache-friendly `npx` invocation when a plugin-only installation has no local
-dependency. The `npx` invocation MUST only resolve the pinned native executable
-and MUST NOT launch the analyzer against Codex data. TaskChef MUST execute that
-native binary directly. The adapter MUST first request structured Codex output
-with live-capable online pricing and retry with ccusage's bundled offline
-pricing after a bounded failure. TaskChef MUST NOT parse, store, or serve raw
-Codex rollout files, prompts, responses, transcripts, or reasoning. Analyzer,
-npm, network, timeout, malformed output, unknown pricing, or an unresolved
-thread MUST NOT block lifecycle tools or dashboard loading.
-
-Dashboard-manual turns are administrative events, not Codex executions. They
-MUST immediately report per-turn usage as unavailable, MUST NOT schedule or
-store a cumulative usage boundary, and MUST NOT receive a token or cost delta.
-A later executor turn MUST use the nearest preceding reliable executor
-boundary, skipping any intervening dashboard-manual turns.
-
-The mode-0600 `.taskchef-usage.json` schema 2 cache stores only normalized cumulative
-token boundaries, per-turn deltas, model names, estimated cost, source version,
-and freshness. It is independent of task-log schema versions so legacy logs remain
-readable. Schema 1 usage caches MUST migrate in memory by discarding their
-TaskChef-specific cost-coverage classification while preserving valid ccusage
-cumulative estimates. Writes MUST use the workspace lock and atomic replacement. Symlinked
-or unsupported cache files MUST be rejected. Writes MUST compact the derived
-cache to recent task projections, recent per-turn results, and the latest
-cumulative boundary. An oversized legacy cache MUST be treated as rebuildable
-derived data so it cannot permanently disable usage reporting.
-
-A linked Codex thread MAY map to multiple ccusage session segments. TaskChef
-MUST aggregate only records whose primary durable thread UUID is that exact
-identity; a UUID appearing only as a nested suffix MUST NOT be attributed to
-the parent or child TaskChef task. It MUST retain input, cached-input, output,
-reasoning-output, and total fields without adding cached or reasoning subsets
-into totals a second time.
-
-After a terminal report, TaskChef MUST mark the turn `calculating` and perform
-bounded deferred reconciliation without delaying the lifecycle response.
-The dashboard MUST also preload eligible derived usage in its existing service
-lifecycle without requiring a task-detail request. Startup, task-log changes,
-and periodic recovery passes MUST consider missing, interrupted, and
-cooldown-expired records; successful current-generation records MUST remain
-cached. Background work MUST be deduplicated, MUST enforce a small global
-concurrency limit, MUST use bounded delayed retries, and MUST stop when the
-dashboard closes.
-Per-turn usage MUST be a non-negative delta between adjacent reliable cumulative
-boundaries. A first recorded turn MAY use zero as its baseline. Historical
-turns without boundaries and decreasing or ambiguous snapshots MUST be labeled
-`unavailable`, never zero or estimated. A historical task MAY still show its
-resolvable cumulative total. A boundary is reliable only after two consecutive
-samples agree. Exhausted unstable sampling and a newer turn beginning before
-stabilization MUST leave that turn unavailable and MUST NOT establish a delta
-baseline. Zero is valid for the first turn only when TaskChef observed that turn
-in progress before its terminal report; a first historical terminal turn MUST
-remain unavailable even when its cumulative task total is resolvable.
-
-Every available projection MUST identify ccusage, its version when available,
-the requested online or fallback offline pricing mode, and usage freshness.
-The online mode records TaskChef's request, not a claim about ccusage's internal
-cache. Dollar values MUST be labeled API-equivalent estimates. Positive token
-usage with a zero or missing analyzer cost MUST display cost unavailable, not
-`$0.00`. A per-turn dollar delta MUST be unavailable when its adjacent
-cumulative boundaries use different analyzer versions or requested pricing
-modes. When ccusage supplies a valid cumulative estimate, TaskChef MUST display
-it without applying its own model-family or cache-write coverage policy. A model
-family change between otherwise compatible boundaries MUST NOT prevent TaskChef
-from deriving the per-turn estimate.
-The dashboard Settings response MUST report the provider version returned by
-the executable resolved for runtime use, not merely copy the dependency pin.
+TaskChef MUST use its own saved-record accounting engine for the board and web
+dashboard. Usage requires Node.js 22.18+ and readable local Codex records.
+Unavailable usage MUST NOT block lifecycle tools or dashboard loading.
+
+Per-turn usage MUST match the native Codex turn ID. A dispatcher turn without
+that match MUST show unavailable turn usage, while its chat total MAY remain
+available. Administrative dashboard turns MUST NOT receive execution usage.
+Historical tasks MUST remain lazy; opening Details reads their usage. Requests
+MUST be deduplicated and bounded, and queued work MUST stop on dashboard close.
+
+The engine MUST include descendant usage once, preserve input, cached input,
+output, reasoning, and total categories, and avoid counting cached input or
+reasoning subsets twice. Missing logs or parent-turn links MUST mark known
+subtotals incomplete. Dollar values MUST be API-equivalent estimates using
+known model prices. Unknown model prices MUST NOT imply a zero-dollar cost.
+
+Board accounting caches MUST live under the TaskChef state directory's `cache/`
+folder. The web dashboard MUST retain normalized usage in the mode-0600
+`.taskchef-usage.json` cache. Writes MUST use the workspace lock and atomic
+replacement. Existing schema-2 projections from the previous provider MUST
+remain readable. Cache files MUST contain accounting data and source metadata,
+not prompts, replies, or reasoning text. Source changes MUST invalidate derived
+accounting results. Cache errors MUST allow source accounting to continue.
+The dashboard Settings response MUST identify TaskChef and its package version.
 
 Task IDs and non-null thread identities MUST be unique. The immutable intent
 fields MUST NOT change after recording.

package/docs/taskchef-next-github.md

@@ -0,0 +1,206 @@
+# GitHub PR status in TaskChef
+
+TaskChef reads PR attachments from `state_5.sqlite:thread_attachments`.
+Only records with `attachment_type = pull_request` count. The `payload.url`
+identifies the PR. A transcript link alone does not establish PR ownership. The card uses only registered PRs referenced in the latest prompt/reply or successfully attached by a saved `codex_app.attach_artifact` call in that turn. Older chat attachments do not decide the latest turn's state.
+Older Codex databases without this table show no PR attachments.
+
+## Connect GitHub
+
+1. In plugin settings, select **GitHub → Connect GitHub**, then **Sign in with GitHub**. The Done column also links to these connection controls when signed out.
+2. Enter the displayed code on GitHub and approve access.
+3. Install the GitHub App on the accounts and repositories you want to read.
+   **Repository access** opens GitHub's installation settings.
+
+TaskChef includes its registered GitHub App client ID. Once connected, the native settings action becomes **Manage GitHub**. Existing local client-ID overrides remain internal; the public settings page has no client-ID field. The device code, access token, and refresh
+token stay in the local MCP server's system credential store. They never go to
+the sidebar, ordinary JSON files, shell arguments, or a TaskChef hosted server.
+On macOS this is Keychain; Windows uses Credential Manager; Linux requires
+Secret Service. Release packaging includes credential-store bindings for macOS and Windows on
+ARM64/x64, and Linux on ARM64/x64 with glibc or musl. There is no plaintext fallback. A locked or unavailable store
+shows an error. GitHub's own approval and repository-selection pages control
+access. Organizations may require administrator approval.
+
+**Disconnect this computer** removes the local credential and clears the
+process's PR cache. It does not revoke the GitHub grant. Revoke that separately
+in GitHub's authorized-app settings if desired.
+
+## Register the app
+
+Register a GitHub App, enable **Device flow**, and keep expiring user access
+tokens enabled. Disable webhooks. Request these repository permissions:
+
+| Permission | Access | Purpose |
+| --- | --- | --- |
+| Pull requests | Read-only | Open, draft, closed, and merged PRs |
+| Checks | Read-only | CI check results |
+| Commit statuses | Read-only | Older CI status results |
+| Metadata | Read-only | Required by GitHub |
+
+Use the project repository as the homepage. Device flow needs no callback
+server, private key, or client secret. GitHub requires the app to be installed
+for private repository access. Choose **Any account** if distributing it to
+other users. Registration does not itself give the app access to repositories.
+
+The preview supports GitHub.com only. Enterprise hosts show an unavailable
+status. Do not enter an OAuth App ID or a personal access token in the setting.
+
+## Board rules
+
+Archived chats go to the optional Archived column before these rules apply.
+Chats with no saved turn are hidden. Running always takes priority over Done marks.
+
+### With an active schedule
+
+| Latest turn | Result | Column |
+| --- | --- | --- |
+| Either input source | In progress | Running |
+| Either input source | Failed or interrupted | Waiting, with Interrupted tag |
+| Scheduled prompt | Completed, with any PR state or no PR | Scheduled |
+| Human prompt | Completed; all latest-turn PRs merged | Scheduled |
+| Human prompt | Completed; unmerged/unknown PR or no PR | Waiting for input/review |
+
+A saved heartbeat marker identifies a scheduled prompt. If input source cannot
+be verified, use the human-input rules. Any active schedule keeps the chat
+scheduled, even when the schedule that started the latest turn is now paused.
+Manual Done is disabled until all schedules are paused.
+
+### Without an active schedule
+
+| Latest turn / user action | Column |
+| --- | --- |
+| In progress | Running |
+| Marked Done for this turn, with no latest-turn PR | Done |
+| Failed or interrupted, without a Done mark | Waiting, with Interrupted tag |
+| Completed; all latest-turn PRs merged | Done |
+| Completed; any unmerged or unknown latest-turn PR | Waiting for input/review |
+| Completed; no latest-turn PR and no Done mark | Waiting for input/review |
+| Unrecognized saved turn status | Unverified, within Waiting |
+
+A new turn resets a manual Done mark. Passing CI does not guarantee merge
+approval or that every branch-protection requirement is met. A closed PR
+without merge remains Waiting for a human.
+
+Cards show compact PR icons beside their time. Local SVG drawings match the
+Codex branch layout: a curved merged branch, a plus on the plain open icon,
+and colored status dots in place of the lower-right node. Cards and popup
+rows use the same glyphs. The whole status line shares
+one popup on hover or focus. It shows work duration, each linked PR title with
+its number first, turn usage, and the next scheduled run, each on a separate
+line with an icon. PR titles stay on one line and use an ellipsis. CI state is
+represented by the PR icon; the popup has no separate CI row. Subagent count
+appears only in Details. Missing information is omitted. Mergeability and check
+time are not shown.
+Unknown PR status uses a neutral icon without an Unavailable label on the card.
+Repository access failures add a warning icon and a Grant access link to the
+TaskChef GitHub App installation page. Confirmed permission errors say Access
+denied; GitHub NOT_FOUND responses say Cannot access because they can also
+mean the repository or PR was removed. Network and rate-limit errors do not
+claim a permission failure. Valid PR state remains visible if CI access fails.
+Tab moves from the status line to its PR link; Escape closes the popup.
+
+![Shared card status popup](images/taskchef-unified-status-popup.jpg)
+
+![PR icon shape comparison](images/taskchef-pr-icon-comparison.jpg)
+
+## Codex sidebar icon research
+
+OpenAI's changelog confirms draft, open, merged, and closed PR badges. It does
+not publish a color legend. The table below comes from read-only inspection of
+the installed desktop application's compiled `webview/assets/app-initial` bundle
+on 10 October 2026. It is an implementation observation, not a documented API.
+
+| Appearance | Installed Codex rule |
+| --- | --- |
+| Dashed PR icon | Draft |
+| Purple merge icon | Merged |
+| Red closed icon | Closed without merge |
+| PR with red dot | Merge conflicts or failing CI |
+| PR with green dot | Passing CI or `canMerge = true` |
+| PR with yellow dot | Other open PR state (`in_progress`) |
+
+The implementation selects `successful` when CI passes but `canMerge` is false,
+and `ready` when `canMerge` is true. Both use the same green dot. Yellow does
+not specifically mean no CI, and green alone does not prove merge readiness.
+TaskChef reads PR state, title, draft state, head revision, merge conflicts,
+merge state, and the latest commit's combined check status. It treats CLEAN or
+HAS_HOOKS with MERGEABLE as ready to merge. The icon distinguishes Checks
+passed from Ready to merge; the shared popup uses the same state icon. GitHub can report an unknown merge state briefly;
+TaskChef checks that state again while the card is visible.
+
+## Refresh and failure behavior
+
+The board still polls its local MCP server every five seconds while visible.
+GitHub checks use the board's project and time filters. The default time filter is
+All time. Only rendered cards that intersect the visible viewport start requests.
+Opening the board first reads local records without GitHub requests. Card visibility
+then schedules a check after a 250 ms debounce. Scrolling, searching, filtering,
+and loading more cards update this set. Offscreen cards do not start requests.
+Opening one chat's Details checks that chat on demand. New chats follow the same
+rule when their latest turn has an owned PR.
+
+PR results are saved in `cache/github-prs.json` beside TaskChef settings,
+with restricted file permissions. This file contains no tokens. A shared local
+lock protects reads and writes across MCP processes. Results are tied to the
+GitHub account and client ID; disconnect and sign-in clear them.
+
+Settled results have no short expiry. A new turn, a changed turn state, a new
+PR, or manual Refresh triggers a board check. Details fetches only PRs with no saved result. Pending or unknown CI, an unknown
+merge state on an open or draft PR, and failed checks of GitHub availability retry after 60 seconds
+while the card is visible. Offscreen cards do not trigger these retries.
+Passing or failed CI stays cached until another trigger. A merge made on GitHub
+after a settled result is saved needs Refresh to be detected.
+
+Queries combine up to 25 PRs per request. Hidden CLI/exec chats and archived
+history do not start requests. Opening, reopening, and automatic Details polling do not force a check. Historical results have no expiry; explicit Refresh also updates the open detail’s PRs.
+Rate limits still apply to explicit refreshes. A malformed or unwritable cache
+reports an error instead of silently fetching the entire board.
+
+Without GitHub sign-in, automatic Done from PR merge cannot be verified. Manual
+Done for chats with no latest-turn PR still works. The Done column shows a
+Connect GitHub link until sign-in succeeds.
+
+GitHub receives repository names and PR numbers only, plus its authentication
+token. Task titles, prompts, replies, and local paths are not included.
+
+Unavailable status never counts as merged. A failed refresh replaces the cached
+status with Unavailable. Codex database failures remain fatal to the board;
+GitHub failures are shown in the connection dialog and PR badges.
+
+Device sign-in polls only while its dialog is open and visible. It follows
+GitHub's polling interval and slows down when requested. Pending sign-in is
+stored in the credential store so another local MCP process can continue it.
+Refresh tokens are rotated under a local lock shared by MCP processes.
+
+## References
+
+- [GitHub App device flow](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)
+- [Refresh user tokens without a device-flow client secret](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/refreshing-user-access-tokens)
+- [GitHub App permissions](https://docs.github.com/en/rest/authentication/permissions-required-for-github-apps)
+
+- [OpenAI changelog: PR status badges](https://learn.chatgpt.com/docs/changelog)
+
+## Schedule clock
+
+An active schedule appears as a clock before the PR icons, rather than text.
+The shared status popup uses the desktop scheduler's `automations` table in
+`sqlite/codex-dev.db`. When `next_run_at` is set, TaskChef shows
+`next_run_nominal_at` if present, otherwise `next_run_at`. It uses the earliest
+known time across active schedules for that chat. Reads are short and read-only.
+Missing next-run metadata does not change the schedule flag or guess a time;
+the popup omits the next-run line.
+
+## Private repository CI reads
+
+PR state and merge metadata use GraphQL. CI uses the head revision with the
+REST check-runs and combined commit-status endpoints. These endpoints use the
+app's existing read-only Checks and Commit statuses permissions. Reading a
+GraphQL commit object can require Contents access on private repositories;
+TaskChef does not request Contents access. A CI error keeps the independently
+returned PR state. Empty legacy status lists do not count as pending CI.
+If more than 100 latest check runs are returned, TaskChef keeps CI unknown
+instead of claiming success from an incomplete page.
+
+### Earlier-turn PR on cards
+
+Card placement uses only the latest turn’s owned PRs. When that turn has no PR, a visible card can display the most recently mentioned owned PR from an earlier turn in the selected rollout. The status popup labels it **Earlier turn PR**. This display fallback never moves a chat to Done or restricts manual Done. History lookup is lazy and cached until the database records change; GitHub status uses the existing scoped cache. Details retains its full PR list.

package/docs/taskchef-next-status-research.md

@@ -0,0 +1,102 @@
+# TaskChef Next status research
+
+> Research note, not a product contract. See [the specification](spec.md) for
+> current TaskChef behavior and [the sidebar guide](mcp-app.md) for the current
+> TaskChef Next implementation.
+
+## Local data and proposed labels
+
+TaskChef Next can read chat metadata from `state_5.sqlite:threads` and the
+latest turn from `thread_history_1.sqlite:thread_turns`. A turn's `completed`
+status means Codex ended that turn. It does not say whether the user's larger
+task is finished or whether the assistant asked for input. The sidebar now applies the workflow rules described in [the sidebar guide](mcp-app.md).
+
+The proposed board labels are workflow rules, not semantic judgments:
+
+| Label | Proposed rule |
+| --- | --- |
+| Running | Open chat; latest selected turn is `inProgress`, regardless of timestamp age. |
+| Waiting for input/review | Open chat; latest turn is `completed`. This includes ordinary idle chats, even when no question or review was requested. |
+| Done | User marks a chat without PRs done, or its latest turn completed and all attached PRs are confirmed merged. Both require no active schedule. A new turn clears a manual Done mark. |
+| Archived | Chat is archived. Hidden by default and shown in a separate column when enabled. |
+| Interrupted | Open chat; latest turn is `interrupted` or `failed`. Show the recorded error when available. |
+
+These labels describe the **board queue**, not verified task outcomes. Waiting
+means the chat is open and Codex is idle; it does not prove that Codex requested
+input or review. Done means a manual mark for a chat without PRs, or confirmed merged status for all attached PRs.
+Archived is separate; archiving does not prove that the underlying work succeeded.
+The GitHub integration uses merged PRs for Scheduled when a schedule is active, otherwise Done, and unmerged or unavailable PRs
+for Waiting after a completed turn. Real sign-in needs a registered GitHub App.
+
+The archive flag takes precedence over an old turn status. The earlier proposal
+used a two-minute activity cutoff for Running. That proposal is superseded:
+the sidebar follows the latest selected turn status and does not infer a stop
+from timestamp age. Unrecognized turn states remain Unverified. Chats with no
+turn row are omitted. The sidebar excludes JSON subagent sources in
+`threads.source` and includes all eligible chats with a current-rollout turn.
+
+Counts from all unarchived database rows are not counts of current work. The
+optional Updated filter narrows the view; it does not change queue labels.
+
+## Scheduled work
+
+An active schedule is a flag on a chat, alongside its current workflow label.
+The board has a Scheduled column for idle scheduled turns. Running and
+Interrupted take precedence; ordinary completed input returns to Waiting while
+the schedule badge remains.
+
+Local heartbeat configurations have `target_thread_id` and `status`. The latest
+turn points through `first_user_item_id` to `thread_items.item_json`. Observed
+heartbeat inputs contain a `<heartbeat>` wrapper with an `automation_id` and
+have no `clientId`; ordinary desktop inputs have a `clientId`. The sidebar
+matches the wrapper to a known automation on that chat rather than matching
+execution time. This is an observed internal format, not a supported stable API.
+It does not infer scheduled origin from a missing `clientId` alone. Paused
+schedules do not place idle chats in Scheduled. Cron runs are distinct from
+heartbeat chats and are not linked by this rule.
+
+## Optional model judgment
+
+A local Codex app-server client can reuse the desktop user's saved Codex login.
+The experiment used `gpt-6-luna` with reasoning effort `none`: it started an
+ephemeral, read-only app-server thread and sent a `turn/start` request with an
+`outputSchema` requiring `state`, `confidence`, `evidence`, and `reason`. The
+`state` values were `done`, `needs_input`, and `unknown`. The request included
+real chat messages selected from `thread_history_1.sqlite:thread_items` and
+received a schema-conforming JSON decision without an `OPENAI_API_KEY`. This
+proves the route is possible, not that its judgments are accurate. The
+app-server adds substantial context and latency, and the experiment did not
+establish accuracy
+across different chat types. Keep this as an optional enrichment route; it is
+not needed to compute the proposed workflow labels. A separate Jev experiment
+also returned a typed decision, but it needs separate TypeSafe credentials.
+
+If semantic judgment is later added, compare it with independent human labels
+and retain the evidence used for each decision. Do not silently convert a
+model's guess into a database fact.
+
+## Cloud and GitHub prerequisites
+
+The local scanner does not contain durable-host cloud chats. A read-only test
+of `codex cloud list --json --limit 20` returned an empty task list, while the
+desktop thread tools had returned five durable-host chats. This does not prove
+that all cloud accounts behave the same way. It does show that this command
+cannot supply the missing chats in the tested account. Do not replace the
+missing cloud list with an empty list presented as complete. A supported
+code-driven source for these desktop cloud chats is still needed.
+
+The current Codex database has `state_5.sqlite:thread_attachments`. Records with
+`attachment_type=pull_request` provide the attached PR URL in `payload.url`.
+This corrects the earlier schema scan. Transcript links are not attachments.
+
+TaskChef includes its registered GitHub App public client ID with device flow
+enabled. Users connect through the native GitHub settings action.
+TaskChef uses read-only Pull requests, Checks, and Commit statuses permissions.
+Access and refresh tokens stay in the local OS credential store; the sidebar
+receives no tokens. There is no client secret, private key, or developer CLI
+credential in the product flow.
+
+After a completed turn, a nonempty attachment list with every PR confirmed merged
+means Done. Open, draft, closed without merge, and unavailable PRs stay Waiting.
+Running, Interrupted, and Archived retain their rules. Manual Done applies only
+without PR attachments. See [setup, polling and validation limits](taskchef-next-github.md).

package/docs/taskchef-next-storage.md

@@ -0,0 +1,167 @@
+# TaskChef: Codex storage
+
+[Edit the storage diagram](diagrams/taskchef-next-storage.drawio) · [Storage PNG](diagrams/taskchef-next-storage.drawio.png)
+
+[Edit the reply lookup example](diagrams/taskchef-next-reply-lookup.drawio) · [Lookup PNG](diagrams/taskchef-next-reply-lookup.drawio.png)
+
+![Files and their tables](diagrams/taskchef-next-storage.drawio.png)
+
+The storage diagram groups tables inside their database files. The separate example below shows current-reply lookup. Selected fields only; these internal schemas can change.
+
+![Current reply lookup after a revert](diagrams/taskchef-next-reply-lookup.drawio.png)
+
+## One chat, two possible IDs
+
+Suppose chat **C** has a turn **T**:
+
+| Store | Ordinary history | After Codex selects a new rollout R |
+| --- | --- | --- |
+| `state_5.sqlite` → `threads.id` | C | C: the chat ID stays the same |
+| `threads.rollout_path` | `rollout-<timestamp>-C.jsonl` | `rollout-<timestamp>-C_R.jsonl` |
+| `thread_history_1.sqlite` → `thread_turns.thread_id` | C | R: use the ID after the underscore |
+| `thread_turns.turn_id` | T | The latest turn in R |
+| `thread_items.thread_id` | C | R |
+| JSONL → `session_meta.payload.id` | C | C: this is still the chat ID |
+
+The filename examples use C and R as short labels. Real filenames contain UUIDs. `.jsonl.zst` uses the same ID rule. Codex's [rollout filename resolver](https://github.com/openai/codex/blob/main/codex-rs/rollout/src/metadata.rs) describes the separate ID after a revert. For paginated history, an unrecognized selected filename is an error. Legacy history supports noncanonical filenames with a stable chat-ID lookup. Old turn rows may remain under C. They belong to earlier history and must not replace the selected rollout's current turn.
+
+TaskChef reads the filename from SQLite. It does not open the log to determine this lookup ID. Schedules, subagent links, navigation, and local Done marks continue to use the stable chat ID.
+
+## Main tables and records
+
+| File | Table or record | Example and use |
+| --- | --- | --- |
+| `state_5.sqlite` | `threads` | Chat C, name “Fix login”, project, archived flag, selected rollout path. Also holds model, reasoning effort, token total, pin and project metadata. |
+| `state_5.sqlite` | `thread_spawn_edges` | Parent C → child D. Exclude D from the board; count it on C. |
+| `thread_history_1.sqlite` | `thread_turns` | Rollout R, turn T, `status = completed`, duration and start/end times. This means the turn ended; the task may still need input or review. |
+| `thread_history_1.sqlite` | `thread_items` | `(R, T, item I)` with `item_type = userMessage`, `agentMessage`, `commandExecution`, `mcpToolCall`, or `fileChange`. `item_json` contains the saved item body. The board reads the latest turn's first input to identify a heartbeat. It also reads the linked final reply, or the latest saved agent message in that turn when no final reply is linked. It never uses a previous turn as the current reply. Card excerpts contain at most 2,000 characters; the UI displays two lines. |
+| `thread_history_1.sqlite` | `thread_history_projection_state` | R with the next byte offset and record ordinal. Tracks how far the saved history has been projected into SQLite. The board does not use it. |
+| Rollout `.jsonl` | One JSON record per line | `type = session_meta`, `event_msg`, `response_item`, etc. The inner `payload.type` gives the event or response kind, such as `task_started` or `task_complete`. There are no SQL tables in this file. |
+
+The optional log reader adds bounded message counts for one selected chat. It never supplies board status when SQLite fails.
+
+## Other observed tables
+
+The board does not query these tables. This list records table names seen during the local schema check; it is not a supported schema contract.
+
+| Database | Other tables |
+| --- | --- |
+| `state_5.sqlite` | `_sqlx_migrations`, `thread_dynamic_tools`, `backfill_state`, `remote_control_enrollments`, `external_agent_config_imports`, `thread_sections`, `rollout_migration_state`, `rollout_migration_skipped_rollouts`, `projects`, `project_roots`, `project_idempotency_keys`, `thread_attachments` |
+| `thread_history_1.sqlite` | `_sqlx_migrations`, `thread_realtime_items` |
+
+TaskChef also reads heartbeat links from `automations/*/automation.toml`. Manual Done marks are saved in TaskChef's separate state file. Neither source modifies Codex's databases.
+
+## Project picker sorting
+
+The button beside Search projects cycles Most recent → A–Z → Z–A. Most recent is the default each time the view mounts. It uses the latest chat update time per project among chats allowed by the source and archive settings. Projects without matching chats follow those with activity, ordered by name. All projects stays first and No project stays last. Sorting preserves the search and selected project.
+
+
+## Detail timing and PR cache
+
+Details shows the latest turn’s duration and the sum of saved finished-turn
+`duration_ms` values for the selected history ID. For a running turn, the UI adds
+its elapsed time once. Idle time and child chats are excluded. The tooltip reports
+finished turns whose duration is missing. Earlier rollout histories are not added;
+after a rewind, this is recorded time for the selected history, not a lifetime total.
+The aggregate is cached until either database changes.
+
+Historical PR results use the existing disk cache. Opening Details fetches only
+URLs with no saved result; it does not expire those results or invalidate them when
+a different turn starts. Refresh explicitly checks the open detail’s PRs again.
+The board still checks newly referenced PRs and retries pending or unknown current
+PR states while their cards are visible. Disconnecting or changing the GitHub
+account clears its cached results. Local history links are cached per database
+snapshot and rebuilt when the database changes.
+
+## Saved work time and usage
+
+Visible board cards and Details read accounting events from the chat's saved rollouts and all
+nested subagent chats found through `thread_spawn_edges`. Board inventory and
+turn state still come from the databases. A database query failure remains fatal.
+Optional accounting errors are shown as partial data.
+
+The reader discovers older rollouts under `sessions` and `archived_sessions`.
+It includes plain JSONL and zstd-compressed JSONL files. It checks this file
+inventory at most once per minute while usage is requested.
+It caches compact accounting records in the MCP process. Unchanged files are
+not read again. Appended files are read from the last complete line; replaced
+or truncated files are read again. Changed compressed files are decoded again;
+unchanged compressed files use the same cache. A runtime without zstd support
+marks compressed histories partial. Concurrent views share this reader.
+
+Computed accounting results are saved under TaskChef's state directory in
+`cache/usage/`, with one hashed file per chat and duration-view variant. Files
+contain accounting totals and source metadata, not prompts or replies. Private
+file permissions and atomic writes protect the local cache. Before reusing it,
+the reader checks the latest turn ID, linked descendants, rollout metadata,
+duration fallbacks, and pricing table. A new turn invalidates the old result;
+appended logs also invalidate it while a turn runs. An unchanged result survives
+an MCP restart without parsing the logs again. Damaged caches are rebuilt, and
+cache write failures do not prevent source accounting. Compact parsed records
+remain in memory for incremental updates. Saved source coverage also detects
+an older rollout that disappears from the inventory. Missing sources keep
+known historical totals as incomplete; corrections within the same logical
+rollout can still recalculate them. Moving a rollout into archived storage
+preserves its source identity.
+
+Work time sums finished turns across the parent's saved rollouts, deduplicated
+by turn ID, and joins known durations from the selected SQLite history. It adds
+current running time in the view. Idle time and subagent time are excluded.
+Missing or unreadable histories make this total partial.
+
+Usage reads `token_count` events. Chat totals use cumulative counter changes;
+latest-turn usage uses individual call counters and the surrounding turn ID.
+Copied events and repeated unchanged counters are counted once. A missing
+boundary or counter correction does not prevent later turns from reporting.
+Subagent usage is included once per descendant chat. `root_turn_id` assigns
+child calls to the latest parent turn. Missing parent links leave that turn
+partial. Deleted logs, missing calls, and counter resets can prevent an exact
+historical result; the UI never claims that the displayed subtotal is a bill.
+
+Cost uses each saved call's model and input/cache-read/cache-write/output
+counts. Reasoning tokens are already included in output tokens. Unknown models
+remain unpriced. Missing calls can leave tokens known but cost partial. An
+incomplete token or cost column has a superscript 2 on its label and a `≥`
+prefix on each known incomplete value. Cost also has
+superscript 1 for the API-price estimate note. The footnote explains why the
+estimate is incomplete.
+
+The package ships a dated table of standard USD API prices from
+<https://developers.openai.com/api/docs/pricing>. While Details is used, the
+server checks the public Markdown version in the background at most weekly.
+A failed update is retried after an hour. The last valid update is saved beside
+TaskChef's own Done state; the bundled table works offline. No API key, chat
+content, or GitHub token is sent for this public request. If the published table
+format changes, the last valid prices remain in use.
+
+Estimates apply current standard API prices, including the published long
+context rates above 272K input tokens. They do not reproduce subscription
+charges, historic prices, fast-mode surcharges, regional fees, or tool fees.
+
+
+### Unread chats
+
+The board reads `electron-thread-read-state-v1` from Codex's
+`.codex-global-state.json`. It uses the live unread IDs for the single account
+and the local execution-host key recorded in `legacyMigration.adoptedHostIds`.
+Legacy unread lists are migration snapshots and are not used. Missing,
+unsupported, cleared, or ambiguous account/host mappings show no dot.
+The existing metadata file stamp detects changes during board polling even
+when the SQLite databases do not change. Opening TaskChef Details does not
+modify Codex read state; opening the chat in Codex lets Codex manage it.
+
+## Cache locations
+
+Board disk caches share the state directory's `cache/` folder:
+
+- `cache/usage/`: derived accounting results.
+- `cache/pricing.json`: cached official model pricing.
+- `cache/github-prs.json`: PR status results.
+
+The reader moves older caches into these locations on first use. It preserves
+an existing destination. Settings, Done marks, and authentication data remain
+outside `cache/` because they are persistent state, not rebuildable caches.
+The web dispatcher keeps its workspace-specific `.taskchef-usage.json` projection
+file for compatibility with existing task records.
+
+Usage caches retain normalized token counters for known rollout sources, without message content. If an older source disappears, those counters are reconciled with live counters so new usage continues to increase the known subtotal.

package/docs/workflows.md

@@ -27,8 +27,10 @@ start, upgrade, shutdown, and security rationale.
 | `src/dashboard-manager.js` | Concurrent session ensure, exact health reuse, bounded version replacement, and safe conflicts. |
 | `src/dashboard-session-process.js` | Independent loopback server, signals, and in-memory 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. |
+| `src/usage.js` | Normalized private usage projections and historical cache compatibility. |
+| `src/usage-tracker.js` | Usage-provider factory and compatibility with injected cumulative readers. |
+| `src/recorded-usage-tracker.js` | Lazy native-turn projections, descendant totals, bounded requests, and persistent web usage. |
+| `src/codex-session-usage.js` | Saved Codex accounting, incremental file reads, derived disk caches, and shared pricing. |
 
 The MCP process resolves `TASKCHEF_WORKSPACE` once and never accepts a model
 supplied path. The CLI resolves `--workspace`, then the environment, then the

package/node_modules/@napi-rs/keyring/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 N-API for Rust
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.