taskchef 7.28.0 → 7.29.0

package/.codex-plugin/plugin.json

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

package/README.md

@@ -162,6 +162,16 @@ Use $taskchef-executor to execute and report this delegated TaskChef assignment.
 <!-- taskchef_id=c0f010ff-84f2-4838-a69d-0ff1f5d721d7 -->
 ```
 
+### Model roles
+
+TaskChef can apply personal Planner, Implementer, and Reviewer model preferences
+from `~/.codex/agents/`. Planning-only tasks use Planner, while coding tasks and
+single tasks that plan and then execute use Implementer throughout. To apply
+both models, finish a Planner task that saves its plan, then create a separate
+Implementer task using that plan. Reviewer preferences apply when a workflow
+explicitly starts a review subagent. Explicit per-task model choices take
+precedence, and changes affect only tasks created afterward.
+
 ## Work with and report executors
 
 Open an executor as an ordinary Codex task. Each executor reports `working`
@@ -332,7 +342,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
@@ -351,6 +364,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/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

package/docs/spec.md

@@ -162,6 +162,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 +190,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/package.json

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

package/scripts/roles/resolve_roles.py

@@ -8,6 +8,7 @@ import argparse
 import json
 import os
 from pathlib import Path
+import re
 import sys
 import tomllib
 
@@ -57,11 +58,9 @@ def read_layer(directory):
     return found, problems
 
 
-def resolve(project=None, codex_home=None, explicit_model=None, explicit_effort=None):
+def resolve(codex_home=None, explicit_model=None, explicit_effort=None):
     home = Path(codex_home or os.environ.get('CODEX_HOME') or Path.home() / '.codex').expanduser().resolve()
     personal, problems = read_layer(home / 'agents')
-    local, local_problems = read_layer(Path(project).resolve() / '.codex' / 'agents') if project else ({}, [])
-    problems += local_problems
     catalog = None
     catalog_source = str(home / 'models_cache.json')
     try:
@@ -81,7 +80,7 @@ def resolve(project=None, codex_home=None, explicit_model=None, explicit_effort=
         problems.append('Local Codex model catalog is unreadable or malformed; validate availability with the current native tool.')
     results = []
     for role in ROLES:
-        entry = local.get(role, personal.get(role))
+        entry = personal.get(role)
         source = entry['source'] if entry else None
         model = entry['model'] if entry else None
         effort = entry['effort'] if entry else None
@@ -122,8 +121,14 @@ def resolve(project=None, codex_home=None, explicit_model=None, explicit_effort=
                         'taskOverrides': overrides,
                         'subagentOverrides': {('reasoning_effort' if k == 'thinking' else k): v for k, v in overrides.items()},
                         'fallback': 'inherit parent settings' if role == 'reviewer' else 'native new-task default (not guaranteed dispatcher inheritance)'})
+    model_options = [] if catalog is None else [
+        {'value': slug, 'label': entry.get('display_name') or slug,
+         'efforts': [level['effort'] for level in entry['supported_reasoning_levels']]}
+        for slug, entry in catalog.items() if entry.get('visibility') != 'hide'
+    ]
     return {'roles': results, 'problems': problems, 'catalogSource': catalog_source if catalog is not None else None,
-            'precedence': 'explicit user model (and its explicit effort) > project role > personal role > native defaults; explicit effort alone overrides role effort',
+            'modelOptions': model_options,
+            'precedence': 'explicit user model (and its explicit effort) > personal role > native defaults; explicit effort alone overrides role effort',
             'scope': 'Model and effort only; agent instructions, tools, permissions, and other TOML keys are not applied by this adapter.'}
 
 
@@ -148,21 +153,137 @@ def setup(role, model, effort, codex_home=None):
     return {'created': True, 'role': role, 'source': str(target), 'model': model, 'effort': effort}
 
 
+def multiline_state(line, state=None):
+    """Track TOML multiline strings without interpreting their contents as keys."""
+    index = 0
+    while index < len(line):
+        if state:
+            closing = line.find(state, index)
+            while closing >= 0 and state == '"""':
+                escapes = 0
+                cursor = closing - 1
+                while cursor >= 0 and line[cursor] == '\\':
+                    escapes += 1
+                    cursor -= 1
+                if escapes % 2 == 0:
+                    break
+                closing = line.find(state, closing + 3)
+            if closing < 0:
+                return state
+            state = None
+            index = closing + 3
+            continue
+        if line[index] == '#':
+            return None
+        if line.startswith('"""', index) or line.startswith("'''", index):
+            state = line[index:index + 3]
+            index += 3
+            continue
+        if line[index] in ('"', "'"):
+            quote = line[index]
+            index += 1
+            while index < len(line):
+                if line[index] == quote and (quote == "'" or index == 0 or line[index - 1] != '\\'):
+                    index += 1
+                    break
+                if quote == '"' and line[index] == '\\':
+                    index += 2
+                else:
+                    index += 1
+            continue
+        index += 1
+    return state
+
+
+def replace_top_level_preferences(content, model, effort):
+    replacements = {
+        'model': json.dumps(model),
+        'model_reasoning_effort': json.dumps(effort),
+    }
+    assignment = re.compile(
+        r'^(?P<prefix>\s*(?P<key>model|model_reasoning_effort|["\']model["\']|["\']model_reasoning_effort["\'])\s*=\s*).*$'
+    )
+    lines = content.splitlines(keepends=True)
+    state = None
+    boundary = len(lines)
+    found = set()
+    for index, line in enumerate(lines):
+        if state is None and re.match(r'^\s*\[', line):
+            boundary = index
+            break
+        if state is None:
+            body = line.rstrip('\r\n')
+            ending = line[len(body):]
+            match = assignment.match(body)
+            if match:
+                key = match.group('key').strip('"\'')
+                lines[index] = f"{match.group('prefix')}{replacements[key]}{ending}"
+                found.add(key)
+        state = multiline_state(line, state)
+    missing = [f'{key} = {value}\n' for key, value in replacements.items() if key not in found]
+    if missing:
+        prefix = '' if boundary == 0 or lines[boundary - 1].endswith(('\n', '\r')) else '\n'
+        lines[boundary:boundary] = [prefix + ''.join(missing)]
+    candidate = ''.join(lines)
+    expected = tomllib.loads(content)
+    expected['model'] = model
+    expected['model_reasoning_effort'] = effort
+    if tomllib.loads(candidate) != expected:
+        raise ValueError('agent TOML could not be updated without changing unrelated settings')
+    return candidate
+
+
+def update(role, model, effort, codex_home=None):
+    home = Path(codex_home or os.environ.get('CODEX_HOME') or Path.home() / '.codex').expanduser().resolve()
+    resolved = resolve(codex_home=str(home))
+    options = {entry['value']: entry for entry in resolved['modelOptions']}
+    if model not in options or effort not in options[model]['efforts']:
+        raise ValueError('model or reasoning effort is unavailable')
+    existing, layer_problems = read_layer(home / 'agents')
+    role_entry = existing.get(role)
+    if layer_problems or (role_entry and role_entry['problems']):
+        raise ValueError('existing role configuration must be fixed before editing')
+    if role_entry is None:
+        return setup(role, model, effort, str(home))
+    target = Path(role_entry['source'])
+    agents = (home / 'agents').resolve()
+    if target.is_symlink() or target.resolve().parent != agents:
+        raise ValueError('role source is outside the personal agent directory')
+    content = replace_top_level_preferences(target.read_text(), model, effort)
+    temporary = target.with_name(f'.{target.name}.{os.getpid()}.tmp')
+    try:
+        temporary.write_text(content)
+        os.chmod(temporary, target.stat().st_mode & 0o777)
+        os.replace(temporary, target)
+    finally:
+        try:
+            temporary.unlink()
+        except FileNotFoundError:
+            pass
+    return {'updated': True, 'role': role, 'source': str(target), 'model': model, 'effort': effort}
+
+
 def main():
     parser = argparse.ArgumentParser(description=__doc__)
-    parser.add_argument('--project')
     parser.add_argument('--codex-home')
     parser.add_argument('--role', choices=ROLES)
     parser.add_argument('--model')
     parser.add_argument('--effort')
     parser.add_argument('--setup', action='store_true')
+    parser.add_argument('--update', action='store_true')
     args = parser.parse_args()
+    if args.setup and args.update:
+        parser.error('--setup and --update are mutually exclusive')
     if args.setup:
         if not (args.role and args.model and args.effort):
             parser.error('--setup requires --role, --model, and --effort')
         result = setup(args.role, args.model, args.effort, args.codex_home)
+    elif args.update:
+        if not (args.role and args.model and args.effort):
+            parser.error('--update requires --role, --model, and --effort')
+        result = update(args.role, args.model, args.effort, args.codex_home)
     else:
-        result = resolve(args.project, args.codex_home, args.model, args.effort)
+        result = resolve(args.codex_home, args.model, args.effort)
         if args.role:
             result['roles'] = [r for r in result['roles'] if r['role'] == args.role]
     print(json.dumps(result, indent=2))

package/skills/taskchef-delegate/SKILL.md

@@ -50,7 +50,7 @@ stop and report that the TaskChef plugin must be reloaded or installed.
    `githubRepos`; use `path` only as checkout identity. Require exactly one
    match and an exact native-project path. Ask instead of guessing.
    Select `planner` for a requested planning assignment and `implementer` for
-   coding work. Use the matched project's `projectModelRoles` from preparation;
+   coding work. Use the personal `modelRoles` from preparation;
    resolve explicit user choices and follow [model roles](references/model-roles.md).
    Small coding changes need no separate planning task. For a planning/coding
    split, the saved plan is the handoff to a separately requested implementation

package/skills/taskchef-delegate/references/model-roles.md

@@ -1,9 +1,8 @@
 # Dispatch model roles
 
-Preparation includes personal and per-project model previews. Use the exact
-matched project's preview. Role preferences use native Codex agent TOML under
-`$CODEX_HOME/agents/` (default `~/.codex/agents/`) and that project's
-`.codex/agents/`; they are optional. The resolver requires Python 3.11+.
+Preparation includes personal model previews. Role preferences use native Codex
+agent TOML under `$CODEX_HOME/agents/` (default `~/.codex/agents/`); they are
+optional. The resolver requires Python 3.11+.
 
 Select `planner` for a planning assignment or `implementer` for coding. Pass
 its `taskOverrides` as native `model` and `thinking` arguments only after checking
@@ -11,16 +10,15 @@ those values against the current create-task tool's supported model/effort
 choices. A missing role means omit both arguments and use the native new-task
 default. This is not guaranteed to inherit the dispatcher's model.
 
-Explicit user model choices take precedence over the project role, personal
-role, and native defaults. An explicit model without explicit effort omits effort and uses the native
+Explicit user model choices take precedence over the personal role and native
+defaults. An explicit model without explicit effort omits effort and uses the native
 interface's omission behavior; do not mix in a different role's effort or claim
 a specific effective effort without evidence. Explicit effort
-alone replaces the resolved role effort. Project roles replace personal roles
-as a unit. To resolve explicit choices, or recheck a preview after configuration
+alone replaces the resolved role effort. To resolve explicit choices, or recheck a preview after configuration
 changes, run:
 
 ```sh
-python3 <plugin-root>/scripts/roles/resolve_roles.py --project <project-path> --role implementer --model <user-model> --effort <user-effort>
+python3 <plugin-root>/scripts/roles/resolve_roles.py --role implementer --model <user-model> --effort <user-effort>
 ```
 
 Omit flags the user did not specify. Resolve the plugin root from this skill's
@@ -47,3 +45,8 @@ implements the function, runs the example, and uses fresh reviewer subagents.
 The dispatcher returns after each creation; it does not wait for or launch
 subsequent phases automatically. A small addition change can instead go
 straight to the implementer.
+
+A single assignment that asks to plan and then execute is an implementation
+assignment. Use the implementer model for that whole task; do not switch models
+mid-turn. To apply both configured roles, dispatch a planner task first, wait
+for its saved plan, then dispatch a separate implementer task using that plan.