taskchef 7.28.1 → 8.0.0

package/.codex-plugin/plugin.json

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

package/README.md

@@ -85,6 +85,21 @@ requested, opens the canonical path with the validated Codex Desktop CLI's
 exact match before indexing it. An open request without a verified native
 project is reported as partial setup, not delegation-ready.
 
+Update one indexed project with taskchef project update; repeated
+--github-repo values replace that entry's complete repository list while
+leaving every other project untouched. project list --json returns stable
+configuration and project-set hashes for postcondition checks.
+
+Whole-index replacement, project removal, and restore are preview-bound. Run
+them with --dry-run, inspect the exact diff, then apply with the returned
+hashes, counts, plan hash, and exact removed-name confirmation after the user
+approves every removed project. TaskChef creates private snapshots under
+backups/ before mutations and actual dashboard startup. Use taskchef backup
+list, create, verify, restore, and prune; restore never runs automatically and
+creates a pre-restore safety snapshot. If the live configuration is missing or
+malformed, preview an explicit config or state restore, then bind the apply to
+the preview's raw-state hash and plan with --confirm-unreadable-current.
+
 Reindexing catches TaskChef up with newly saved Codex projects by comparing
 exact canonical paths and indexing missing requested projects. It preserves
 existing curated entries and does not silently remove projects or overwrite
@@ -342,7 +357,10 @@ server path also rejects requests before discovering or invoking the CLI.
 Task details also show whole-task and per-turn token usage when `ccusage` can
 map the linked Codex thread. A completed turn briefly shows “Calculating token
 usage…” while TaskChef performs bounded deferred reconciliation, because
-the terminal lifecycle callback precedes Codex's final output write. Historical
+the terminal lifecycle callback precedes Codex's final output write. The
+dashboard also preloads missing, interrupted, and retry-eligible usage in a
+bounded background queue at startup, after task changes, and on a periodic
+recovery pass; opening task details is not required to start collection. Historical
 tasks may show a trustworthy task total while older turns remain “Token usage
 unavailable” when no cumulative turn boundaries were recorded. Input, cached
 input, output, reasoning, and total counts retain ccusage's categories. Dollar
@@ -361,6 +379,8 @@ wall-clock elapsed time, not model compute time, and malformed or reversed
 timestamp ranges are shown as unavailable.
 The header shows the running TaskChef package version reported by the same
 bounded health identity used for compatible-listener checks.
+The Settings page 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,

package/bin/taskchef.js

@@ -5,6 +5,16 @@ import { runCli } from "../src/cli.js";
 try {
   process.exitCode = await runCli(process.argv.slice(2));
 } catch (error) {
-  process.stderr.write(`taskchef: ${error.message}\n`);
+  if (process.argv.includes("--json")) {
+    process.stdout.write(`${JSON.stringify({
+      error: {
+        code: error.code ?? "ERROR",
+        message: error.message,
+        ...(error.details ? { details: error.details } : {}),
+      },
+    })}\n`);
+  } else {
+    process.stderr.write(`taskchef: ${error.message}\n`);
+  }
   process.exitCode = 1;
 }

package/docs/dashboard-lifecycle.md

@@ -33,6 +33,13 @@ 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
@@ -60,6 +67,16 @@ elapsed time, not model compute time.
 
 ## Start and reuse
 
+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.
+
+The dashboard watches both 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

package/docs/spec.md

@@ -14,6 +14,8 @@ is dated research, not contract.
 | **Dispatcher workspace** | The per-user local data project selected by `--workspace`, then `TASKCHEF_WORKSPACE`, then `~/.agents/taskchef`. |
 | **Dispatcher** | The Codex task that accepts a request, routes it, records it, creates executors, and returns without supervising them. |
 | **Configured project** | One routing target in `taskchef.json`, identified by canonical local path and described by `name`, optional `description`, `isGitRepository`, and `githubRepos`. |
+| **Mutation preview** | A read-only, hash-bound exact before/after project-index diff required before destructive replacement, removal, or restore. |
+| **State backup** | A private, verified snapshot under the dispatcher workspace's `backups/` directory. It never restores automatically. |
 | **Routing** | Selecting exactly one configured project and exactly one matching native Codex project for an outcome. |
 | **Delegated task** | One independently useful outcome represented by one TaskChef task UUID and snapshot. |
 | **Executor** | The native Codex task created to own and perform one delegated task. |
@@ -124,6 +126,32 @@ from the final derived semantic result. Interrupted outcomes MUST be excluded.
 These projections MUST NOT be persisted in schema 10 and remain compatibility
 aliases for existing callers.
 
+## Project-index mutation and recovery
+
+TaskChef MUST provide a targeted update that preserves every unrelated project
+and replaces an explicitly supplied repository list in full. Project list JSON
+MUST expose stable semantic hashes. Whole-index replacement, project removal,
+and restore MUST first return an exact diff and MUST reject stale hashes,
+incomplete removed-name confirmation, mismatched counts, and unconfirmed large
+count collapse. Agents MUST obtain explicit user permission for every removed
+project entry and verify the complete post-state.
+
+Every actual configuration mutation and actual dashboard-server start MUST
+create or deduplicate a mode-private, manifest-and-hash-verified state snapshot
+before writing. Mutations MUST append bounded attribution-free prepared and
+terminal audit records. Backup list, create, and verify are read-only except for
+explicit creation. Restore MUST default to projects only, show a diff, require
+explicit approval, and create a pre-restore safety snapshot. TaskChef MUST NOT
+restore automatically. State restore authorization MUST bind the selected
+backup and every selected live/source payload hash. Missing or malformed live
+configuration requires config or state scope plus exact raw-state and explicit
+unreadable-current confirmation; a forensic safety snapshot remains eligible
+for rollback when its own integrity verifies.
+
+The dashboard MUST distinguish an unreadable index from missing historical
+project paths, warn without rewriting state, and expose recovery guidance
+without backup payload contents.
+
 ## Optional usage projection
 
 TaskChef MUST pin one tested `ccusage` version as an optional dependency. It
@@ -162,6 +190,13 @@ 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
@@ -183,6 +218,8 @@ cumulative boundaries use different analyzer versions, requested pricing modes,
 or declared cost coverage. For GPT-5.6 with ccusage 20.0.20, provenance MUST
 disclose unverified cache-write coverage and TaskChef MUST NOT claim that the
 estimate includes those charges.
+The dashboard Settings response MUST report the provider version returned by
+the executable resolved for runtime use, not merely copy the dependency pin.
 
 Task IDs and non-null thread identities MUST be unique. The immutable intent
 fields MUST NOT change after recording.

package/docs/workflows.md

@@ -19,6 +19,9 @@ start, upgrade, shutdown, and security rationale.
 | `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/config-mutations.js` | Canonical hashes and exact field-level project diffs. |
+| `src/backups.js` | Private snapshot creation, verification, retention, and restore inputs. |
+| `src/config-audit.js` | Durable prepared/terminal configuration-mutation journal. |
 | `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 session ensure, authenticated reuse and upgrade handoff, and safe conflicts. |
@@ -428,7 +431,8 @@ after a later filesystem failure, the reported backup is the recovery source.
 Configuration and task mutations use the same `proper-lockfile` lock. ID and
 identity uniqueness checks, link eligibility, and result freshness occur
 inside the critical section. Writes use temporary files/hard links and atomic
-rename so readers see complete snapshots.
+rename so readers see complete snapshots. Configuration replacement syncs the
+new file and workspace directory before its audit transaction is committed.
 
 The dispatcher controls routing and immutable intent. The executor controls its
 cooperatively asserted identity and semantic result. Neither identity nor

package/index.js

@@ -1,6 +1,7 @@
 export {
   buildCopilotBrief,
   addProject,
+  createWorkspaceBackup,
   buildTaskSummary,
   canonicalDirectory,
   canonicalGitRoot,
@@ -12,6 +13,10 @@ export {
   initializeWorkspace,
   linkTask,
   listProjects,
+  listWorkspaceBackups,
+  pruneWorkspaceBackups,
+  readProjectIndex,
+  readWorkspaceMaintenance,
   manuallyTransitionTask,
   migrateTaskLog,
   prepareDispatch,
@@ -23,9 +28,18 @@ export {
   reportTaskResult,
   requireSafeId,
   removeProject,
+  restoreWorkspaceBackup,
   validateConfig,
+  updateProject,
+  verifyWorkspaceBackup,
 } from "./src/workspace.js";
 
+export {
+  configHash,
+  projectDiff,
+  projectSetHash,
+} from "./src/config-mutations.js";
+
 export {
   canonicalGithubRepository,
   matchProjectForGithubUrl,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "taskchef",
-  "version": "7.28.1",
+  "version": "8.0.0",
   "description": "A non-blocking interactive dispatcher for visible Codex tasks.",
   "license": "MIT",
   "author": "Favo Yang",

package/skills/taskchef-bootstrap/SKILL.md

@@ -15,8 +15,9 @@ all deterministic workspace operations.
 ## Boundaries
 
 - Keep implementation, tests, and reports in the TaskChef source repository.
-- Create and manage only `AGENTS.md`, `taskchef.json`, and `tasks.jsonl` in a
-  dispatcher workspace. Preserve unrelated user-owned paths.
+- Create and manage only AGENTS.md, taskchef.json, tasks.jsonl,
+  config-audit.jsonl, and TaskChef's private backups and maintenance artifacts
+  in a dispatcher workspace. Preserve unrelated user-owned paths.
 - Do not dispatch tasks or report on executor threads during bootstrap unless
   the user separately requests those actions.
 - Never create hooks, schedules, polling, daemons, login items, or system
@@ -55,7 +56,10 @@ all deterministic workspace operations.
 For adding, importing, removing, listing, or reindexing projects, read
 [project index](references/project-index.md). Preserve exact canonical local
 Codex project identity and existing curated entries; opening a folder is not
-proof of registration. Completion requires verifying the intended index entry.
+proof of registration. Completion requires verifying the intended index entry
+and the complete project set. Any operation that removes a project entry
+requires the user's explicit permission for the exact removed names; removing a
+repository URL from an entry does not authorize removing the entry.
 
 ## Optional model roles
 

package/skills/taskchef-bootstrap/references/project-index.md

@@ -85,6 +85,18 @@ requires an explicit user request and the project-management workflows below.
 
 ## Manage the project index
 
+Before every mutation, run project list --json and retain the complete
+normalized project set, count, and configHash. Use project update for changes
+to one existing entry, including replacing its complete githubRepos list.
+Never use whole-index replacement to edit one entry.
+
+Run destructive replacement or removal first with --dry-run. Present the
+complete diff and exact removed project names to the user and obtain explicit
+permission for those removals. Apply only with the preview's config hash,
+before/after counts, plan hash, exact removed-name JSON file, and count-collapse
+confirmation when requested. A request to remove a repository URL is not
+permission to remove a project entry. Do not use a generic force or yes flag.
+
 1. Bulk import with `project import <file|-> --json`. Input is a JSON array of
    objects containing `path` plus optional `name`, `description`, and
    `githubRepos`, which is always a JSON array of GitHub repository URLs. Before
@@ -94,9 +106,15 @@ requires an explicit user request and the project-management workflows below.
    canonical path, preserves an existing name or description when omitted, and
    unions existing and imported repository lists without duplicates. Use
    `--replace` only when the user explicitly requests replacement. Run
-   `project list --json` afterward and verify every imported entry.
-2. Inspect indexed projects with `project list --json`. Remove by name with
-   `project remove`. Existing task entries keep their project snapshots.
+   `project list --json` afterward and compare the complete project set with the
+   expected post-state. Verify every imported entry and prove all unrelated
+   entries are unchanged; matching counts alone are insufficient.
+2. Inspect indexed projects with project list --json. Update one entry with
+   project update; explicit repository arguments are the complete replacement
+   list. Remove by name only through the preview-bound workflow. Existing task
+   entries keep their project snapshots.
+3. On any postcondition mismatch, stop, report the failure, and offer backup
+   list plus a restore dry-run. Never restore automatically.
 
 Example managed-workspace import entry:
 

package/skills/taskchef-copilot/SKILL.md

@@ -58,6 +58,8 @@ cached brief.
   preserve its durable identity.
 - Never automatically retry a failure, interrupt a working task, or redelegate
   an existing executor as a new task.
+- Explain project-index warnings and suggest read-only backup list, verify, or
+  restore-preview commands. Never restore state without explicit user approval.
 - A missing executor link calls for passive waiting or identity inspection,
   not a retry, continuation, or reason to create another executor.
 - Keep same-assignment follow-up in the existing executor task. Independent new

package/skills/taskchef-dashboard/SKILL.md

@@ -16,5 +16,9 @@ Maintain only the canonical TaskChef dashboard.
    navigate to it. Browser absence, refusal, or blocked localhost navigation is
    non-fatal: still return the clickable URL and the ensure result.
 
+“Recover the dashboard” means restore server availability. Data recovery uses
+the explicit taskchef backup restore --dry-run workflow, shows a diff, requires
+user approval, and never runs automatically.
+
 Do not dispatch project work, read task briefs, inspect executor outcomes, poll,
 start a separate foreground CLI server, or modify TaskChef workspace files.

package/skills/taskchef-delegate/SKILL.md

@@ -30,8 +30,9 @@ stop and report that the TaskChef plugin must be reloaded or installed.
 
 ## Boundaries
 
-- Treat only `AGENTS.md`, `taskchef.json`, and `tasks.jsonl` as TaskChef-managed
-  dispatcher files. Preserve unrelated user-owned paths.
+- Treat only AGENTS.md, taskchef.json, tasks.jsonl, config-audit.jsonl, and
+  TaskChef's private backups and maintenance artifacts as managed dispatcher
+  state. Preserve unrelated user-owned paths.
 - Use real Codex tasks, never collaboration or subagent tools.
 - Never use hooks, schedules, daemons, background monitors, recent-task
   searches, transcripts, hidden reasoning, or polling for identity.