taskchef 5.12.0 → 6.0.0

package/docs/delegation-design.md

@@ -1,178 +1,77 @@
 # 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.
-
-## Minimal workflow
-
-```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
-```
-
-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
+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
+
+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`.
+
+## 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.0.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",