taskchef 5.12.0 → 6.1.0

package/docs/delegation-design.md

@@ -1,178 +1,227 @@
 # Delegation and result design
 
-TaskChef is deliberately smaller than a workflow engine. It records one useful
-snapshot per delegated task, links the executor identity once, accepts semantic
-results from the executor, and performs cheap freshness checks when reporting.
+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.
 
-## Minimal workflow
+## 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
-    participant U as User
-    participant D as Delegate skill
-    participant M as TaskChef MCP
-    participant C as Codex executor
-    participant H as Initial hook
-    participant W as tasks.jsonl
-
-    U->>D: Delegate work
-    par Prepare routing
-        D->>M: prepare_dispatch
-    and
-        D->>C: List native projects
-    end
-    D->>M: record_task(threadId: null)
-    M->>W: Append working task under lock
-    D->>C: Create task with exact marker
-    alt Durable ID returned
-        D->>M: resolve_task
-    else Provisional ID returned
-        D->>C: Bounded recent-task checks
-        D->>C: Read candidates and verify exact marker
-        D->>M: resolve_task(verified child ID)
-        C->>H: Initial UserPromptSubmit
-        H->>W: Wait for verified link; record initial turn
-    end
-    D-->>U: Return immediately
-    C->>M: report_result(needs_input | completed | failed)
-    M->>W: Replace latest semantic snapshot under lock
+  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
 ```
 
-Recording happens before creation. This closes the only important race: when
-the initial hook runs, the exact TaskChef marker already has an entry to update.
-The dispatcher performs only the bounded 10/30-second identity checks. There is
-no scheduler, daemon, indefinite polling, or dispatcher wakeup.
-
-Every executor receives this ownership instruction unchanged:
-
-> This task owns the delegated assignment. Execute it in this task; do not re-dispatch it merely because it concerns TaskChef or a configured project. Explicit requests to delegate separate work remain valid.
-
-## Who writes what
-
-| Writer | Trigger and condition | Fields it owns |
-| --- | --- | --- |
-| Dispatcher via `record_task` | Before executor creation | New entry, `status: working`, null identity/result, server timestamps |
-| Dispatcher via `resolve_task` | Creation returns a durable ID, or bounded discovery verifies one exact-marker child | `threadId` only |
-| Initial `UserPromptSubmit` hook | Prompt starts with the exact TaskChef marker and the verified link exists | Initial `turnId`, `status: working`, `updatedAt`, `updatedBy: hook` |
-| Follow-up `UserPromptSubmit` hook | Session ID exactly matches a recorded executor | Nothing; reads the snapshot and injects the current `turnId` for the MCP callback |
-| Executor via `report_result` | Work has a semantic outcome | `status`, bounded `summary`, result `turnId`, `updatedAt`, `updatedBy: mcp` |
-| Reporter | On explicit report request | Nothing; inferred live state is never persisted |
-
-The hook does not write needs-input, completed, or failed. Its follow-up path is
-read-only and exists only so the executor can report the current turn. A native permission
-request is live Codex state; it is not a TaskChef semantic result. The executor
-uses `needs_input` only when it truly requires a user decision or information.
-
-## Task snapshot
-
-Schema version 3 retains the delegation fields and adds:
-
-- `status`: `working`, `needs_input`, `completed`, or `failed`
-- `summary`: null while working, otherwise a concise result capped at 2,000 characters
-- `turnId`: initial or latest reported turn; linked MCP results require it, and
-  only a pre-thread creation failure may report null
-- `updatedAt`: server-side timestamp
-- `updatedBy`: `dispatcher`, `hook`, or `mcp`
-
-Schema versions 1 and 2 remain readable and normalize to nullable result fields.
-There is no result-event file: each callback replaces the latest snapshot on the
-same JSONL line.
-Result instructions forbid secrets, transcripts, and raw command output; the
-server also caps the stored summary at 2,000 characters.
-
-## Locking and conflicts
-
-All configuration, identity, and result writes use the existing cross-process
-workspace lock. A writer acquires the lock, rereads and validates the complete
-JSONL file, changes one exact task, and publishes a complete replacement with
-an atomic rename. Concurrent writers therefore cannot create partial JSON,
-duplicate entries, or lose changes to different tasks. Sequential callbacks for
-the same task use last accepted write wins; normal executor turns are already
-sequential.
-
-SQLite is postponed because this file-level write volume is tiny and the
-existing lock provides the property users need. SQLite becomes worthwhile only
-if TaskChef later adds high-frequency event history or many continuous writers.
-
-## Result trust
-
-The MCP server does not receive an independently authenticated caller task ID
-from the model transport. It validates that the supplied task exists and that
-the supplied durable thread ID exactly matches the recorded thread. The turn ID
-is stored as evidence but remains model-supplied. A trusted plugin install,
-local-only MCP server, bounded summary, and exact task/thread match are the
-current trust boundary.
-
-This is sufficient for a lightweight personal dispatcher, but not a
-multi-tenant authorization boundary. Transport-authenticated caller identity is
-postponed until Codex exposes it.
-
-## Fresh reporting without reading every task
-
-A stored result is cached evidence, not permanent truth. Overview reports:
-
-1. Load `tasks.jsonl` once.
-2. Always consider working, needs-input, unresolved, and legacy entries.
-3. Consider completed or failed entries updated in the last seven days.
-4. Take one recent-thread metadata snapshot for all selected tasks. Include an
-   older terminal task in an overview when the snapshot shows it is active or
-   awaiting native approval.
-5. A null-thread/null-turn `failed` snapshot written by MCP is a fresh creation
-   failure and needs no live task lookup because no executor exists.
-6. Treat only `updatedBy: mcp` as a semantic cache. Dispatcher- and hook-written
-   `working` snapshots require a targeted live read; an inactive task with no
-   callback has an unknown outcome.
-7. In a broad overview, use an MCP result directly when identity is certain and
-   the task is inactive; do not fan out detailed reads over idle terminal tasks
-   solely because their timestamps are newer.
-8. Active or awaiting-approval metadata overrides the cached result directly.
-   For a focused task, title, or project report, read each selected inactive
-   task at most once when matched metadata is newer than the callback by any
-   amount. Batch targeted immediate reads, at most eight tasks per call, also
-   for a missing callback, uncertain or contradictory state, or an explicitly
-   fully-live request.
-9. If an anomaly triggers a detailed read, compare its latest structured turn
-   ID and native turn state with stored `turnId`. A newer turn without a
-   callback makes the cache stale. An interrupted or cancelled callback turn
-   cannot prove completion.
-
-An explicit task, title, or project report bypasses the seven-day overview
-filter. Old terminal tasks skipped from an overview are counted so the user
-knows history was intentionally omitted.
-
-The cheap operation is the single list/metadata snapshot, not one read per
-historical task. It is sufficient to expose active and native-approval state for
-many recent tasks at once. It does not prove completion; semantic outcomes come
-from MCP callbacks. Detailed thread reads are the exceptional fallback.
-Timestamps are a pragmatic anomaly filter; turn IDs and native turn state
-provide the stronger check whenever a targeted response is necessary.
-
-## Permission and follow-up example
-
-1. Delegation records one `working` entry with null identity.
-2. The dispatcher verifies and resolves the child thread; the initial hook then
-   records its initial turn without trusting the inherited session ID.
-3. The executor reaches a real product decision and calls `report_result` with
-   `needs_input` plus “Approve deployment to production.”
-4. The user opens that executor and approves. The same hook reads the matching
-   task and injects the new turn ID without changing the stored snapshot. Until
-   the final callback, a report sees newer/active live metadata and labels the
-   cached needs-input result stale.
-5. The executor finishes and calls `report_result` with `completed`, the new
-   turn ID, and a concise outcome. The same JSONL line now contains the completed
-   snapshot.
-
-If step 3 were merely Codex asking for filesystem or command approval, no MCP
-callback would be written. Reporting would show “awaiting native approval” from
-live task state.
-
-## Explicitly postponed
-
-- append-only result or transition events
-- lifecycle event types beyond `UserPromptSubmit`
-- fork tracking or result merging
-- SQLite
-- indefinite polling, reconciliation schedules, daemons, and dispatcher wakeups
-- durable report watermarks
-- transcript or assistant-prose classification
-- transport-authenticated caller thread/turn identity
+## 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.
+`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
+
+`taskchef task resolve` is retained only for unresolved schema 1-3 records.
+Operators must establish one exact marker match and one unique durable child
+ID. Schema 4 self-linking records reject manual resolution. History is read
+compatibly and is not eagerly rewritten.
+
+## Dashboard and reports
+
+The dashboard deep link uses only the stored self-linked child ID. File watcher
+events surface linking and results without user interaction. Reporting may
+compare current native metadata with cached semantic results, but it never
+writes inferred lifecycle state.

package/index.js

@@ -9,6 +9,7 @@ export {
   filterTasks,
   importProjects,
   initializeWorkspace,
+  linkTask,
   listProjects,
   prepareDispatch,
   readConfig,
@@ -17,7 +18,6 @@ export {
   recordTask,
   reportTaskResult,
   resolveTask,
-  startTaskFromHook,
   requireSafeId,
   removeProject,
   validateConfig,
@@ -31,20 +31,14 @@ export {
 
 export {
   EXECUTOR_OWNERSHIP_PARAGRAPH,
+  EXECUTOR_LINK_PARAGRAPH,
   EXECUTOR_RESULT_PARAGRAPH,
-  THREAD_RESOLUTION_CHECKPOINTS_MS,
-  THREAD_RESOLUTION_CLOCK_SKEW_MS,
-  THREAD_RESOLUTION_RECENT_LIMIT,
-  THREAD_RESOLUTION_TIMEOUT_MS,
   createAndRecordDelegation,
-  filterThreadCandidates,
-  hasExactTaskChefMarker,
   isProvisionalThreadId,
-  listThreadEntries,
+  normalizeCodexThreadId,
   normalizeDurableThreadId,
   parseTaskChefMarker,
   prepareDelegation,
-  structuredDelegatedInputs,
   taskChefMarker,
 } from "./src/delegation.js";
 
@@ -69,5 +63,3 @@ export {
 } from "./src/dashboard.js";
 
 export { createTaskChefMcpServer } from "./src/mcp.js";
-
-export { INITIAL_LINK_CHECKPOINTS_MS, handleInitialPromptHook } from "./src/hook.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "taskchef",
-  "version": "5.12.0",
+  "version": "6.1.0",
   "description": "A non-blocking interactive dispatcher for visible Codex tasks.",
   "license": "MIT",
   "author": "Favo Yang",
@@ -24,7 +24,6 @@
     "BACKLOG.md",
     "bin",
     "docs/delegation-design.md",
-    "hooks",
     "index.js",
     "mcp",
     "SPEC.md",
@@ -40,6 +39,7 @@
   },
   "devDependencies": {
     "conventional-changelog-conventionalcommits": "^10.3.0",
+    "mermaid": "^11.17.0",
     "yaml": "^2.9.0"
   },
   "scripts": {