taskchef 8.2.2 → 8.3.1

package/docs/spec.md

@@ -59,15 +59,10 @@ is dated research, not contract.
 
 ## Workspace contract
 
-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 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. Dashboard process identity and Codex-session leases
+MUST remain in memory and MUST NOT create owner, secret, or handoff files.
 
 `taskchef.json` MUST have schema version 2, the following required fields, and
 an optional exact `dashboard` object:
@@ -259,7 +254,8 @@ the final link, preserving the delegate skill's immediate-return contract.
    NOT place a blank line between the invocation and marker or inline the
    executor protocol into a new instruction.
 4. It MUST call `record_task` with `threadId: null` before native creation.
-5. It MUST create exactly one native Codex executor and return immediately.
+5. It MUST create exactly one native Codex executor using the resolved
+   Orchestrator preference when configured, then return immediately.
 6. The executor MUST read its own `CODEX_THREAD_ID` and call `link_task`
    before substantive work. It MUST NOT use parent/session identity or guess.
 7. After initial linking, the executor MUST establish a `turnRef`. It MUST use
@@ -274,6 +270,17 @@ the final link, preserving the delegate skill's immediate-return contract.
    TaskChef MUST atomically close it as `interrupted` before appending the new
    working turn; the executor MUST NOT report semantic `failed` for recovery.
 
+For repository work, the visible executor MUST route an explicit combined
+investigate-or-plan-and-implement request through a fresh Planner, then a fresh
+Implementer, then a fresh Reviewer. A direct implementation request, or a later
+request to implement prior investigation or planning, MUST skip the Planner and
+use a fresh Implementer followed by a fresh Reviewer in the same visible task.
+It MUST resolve the applicable role preference immediately before creating a
+child when agent TOML exists; absent agent configuration inherits the parent's
+model settings without requiring Python. It MUST keep at most one writing agent
+active and verify child results. TaskChef persists only the visible executor's
+lifecycle and MUST NOT store or infer child phases, identities, or usage.
+
 Normal executor completion MUST stop after the terminal callback and return
 normally. It MUST NOT archive, hand off, close, navigate away from, or otherwise
 terminate the Codex task merely because work completed. Archive is authorized
@@ -331,11 +338,8 @@ 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 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.
+**Caller:** dispatcher. **Mutation:** starts or reuses the
+Codex-session-scoped loopback dashboard.
 
 **Input:** empty object.
 
@@ -344,7 +348,7 @@ startup success.
 ```text
 { dashboard: {
   action: "started" | "reused",
-  launcher: "session",
+  launcher: "session" | "standalone" | "mcp",
   url: "http://127.0.0.1:3210/",
   workspace: string,
   taskchefVersion: string,
@@ -360,84 +364,65 @@ and concurrent calls are idempotent. The stable default MUST bind only to
 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.
+dashboard-server version, canonical workspace, and recognized launcher identity.
+A `session` listener MUST register the MCP's original Codex parent PID in its
+in-memory lease. Every launcher MUST complete another exact health probe before
+ensure reports `reused`, and the response MUST report the observed launcher.
 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
+readiness 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
+The dashboard MUST track only same-version 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
+MUST gracefully close its HTTP listener and exit. A new 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.
+When exact structured health identifies an older TaskChef dashboard for the
+same canonical workspace, the new MCP MUST request simple graceful shutdown,
+wait a bounded time for port release, and start its installed `session` version
+within the same ensure operation. It MUST NOT transfer in-memory PID leases
+across versions. The replacement initially knows only the activating session;
+a later ensure MAY register another live session or restart the dashboard after
+the activating lease expires.
+
+A recognized newer TaskChef listener MUST NOT be downgraded. Concurrent
+activation and replacement MUST converge through health probing and exclusive
+port binding. Unknown, malformed, different-workspace, or unrelated occupants
+MUST receive no control request or process signal and MUST remain untouched.
+TaskChef MUST NOT discover or kill port owners.
+
+TaskChef's dashboard uses a trusted, single-user localhost threat model. Exact
+bounded health identity is sufficient service recognition and MUST NOT be
+described as cryptographic authentication. The dashboard MUST NOT create or use
+an owner secret, HMAC challenge, durable ownership record, handoff record,
+prepare/commit protocol, recovery lease, or cross-version lease transfer.
+
+The session-registration and shutdown controls MUST remain loopback-only and
+MUST require the exact listener Host and Origin, JSON content type, a non-simple
+TaskChef control header, and an exact bounded request body containing the exact
+structured health identity observed by the caller. The receiver MUST compare
+that expected identity with its own identity before registering a session or
+accepting shutdown. It MUST refuse a mismatch, and the manager MUST probe again
+before applying lifecycle rules to the current occupant. These request-shape
+checks protect against ordinary cross-site browser requests; they MUST NOT be
+described as authentication. Future LAN access is outside this contract and
+requires a separate opt-in design with password-backed user authentication and
+suitable transport protection.
+
+A listener using the former HMAC control protocol will refuse the new simple
+shutdown request. It MUST be reported as a recognized older TaskChef conflict
+and left running. Crossing that one-time compatibility boundary requires the
+verified legacy listener to stop through its existing lifecycle before ensure
+is retried; TaskChef MUST NOT add a process-kill fallback.
 
 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.
+sent only after listener bind, initialization, and initial in-memory lease
+creation. 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.
 
 MCP EOF, explicit close, protocol close, SIGINT, SIGTERM, transport-start
 failure, and MCP-parent loss MUST still bound MCP shutdown. They MUST close the
@@ -756,15 +741,16 @@ 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
-verified legacy listener MUST be reported distinctly from an unknown port
-conflict but MUST remain untouched; one final manual cleanup MAY be required
-when upgrading from such a release. Once both sides implement the same control
-protocol, compatible prior-version handoff is automatic.
+Releases using the former HMAC dashboard control protocol are legacy listeners.
+A verified legacy listener MUST be reported distinctly from an unknown port
+conflict and MUST remain running when it refuses simple graceful shutdown. One
+final stop through that listener's existing lifecycle is required when crossing
+this boundary. Releases implementing simple localhost control replace older
+recognized versions automatically.
 
 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`, `session` launcher, canonical workspace,
+version, dashboard protocol `serverVersion`, reported 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

@@ -24,8 +24,8 @@ start, upgrade, shutdown, and security rationale.
 | `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. |
-| `src/dashboard-session-process.js` | Independent loopback server, private ownership publication, signals, and Codex-session lease. |
+| `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. |
@@ -46,31 +46,31 @@ sequenceDiagram
   participant D as Dispatcher
   participant M as TaskChef MCP
   participant H as Loopback health
-  participant S as Dashboard session process
+  participant S as Dashboard 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 session launcher
+  alt Exact service, versions, canonical workspace, and recognized launcher
     H-->>M: Bounded compatible identity
-    M->>S: Authenticate owner and register Codex parent PID
-    M-->>D: reused, URL, workspace, versions
+    M->>S: Register Codex parent PID when launcher is session
+    M->>H: Verify exact health again
+    M-->>D: reused, URL, workspace, versions, actual launcher
   else No listener
     H--xM: Connection refused
     M->>S: Launch session process on 127.0.0.1:3210
-    S-->>M: Private owner metadata and bounded identity
+    S-->>M: Ready after bind, initialization, and initial lease
     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
+  else Recognized older TaskChef listener for this workspace
+    M->>S: Simple guarded graceful shutdown request
+    S-->>M: Port released within bounded wait
     M->>S: Launch installed session version
     M-->>D: started, URL, workspace, versions
-  else Standalone, unknown, stale, or different workspace
+  else Newer, unknown, malformed, or different workspace
     H-->>M: Missing or incompatible identity
     M-->>D: Actionable conflict, listener untouched
   end
-  Note over D: Continue even when ensure failed
   D-->>D: Answer, report, or dispatch
   Note over D: Created-thread directive, when any, precedes final dashboard link
 ```
@@ -78,32 +78,39 @@ sequenceDiagram
 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.
+`taskchef dashboard` listener identifies itself as `standalone`. An
+exact-current, healthy same-workspace listener with a recognized `standalone`,
+`mcp`, or `session` launcher may be reused; ensure reports its actual launcher,
+and only `session` listeners register Codex PID leases. No TaskChef path
+terminates an incompatible listener or installs OS persistence.
 
 Autostart and explicit ensures share the same manager promise, while
-cross-process port races converge through authenticated reuse. An
+cross-process port races converge through exact health recognition and port binding. 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.
 
 ## Release-install verification
 
-The practical release handoff ends in this order:
+The practical release-install sequence 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`, `session`
+4. Verify the expected TaskChef version, protocol `serverVersion`, reported
    launcher, canonical workspace, and canonical URL returned by the dashboard identity.
 
 Replacing plugin files alone cannot execute autostart because old code remains
 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.
+Codex. Activation of the installed MCP asks a recognized older same-workspace
+TaskChef listener to shut down gracefully. If the listener accepts, TaskChef
+waits boundedly for its port and starts the installed session version. If the
+listener lacks the compatible callback or refuses the request, it remains
+running and ensure reports a conflict. An exact-compatible same-workspace
+dashboard with any recognized launcher may be reused; a newer or unknown
+listener is never terminated or replaced. A release using the former HMAC
+control protocol needs one verified stop through its existing lifecycle before
+the simple control protocol can take over.
 
 ## Normal delegation and self-linking
 
@@ -149,6 +156,16 @@ Record-before-create makes native creation failure observable. Executor
 self-linking removes dispatcher-side polling, task search, title matching, and
 parent/child identity inference.
 
+The created executor is the stable visible owner. For repository work, an
+explicit combined investigate-or-plan-and-implement request runs a fresh
+Planner, Implementer, and Reviewer in that order. Direct implementation and a
+later request to implement prior investigation skip the Planner and run a fresh
+Implementer and Reviewer in the same visible task. Each role is resolved
+immediately before use when agent TOML exists; absent configuration inherits the
+parent's settings without requiring Python. Only one writer may be active.
+TaskChef records only the executor's ordinary request/result timeline; it does
+not track child phases or identities.
+
 The generated task begins with the complete assignment, adds the local reporting
 authorization paragraph separated by a blank line, leaves one blank line,
 then places one explicit `$taskchef-executor` invocation immediately before its

package/package.json

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

package/scripts/roles/resolve_roles.py

@@ -12,7 +12,7 @@ import re
 import sys
 import tomllib
 
-ROLES = ('planner', 'implementer', 'reviewer')
+ROLES = ('orchestrator', 'planner', 'implementer', 'reviewer')
 EFFORTS = ('none', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max', 'ultra')
 
 
@@ -120,7 +120,7 @@ def resolve(codex_home=None, explicit_model=None, explicit_effort=None):
                         'availability': availability, 'problems': errors,
                         '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)'})
+                        'fallback': 'native new-task default' if role == 'orchestrator' else 'inherit parent settings'})
     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']]}

package/skills/taskchef-delegate/SKILL.md

@@ -5,8 +5,8 @@ description: "Dispatch work received in the canonical TaskChef workspace into Co
 
 # TaskChef Delegate
 
-Create real Codex tasks through the canonical per-user TaskChef data workspace
-and return immediately.
+Create stable visible TaskChef parent tasks through the canonical per-user
+TaskChef data workspace and return immediately.
 
 ## Invocation boundary
 
@@ -33,7 +33,8 @@ stop and report that the TaskChef plugin must be reloaded or installed.
 - 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.
+- Use real Codex tasks for visible delegated work. The dispatcher never uses
+  collaboration or subagent tools; the created executor may use them internally.
 - Never use hooks, schedules, daemons, background monitors, recent-task
   searches, transcripts, hidden reasoning, or polling for identity.
 - Never wait for delegated work after native creation.
@@ -50,13 +51,11 @@ stop and report that the TaskChef plugin must be reloaded or installed.
 3. Route against configured project `name`, `description`, and canonical
    `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 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
-   assignment; do not switch models during a turn or coordinate phases automatically.
-   Resolve configuration problems before recording the task.
+   Select the `orchestrator` preference from preparation for every visible
+   parent. Resolve explicit choices and follow
+   [model roles](references/model-roles.md). Missing configuration means omit
+   model overrides; surface invalid or unavailable configuration before
+   recording the task.
 4. Build each executor instruction in this exact shape:
 
    - Begin with the actual assignment on the first line and keep its complete
@@ -76,7 +75,8 @@ stop and report that the TaskChef plugin must be reloaded or installed.
 5. Before creating each executor, call `record_task` exactly once with `id`,
    `project`, `title`, the exact marked `instruction`, and `threadId: null`.
 6. Create one real Codex task using the exact configured project, an appropriate
-   native environment, the marked instruction, and a short title.
+   native environment, the marked instruction, a short title, and the resolved
+   orchestrator model and effort overrides when present.
 7. Return immediately. Preserve a returned provisional client ID only for the
    created-thread directive. Do not call `link_task` from the dispatcher even
    when creation returns a durable ID; the child must self-link.

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

@@ -1,52 +1,29 @@
-# Dispatch model roles
+# Model roles
 
-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+.
+TaskChef reads optional personal role preferences from native Codex agent TOML
+in `$CODEX_HOME/agents/` (default `~/.codex/agents/`). Only model and reasoning
+effort are adapted; TaskChef does not load the files' instructions, tools, or
+permissions.
 
-Select `planner` for a planning assignment or `implementer` for coding. Pass
-its `taskOverrides` as native `model` and `thinking` arguments only after checking
-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.
+For a new visible task, select `orchestrator` from the `modelRoles` returned by
+`prepare_dispatch`. Pass its `taskOverrides` as the native task's `model` and
+`thinking` only after checking that the current creation interface supports
+them. Missing configuration means omit both overrides. Invalid or unavailable
+configuration must be reported rather than silently ignored.
 
-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. To resolve explicit choices, or recheck a preview after configuration
-changes, run:
+Explicit user choices take precedence. An explicit model without an explicit
+effort omits effort; do not combine it with a configured effort from another
+model. To resolve an explicit choice, run the packaged resolver before creating
+the task:
 
 ```sh
-python3 <plugin-root>/scripts/roles/resolve_roles.py --role implementer --model <user-model> --effort <user-effort>
+python3 <plugin-root>/scripts/roles/resolve_roles.py --role orchestrator --model <model> [--effort <effort>]
 ```
 
-Omit flags the user did not specify. Resolve the plugin root from this skill's
-real path, two parents above the skill directory. Do not substitute dispatcher
-paths for the target project or infer model names from skill prose.
+Resolve `<plugin-root>` from this skill's installed path. Omit flags the user
+did not specify. The local model catalog is advisory; the current native tool
+is authoritative about supported model and effort values.
 
-Report malformed profiles, duplicate names, unavailable models/efforts, and
-resolver failures. Do not quietly fall back and claim preferences were honored.
-The local model catalog is advisory: explain if a current native tool disproves
-its stale warning. Otherwise resolve the problem or obtain a valid explicit
-choice before task creation. Native creation failures retain normal TaskChef
-failure reporting. A preparation without role fields supports historical
-installations: check role files before deciding that no preferences exist.
-
-Only model and effort are adapted. The native agent file's instructions, tools,
-permissions, and other settings are not applied by create-task arguments. A
-role name in a title is not a native role selector. If the native interface adds
-a role selector, use it only with verified effective settings.
-
-For a plan-to-implementation handoff, a planner assignment can save
-`plans/addition.md` describing a pure addition function and the acceptance
-example `2 + 3 = 5`. A later implementer assignment reads that exact plan,
-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.
+The visible executor resolves Planner, Implementer, and Reviewer preferences
+itself when it starts those subagents. The dispatcher does not create or wait
+for those children.

package/skills/taskchef-executor/SKILL.md

@@ -60,6 +60,40 @@ UUID is the lifecycle identity. Retry a possibly lost working callback with the
 same `turnRef`; never generate a replacement for the same prompt or bypass a
 link-pending state.
 
+## Coordinate the assignment
+
+Keep this visible task as the stable owner of the assignment and its follow-ups.
+For repository work, use these tight routes:
+
+- An explicit investigate-or-plan-and-implement request starts a fresh Planner,
+  then a fresh Implementer, then a fresh Reviewer.
+- A direct implementation request starts a fresh Implementer, then a fresh
+  Reviewer; skip the Planner.
+- A later request to implement prior investigation or planning stays in this
+  visible task and starts a fresh Implementer, then a fresh Reviewer.
+
+Make the Reviewer read-only and cover the complete change. Use the installed
+`$branch-review-subagent-loop` when available or required by repository policy.
+TaskChef tracks only this parent task's lifecycle; do not report child phases or
+identities to TaskChef.
+
+Immediately before starting a child, check the Codex agents directory. If it
+contains no TOML files, inherit the parent's model settings without invoking
+Python. Otherwise resolve that role with the packaged resolver and use its
+`subagentOverrides` when valid:
+
+```sh
+python3 <plugin-root>/scripts/roles/resolve_roles.py --role <planner|implementer|reviewer>
+```
+
+Resolve `<plugin-root>` from this skill's installed path. Missing configuration
+means inherit the parent's model settings. Surface invalid or unavailable
+configuration instead of silently ignoring it. Give each child only the goal,
+scope, repository or worktree, relevant instructions, and validation expected;
+ask it to return changed files, tests, and blockers. Keep at most one writing
+agent active, verify its result, and use a fresh writer before another review
+when review finds a valid issue.
+
 ## Finish every execution turn
 
 Before ending, call `report_state` with the same `turnRef` and `turnId` values