taskchef 6.0.0 → 6.1.0

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "taskchef",
-  "version": "6.0.0",
+  "version": "6.1.0",
   "description": "Dispatch work from a data-only workspace to visible Codex project tasks.",
   "author": {
     "name": "Favo Yang",
@@ -33,6 +33,9 @@
       "$taskchef-delegate Dispatch this request to the right project.",
       "$taskchef-report Report on work in the TaskChef task history."
     ],
-    "brandColor": "#D97706"
+    "brandColor": "#D97706",
+    "composerIcon": "./assets/taskchef.svg",
+    "logo": "./assets/taskchef.svg",
+    "logoDark": "./assets/taskchef-dark.svg"
   }
 }

package/assets/taskchef-dark.svg

@@ -0,0 +1,9 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="48" height="48" viewBox="0 0 48 48" fill="none">
+  <rect x="2" y="2" width="44" height="44" rx="11" fill="#F59E0B"/>
+  <path d="M15 37V27.5C11.9 26.3 10 23.6 10 20.5C10 16.4 13.4 13 17.5 13C19 10 21.2 8.5 24 8.5C26.8 8.5 29 10 30.5 13C34.6 13 38 16.4 38 20.5C38 23.6 36.1 26.3 33 27.5V37H15Z" fill="#FFFBEB"/>
+  <path d="M19 24L22 27L28.5 20.5" stroke="#78350F" stroke-width="3" stroke-linecap="round" stroke-linejoin="round"/>
+  <path d="M24 28V32M24 32H19M24 32H29" stroke="#78350F" stroke-width="3" stroke-linecap="round" stroke-linejoin="round"/>
+  <circle cx="19" cy="32" r="2" fill="#78350F"/>
+  <circle cx="29" cy="32" r="2" fill="#78350F"/>
+  <path d="M15 37H33" stroke="#78350F" stroke-width="3" stroke-linecap="round"/>
+</svg>

package/assets/taskchef.svg

@@ -0,0 +1,9 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="48" height="48" viewBox="0 0 48 48" fill="none">
+  <rect x="2" y="2" width="44" height="44" rx="11" fill="#D97706"/>
+  <path d="M15 37V27.5C11.9 26.3 10 23.6 10 20.5C10 16.4 13.4 13 17.5 13C19 10 21.2 8.5 24 8.5C26.8 8.5 29 10 30.5 13C34.6 13 38 16.4 38 20.5C38 23.6 36.1 26.3 33 27.5V37H15Z" fill="#FFF7ED"/>
+  <path d="M19 24L22 27L28.5 20.5" stroke="#7C2D12" stroke-width="3" stroke-linecap="round" stroke-linejoin="round"/>
+  <path d="M24 28V32M24 32H19M24 32H29" stroke="#7C2D12" stroke-width="3" stroke-linecap="round" stroke-linejoin="round"/>
+  <circle cx="19" cy="32" r="2" fill="#7C2D12"/>
+  <circle cx="29" cy="32" r="2" fill="#7C2D12"/>
+  <path d="M15 37H33" stroke="#7C2D12" stroke-width="3" stroke-linecap="round"/>
+</svg>

package/docs/delegation-design.md

@@ -4,63 +4,213 @@ TaskChef stores a durable local task history while Codex owns execution. The
 dispatcher records intent, the executor registers its own identity, and only
 the executor reports semantic outcomes.
 
-## Lifecycle
-
-1. `prepare_dispatch` returns a fresh task UUID, exact marker, timestamp, and
-   configured projects.
-2. The dispatcher calls `record_task` with the complete marked instruction and
-   `threadId: null` before native creation.
-3. The dispatcher creates the Codex task and returns immediately. A durable or
-   provisional creation result is never treated as authority to link the
-   record.
-4. As its first TaskChef action, the executor reads its own durable native
-   thread ID and calls `link_task(taskId, threadId)`.
-5. Before ending a turn with a semantic outcome, the executor reads that exact
-   thread, takes the current turn ID, and calls `report_result`.
-
-There is no task listing, candidate read, marker search, wait, retry loop,
-transcript read, or hook in the dispatch path. The existing filesystem watcher
-notices the atomic `link_task` rewrite and immediately refreshes the dashboard.
-
-## Identity guarantees
+## Key terminology
+
+The central identity rule is: **the executor child links itself**. The
+dispatcher may create the child, but it never treats its own thread, a parent
+thread, or a provisional creation handle as the executor's durable identity.
+
+| Term | Meaning |
+| --- | --- |
+| TaskChef task ID | Stable UUID allocated by `prepare_dispatch`; it identifies the durable TaskChef record. |
+| Exact marker | First-line correlation marker copied into the executor instruction; it binds that instruction to the pre-recorded TaskChef task. |
+| Source or parent thread ID | The dispatcher/delegator context; never valid as the executor identity. |
+| Executor thread ID | The child's own durable `CODEX_THREAD_ID`; the executor supplies it to `link_task`. |
+| Provisional client thread ID | Temporary native creation handle; useful for creation UI, but never identity authority. |
+| Turn ID | Current native turn UUIDv7 read from the exact executor thread; it proves result freshness. |
+| `tasks.jsonl` | Durable append/rewrite history whose latest snapshot is shown by TaskChef. |
+
+The diagrams below are intentionally small. Calls into **TaskChef MCP** name
+the MCP function being invoked. Notes beside `tasks.jsonl` name the fields that
+step populates or replaces.
+
+## Workflow 1: Prepare and record intent
+
+The dispatcher first asks TaskChef to allocate routing and correlation values.
+`prepare_dispatch` does not write a record. The dispatcher then embeds the exact
+marker in the instruction and calls `record_task` **before** native creation, so
+an executor can self-link as soon as its first turn starts.
+
+```mermaid
+sequenceDiagram
+  autonumber
+  actor U as User
+  participant D as Dispatcher
+  participant M as TaskChef MCP
+  participant W as tasks.jsonl
+
+  U->>D: Delegation request
+  D->>M: prepare_dispatch()
+  M-->>D: taskId, marker, preparedAt, projects
+  Note over D,M: Allocate identity and routing only#59; no record written
+  D->>M: record_task(id, project, title, marked instruction, threadId=null)
+  M->>W: Append schema 4 snapshot
+  Note right of W: id, project, title, instruction, createdAt<br>threadId=null, status=working, summary=null, turnId=null<br>updatedAt=createdAt, updatedBy=dispatcher
+  M-->>D: Recorded task snapshot
+```
+
+## Workflow 2: Create and self-link the executor
+
+After recording, the dispatcher creates the native Codex task and returns
+immediately. A durable or provisional ID returned to the dispatcher is not
+trusted as executor identity. The child reads its own `CODEX_THREAD_ID` and
+uses `link_task` as its first TaskChef action.
 
 The exact marker correlates the child instruction with the pre-created record.
-The executor must use its native current thread ID, never the delegation
-`sourceThreadId`, parent task, inherited session identity, title, or provisional
-client ID.
-
-`link_task` runs under the workspace lock. It permits one atomic
-`null`-to-durable transition, rejects malformed or provisional IDs, rejects a
-thread already owned by another TaskChef task, rejects a different retry, and
-returns the existing snapshot for an identical retry.
-
-Custom MCP does not currently authenticate the calling Codex task. The thread
-ID is therefore a cooperative assertion inside TaskChef's local single-user
-trust boundary. The design prevents accidental parent/child confusion but does
-not claim resistance to a deliberately forged local MCP call.
-
-## Failure and retry behavior
-
-If native creation fails after recording, the dispatcher writes one terminal
-`failed` result with null thread and turn IDs and a bounded summary. If the
-executor is interrupted, cancelled, cannot see `link_task`, or gets a rejected
-link, the record remains `working` with `threadId: null`. That visible
-link-pending state is retryable on a later turn. TaskChef never guesses or
-recovers identity through the dashboard.
-
-## Result freshness
-
-Linked results require an exact thread-ID match and a non-null current turn ID.
-For self-linked schema 4 journeys, the native time-ordered Codex UUID must be
-strictly newer for every changed result; exact same-turn retries remain safe.
-Identical `report_result` retries are safe. A follow-up or resumed executor must
-read its exact task again and report the new turn ID; reusing the initial turn
-cannot establish freshness.
-
-The latest snapshot fields are `status`, bounded `summary`, `turnId`,
-`updatedAt`, and `updatedBy`. Historical `updatedBy: hook` values remain
-readable, but new installations contain no hook and new writes use `dispatcher`
-or `mcp`.
+`link_task` atomically permits one `null`-to-durable transition, rejects a
+malformed or reused ID, and makes the dashboard deep link target the child—not
+the source, parent, or dispatcher thread.
+
+```mermaid
+sequenceDiagram
+  autonumber
+  actor U as User
+  participant D as Dispatcher
+  participant C as Codex native tasks
+  participant E as Executor child
+  participant M as TaskChef MCP
+  participant W as tasks.jsonl
+  participant V as Dashboard
+
+  D->>C: Create task with marked instruction
+  C-->>D: Durable threadId or provisional clientThreadId
+  Note over D,C: Creation result is not executor identity authority
+  D-->>U: Created-task directive#59; dispatcher returns immediately
+  C->>E: Start initial executor turn
+  E->>E: Read own CODEX_THREAD_ID
+  E->>M: link_task(taskId, child threadId)
+  M->>W: Atomic identity registration
+  Note right of W: Set threadId=child UUIDv7<br>Set updatedAt and updatedBy=mcp<br>Keep status=working, summary=null, turnId=null
+  M-->>E: Self-linked task snapshot
+  W-->>V: Filesystem watcher refresh
+  Note right of V: Deep link targets the exact executor child
+```
+
+## Workflow 3: Report the current turn
+
+Before ending with a semantic outcome, the executor reads its exact native
+thread and obtains that turn's current UUIDv7. It then calls `report_result`
+with its matching self-linked thread ID. The status is `completed`, `failed`,
+or `needs_input`; the summary is concise and bounded.
+
+Changed results must use a strictly newer turn ID. An identical same-turn retry
+is idempotent, but reusing an old turn ID for a changed result cannot establish
+freshness.
+
+```mermaid
+sequenceDiagram
+  autonumber
+  participant E as Executor child
+  participant C as Codex native tasks
+  participant M as TaskChef MCP
+  participant W as tasks.jsonl
+  participant V as Dashboard
+
+  E->>C: Exact read of this executor thread
+  C-->>E: Current turnId UUIDv7
+  E->>M: report_result(taskId, threadId, turnId, status, summary)
+  M->>W: Store semantic result
+  Note right of W: Replace status, summary, turnId<br>Set updatedAt and updatedBy=mcp
+  M-->>E: Updated task snapshot
+  W-->>V: Filesystem watcher refresh
+```
+
+## Workflow 4: Resume after `needs_input`
+
+`needs_input` is a semantic pause, not a native approval prompt. After the user
+responds or resumes the task, the executor reads the exact task again. The new
+turn ID, rather than the initial one, accompanies the updated result.
+
+```mermaid
+sequenceDiagram
+  autonumber
+  actor U as User
+  participant E as Executor child
+  participant C as Codex native tasks
+  participant M as TaskChef MCP
+  participant W as tasks.jsonl
+  participant V as Dashboard
+
+  E-->>U: Request decision or information
+  U->>E: Follow up or resume
+  E->>C: Exact native read after follow-up
+  C-->>E: Newer current turnId UUIDv7
+  E->>M: report_result(taskId, threadId, newer turnId, completed, summary)
+  M->>W: Replace latest semantic result
+  Note right of W: status=completed, new summary, newer turnId<br>updatedAt refreshed, updatedBy=mcp
+  M-->>E: Completed task snapshot
+  W-->>V: Filesystem watcher refresh
+```
+
+## Workflow 5: Creation and linking failures
+
+Because `record_task` happens first, native creation failure remains visible:
+the dispatcher reports one terminal failure while both identity fields stay
+null. The dispatcher makes exactly one native creation call and never retries
+it. TaskChef never guesses an executor identity from recent tasks, titles,
+transcripts, or dashboard activity.
+
+For linking, outcome depends on where interruption occurs. Before commit, an
+eligible record remains link-pending. If the atomic write commits but its reply
+is lost, the record is already linked and an identical retry returns that
+snapshot. Inspect rejections before retrying; identity conflicts and terminal
+records must not be blindly retried.
+
+```mermaid
+sequenceDiagram
+  autonumber
+  actor U as User
+  participant D as Dispatcher
+  participant C as Codex native tasks
+  participant E as Executor child
+  participant M as TaskChef MCP
+  participant W as tasks.jsonl
+
+  alt Native creation fails after record_task
+    D->>C: Create task with marked instruction
+    C--xD: Creation error
+    D->>M: report_result(taskId, null, null, failed, bounded summary)
+    M->>W: Store terminal creation failure
+    Note right of W: Keep threadId=null and turnId=null<br>Set status=failed, summary, updatedAt, updatedBy=mcp
+    M-->>D: Failed task snapshot
+    D-->>U: Creation failure with preserved TaskChef taskId
+  else Initial link stops before commit
+    E--xM: link_task(taskId, child threadId)
+    Note right of W: Remains threadId=null, status=working<br>Eligible link-pending record may retry later
+  else Link commits but response is lost
+    E->>M: link_task(taskId, child threadId)
+    M->>W: Commit child threadId
+    M--xE: Response lost
+    E->>M: Identical link_task retry
+    M-->>E: Return existing linked snapshot
+  end
+```
+
+## MCP calls and field transitions
+
+| Step | Caller | Operation | Key input | Task record effect |
+| --- | --- | --- | --- | --- |
+| 1 | Dispatcher | `prepare_dispatch` | No task identity supplied | Returns `taskId`, exact `marker`, `preparedAt`, and configured `projects`; does not write `tasks.jsonl`. |
+| 2 | Dispatcher | `record_task` | `id`, `project`, `title`, marked `instruction`, `threadId: null` | Appends schema 4 with `createdAt`; sets `status: working`, `summary: null`, `turnId: null`, `updatedAt: createdAt`, `updatedBy: dispatcher`. |
+| 3 | Dispatcher | Native Codex task creation—not MCP | Target project plus marked instruction | Does not change the TaskChef record. A returned durable or provisional ID is not identity authority. |
+| 4 | Executor | `link_task` | Marked `taskId` plus its own `CODEX_THREAD_ID` | Atomically changes `threadId` from `null` to the canonical child UUIDv7; refreshes `updatedAt` and sets `updatedBy: mcp`. |
+| 5 | Executor | `report_result` | Exact `taskId`, self-linked `threadId`, current `turnId`, semantic `status`, concise `summary` | Replaces the latest `status`, `summary`, and `turnId`; refreshes `updatedAt` and sets `updatedBy: mcp`. Changed follow-up results require a newer UUIDv7 `turnId`. |
+| Failure | Dispatcher | `report_result` after native creation error | `taskId`, `threadId: null`, `turnId: null`, `status: failed`, bounded `summary` | Preserves the pre-created record and null identity while storing a terminal creation failure. |
+
+## Design boundaries
+
+There is no task listing, candidate read, marker search, wait, polling loop,
+native creation retry, transcript read, or hook in the dispatch path. The
+filesystem watcher notices atomic TaskChef writes and refreshes only the
+dashboard; reports read current state on demand.
+
+Custom MCP does not authenticate the calling Codex task. The executor thread ID
+is therefore a cooperative assertion inside TaskChef's local single-user trust
+boundary. The design prevents accidental parent/child confusion but does not
+claim resistance to a deliberately forged local MCP call.
+
+Historical `updatedBy: hook` values remain readable, but new installations
+contain no hook and new writes use `dispatcher` or `mcp`.
 
 ## Legacy recovery
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "taskchef",
-  "version": "6.0.0",
+  "version": "6.1.0",
   "description": "A non-blocking interactive dispatcher for visible Codex tasks.",
   "license": "MIT",
   "author": "Favo Yang",
@@ -39,6 +39,7 @@
   },
   "devDependencies": {
     "conventional-changelog-conventionalcommits": "^10.3.0",
+    "mermaid": "^11.17.0",
     "yaml": "^2.9.0"
   },
   "scripts": {