taskchef 7.14.2 → 7.15.0

package/.codex-plugin/plugin.json

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

package/README.md

@@ -49,7 +49,7 @@ The canonical workspace is `~/.agents/taskchef`. TaskChef owns only:
 ```text
 AGENTS.md       managed dispatcher instructions plus user additions
 taskchef.json   schema-2 configured projects and routing metadata
-tasks.jsonl     one task snapshot per line (schema 8; schema 4/5/6/7 migration supported)
+tasks.jsonl     one task snapshot per line (schema 9; schema 4-8 migration supported)
 ```
 
 List or change routing targets conversationally:
@@ -124,6 +124,10 @@ appends a `turns` entry that pairs that request with a null result while working
 then fills the same entry with the semantic outcome. A follow-up therefore shows
 its own request with “In progress,” never the preceding turn's result. Returned
 tasks still derive `results` and `lastResult` as compatibility projections.
+Every entry has a required `turnRef`, which is the lifecycle identity. When
+Codex exposes a native turn ID, both `turnRef` and `turnId` contain that value.
+Otherwise the executor retains a fresh UUID in `turnRef` and stores
+`turnId: null`; native turn lookup is never a prerequisite for work or reporting.
 If Codex crashes, an MCP call is lost, or the app restarts before that terminal
 report, the next newer `working` report atomically marks the unfinished turn
 `interrupted` and appends the new active turn. `interrupted` is TaskChef-authored
@@ -246,8 +250,9 @@ taskchef doctor
 
 `doctor` is read-only. `workspace init` creates missing files and refreshes
 managed instructions. `workspace migrate` explicitly upgrades supported schema
-4/5/6/7 task lines to schema 8 under the workspace lock. It validates the complete
-source and converted log before writing, creates an exclusive `tasks.jsonl.pre-v8-*.bak`
+4-8 task lines to schema 9 under the workspace lock. It validates task and turn
+counts plus the complete source and converted log before writing, creates an
+exclusive `tasks.jsonl.pre-v9-*.bak`
 backup, atomically replaces the log, validates the result, and becomes an
 idempotent no-op after migration. If replacement fails, the original remains
 or the reported backup can be restored; unsupported or invalid input is rejected
@@ -256,9 +261,9 @@ before a backup or rewrite.
 If a new record has no thread ID, the executor is link-pending. Reopen that
 executor so its first action can retry `link_task`. Do not guess an identity
 or edit `tasks.jsonl`. If native task creation failed, the record is retained
-as `failed` with null thread and turn IDs.
+as `failed` with a retained fallback `turnRef` and null thread and Codex turn IDs.
 
-Schemas other than 4, 5, 6, 7, and 8 remain unsupported. Retain such a workspace
+Schemas other than 4, 5, 6, 7, 8, and 9 remain unsupported. Retain such a workspace
 unchanged and create a current workspace; the migration command deliberately
 does not guess how to convert unknown formats.
 

package/docs/firstmate-taskchef-comparison.md

@@ -115,10 +115,10 @@ creation. The executor then reads its own `CODEX_THREAD_ID` and calls
 The task record keeps one immutable intent/project snapshot plus the latest
 identity and semantic result fields.
 
-**Fact:** Schema 4 linking accepts one atomic null-to-canonical-Codex-UUIDv7
-transition. Exact retries are idempotent, conflicts fail, and link interruption
-remains visibly pending. Follow-up semantic results require a newer exact
-native turn ID.
+**Fact:** Linking accepts one atomic null-to-canonical-Codex-UUIDv7 transition.
+Exact retries are idempotent, conflicts fail, and link interruption remains
+visibly pending. Schema 9 lifecycle callbacks use a required `turnRef`: the
+native Codex turn ID when available, or a retained UUID with `turnId: null`.
 
 ### FirstMate
 
@@ -162,7 +162,7 @@ backends have different verification or experimental status.
 
 **Fact:** Persisted statuses are `working`, `needs_input`, `completed`, and
 `failed`. Executors report
-`working` at turn start and a semantic state before ending. Schema 8 preserves
+`working` at turn start and a semantic state before ending. Schema 9 preserves
 the paired turn timeline and semantic-only compatibility results while a newer
 turn is working. If a terminal report is lost, the next valid working start
 closes the predecessor with a timeline-only `interrupted` outcome rather than

package/docs/spec.md

@@ -26,7 +26,8 @@ is dated research, not contract.
 | **Turn timeline** | The ordered collection pairing each turn's concise request summary with its semantic result, TaskChef-generated interruption outcome, or current in-progress state. |
 | **Interrupted turn** | A formerly active turn that lacked a terminal report when a newer valid turn started; TaskChef closes it with the fixed timeline-only `interrupted` outcome. |
 | **Last semantic result** | The final result-history entry, exposed through the derived `lastResult` compatibility alias. |
-| **Current turn ID** | The canonical Codex UUIDv7 returned by an exact native read of the linked executor for the turn being reported. |
+| **Turn reference** | Required lifecycle identity for one executor prompt. It is the native Codex turn ID when available, otherwise a retained client-generated UUID. |
+| **Current turn ID** | Optional Codex metadata for the reported prompt; null when native turn reading is unavailable. |
 | **Dashboard** | The loopback, read-only UI derived from validated workspace snapshots and bounded native actions. |
 | **Skill** | One packaged agent procedure: `taskchef-bootstrap`, `taskchef-delegate`, `taskchef-executor`, or `taskchef-copilot`. |
 
@@ -71,8 +72,8 @@ Repository URLs MUST canonicalize to `https://github.com/<owner>/<repository>`
 and be case-insensitively deduplicated.
 
 `tasks.jsonl` MUST contain zero or more newline-terminated schema-4 through
-schema-8 records, one per line. Schemas 4 through 7 are supported
-migration/read formats; every new record and state mutation MUST write schema 8. Other schemas
+schema-9 records, one per line. Schemas 4 through 8 are supported
+migration/read formats; every new record and state mutation MUST write schema 9. Other schemas
 or unsupported fields MUST be rejected without conversion.
 Reads and writes MUST reject symlinked managed files. Mutations
 MUST hold the shared workspace lock and replace state atomically; read-only
@@ -84,7 +85,7 @@ Every record MUST contain exactly these fields:
 
 | Field | Contract |
 | --- | --- |
-| `schemaVersion` | Integer `8`; schema-4/5/6/7 records remain readable until explicit migration or their next mutation. |
+| `schemaVersion` | Integer `9`; schema-4/5/6/7/8 records remain readable until explicit migration or their next mutation. |
 | `id` | Unique safe TaskChef ID; delegation uses a lowercase full UUID. |
 | `project` | Immutable configured-project snapshot. |
 | `title` | Non-empty display title. |
@@ -93,16 +94,17 @@ Every record MUST contain exactly these fields:
 | `createdAt` | ISO 8601 creation timestamp. |
 | `status` | `working`, `needs_input`, `completed`, or `failed`. |
 | `summary` | Null while working; otherwise the current semantic state's non-empty summary of at most 2,000 characters. |
-| `turnId` | Null before turn reporting; otherwise the current reported turn. Linked MCP journeys use a canonical Codex UUIDv7. |
+| `turnRef` | Null before reporting begins; otherwise the required lifecycle identity of the current turn. Self-linking journeys use a native or fallback UUID. Migrated low-level `report_result` compatibility records may retain an opaque ref equal to their opaque `turnId`. |
+| `turnId` | Optional Codex metadata. When non-null it equals `turnRef`; null indicates fallback identity. |
 | `updatedAt` | ISO 8601 timestamp not earlier than `createdAt` or the prior `updatedAt`; clock rollback cannot backdate a transition. |
 | `updatedBy` | `dispatcher` or `mcp`. |
-| `turns` | Ordered oldest-first array of `{turnId, requestSummary, startedAt, result}`. `requestSummary` is null only for migrated/compatibility turns. `result` is null only for the latest working turn, a semantic `{status, summary, updatedAt}` result, or the TaskChef-generated `{status: "interrupted", summary: "Turn interrupted before a terminal report.", updatedAt}` outcome. Canonical self-linking turn IDs are unique. A migrated low-level opaque record may retain one final reused ID to represent its legacy completed-result-plus-working-state ambiguity. |
+| `turns` | Ordered oldest-first array of `{turnRef, turnId, requestSummary, startedAt, result}`. Every `turnRef` is required. `requestSummary` is null only for migrated/compatibility turns. `result` is null only for the latest working turn, a semantic `{status, summary, updatedAt}` result, or the fixed TaskChef `interrupted` outcome. New self-linking turn refs are unique. A migrated low-level opaque record may retain one final reused native-derived ref for its legacy ambiguity. |
 
 Returned Task objects MUST additionally expose `latestTurn` as null for an empty
 timeline or the final `turns` entry. They MUST derive `results` only from
 semantic `needs_input`, `completed`, and `failed` turn results and `lastResult`
 from the final derived semantic result. Interrupted outcomes MUST be excluded.
-These projections MUST NOT be persisted in schema 8 and remain compatibility
+These projections MUST NOT be persisted in schema 9 and remain compatibility
 aliases for existing callers.
 
 Task IDs and non-null thread identities MUST be unique. The immutable intent
@@ -129,12 +131,15 @@ the final link, preserving the delegate skill's immediate-return contract.
 5. It MUST create exactly one native Codex executor and 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 exactly read its linked task and
-   call `report_state` with that turn ID, `working`, and no summary before work.
-8. Before ending, it MUST call `report_state` for the same working turn with a
+7. After initial linking, the executor MUST establish a `turnRef`. It MUST use
+   the native Codex turn ID for both `turnRef` and `turnId` when available;
+   otherwise it MUST retain a fresh UUID `turnRef` and use `turnId: null`.
+   It MUST call `report_state` with that identity, `working`, and no summary before work.
+8. Before ending, it MUST call `report_state` with the same `turnRef` and
+   `turnId` metadata as the working report and a
    semantic status and concise summary.
-9. A follow-up MUST report `working` with its new current turn ID before work.
-   It MUST NOT reuse a prior turn. If the preceding turn is still unfinished,
+9. A follow-up MUST report `working` with a new `turnRef` before work.
+   It MUST NOT reuse a prior prompt's ref. If the preceding turn is still unfinished,
    TaskChef MUST atomically close it as `interrupted` before appending the new
    working turn; the executor MUST NOT report semantic `failed` for recovery.
 
@@ -146,7 +151,8 @@ managed child repository and its workspace/root repository MUST include both
 pull-request URLs. Executors MUST NOT guess unresolved repository identity.
 
 If native creation fails after recording, the dispatcher MUST call
-`report_state` with `failed`, null thread/turn IDs, and a bounded summary.
+`report_state` with `failed`, a retained fallback UUID `turnRef`, null thread
+and Codex turn IDs, and a bounded summary.
 A link failure MUST remain visible and retryable; the executor MUST report it
 visibly and MUST NOT continue substantive work.
 
@@ -254,7 +260,7 @@ new preparation values, though it writes no state.
 
 **Structured output:** `{ task: Task }`.
 
-The returned task has schema 8, `working`, null summary/turn/thread/latestTurn/lastResult,
+The returned task has schema 9, `working`, null summary/turn/thread/latestTurn/lastResult,
 empty `turns` and derived `results` arrays,
 `updatedBy: dispatcher`, and equal creation/update timestamps. Duplicate IDs,
 unknown projects, malformed markers, and invalid input fail. Repeating a
@@ -292,23 +298,29 @@ marker, or ineligible state fails.
 | --- | --- |
 | `taskId` | Non-empty string. |
 | `threadId` | Matching non-empty ID for a linked task; null only for creation failure. |
-| `turnId` | Current canonical Codex UUIDv7 for a linked MCP journey; null only for creation failure. Maximum 256 characters at the MCP boundary. |
+| `turnRef` | Stable UUID for this prompt. It may be omitted only by legacy callers that supply a non-null `turnId`, in which case TaskChef derives the same value. |
+| `turnId` | Optional Codex metadata. When present it MUST equal `turnRef`; null is valid for fallback UUID refs. Maximum 256 characters. |
 | `status` | `working`, `needs_input`, `completed`, or `failed`. |
 | `summary` | Omitted or null for `working`; required non-empty string of at most 2,000 characters otherwise. Known GitHub issues and pull requests use canonical URLs. |
 | `requestSummary` | Concise current request of at most 1,000 characters for `working`; optional for backward compatibility and omitted for semantic states. A known selected GitHub repository uses its canonical URL. |
 
 **Structured output:** `{ task: Task }`.
 
-For a linked self-linking journey, a new `working` state MUST identify a turn
-newer than the current turn and last semantic result. An exact retry of any
-already-recorded working start MUST return the current task without mutation.
+For a linked self-linking journey, a new `working` state MUST use a `turnRef`
+not already assigned to a different turn. An exact retry of the current
+working start MUST return the current task without mutation.
+When `turnId` is present, its native-backed `turnRef` MUST also be newer than
+every previously stored native-backed ref. Fallback UUID refs are opaque and
+MUST NOT be lexically ordered.
 A semantic state MUST match the current working turn. Conflicting or stale
-state fails. A null-identity record accepts only a fresh executor
-creation `failed` state with both IDs null. Starting work appends one turn with
+state fails. A null-thread record accepts only a fresh executor creation
+`failed` state with a retained `turnRef` and null thread/turn IDs. Starting work appends one turn with
 its request and a null result. When the previous latest turn is unfinished, the
 same locked atomic rewrite MUST first fill it with the fixed TaskChef-generated
 `interrupted` outcome. The semantic report fills the active turn's result.
-An identical retry for any settled turn returns success without an append. A
+An identical retry for the current settled turn returns success without an
+append. Once a newer turn starts, every callback for a historical ref is stale
+and fails, even when its content exactly matches the stored callback. A
 different request or result for the same turn, a stale turn, or a semantic
 result that does not match the active working turn MUST fail.
 
@@ -325,8 +337,9 @@ MUST contain no crash output, transcript, user text, or inferred failure cause.
 temporary compatibility alias. It implicitly accepts a fresh supplied turn and
 stores its semantic result in a request-unknown turn, including for supported schema-4/5/6 records and
 low-level opaque direct records. It does not accept `working`. New executor
-instructions MUST use `report_state`. Successful mutation upgrades schema 4/5/6/7
-to schema 8; unsupported schemas remain rejected.
+instructions MUST use `report_state`. Successful mutation upgrades schema 4-8
+to schema 9; unsupported schemas remain rejected. Legacy callers that omit
+`turnRef` remain compatible when `turnId` is non-null.
 
 ## Copilot and dashboard
 
@@ -377,10 +390,10 @@ Snapshot and SSE list payloads MUST omit full `turns` and derived `results`
 history and include `latestTurn`. The bounded per-task detail endpoint MAY
 return the full validated task so the dialog can render the paired timeline newest first.
 Dashboard notifications MUST capture an immutable event-time projection of the
-task title, lifecycle state and event, turn ID when present, event timestamp,
+task title, lifecycle state and event, turn ref and optional Codex turn ID, event timestamp,
 and relevant concise summary. Rendering MUST NOT resolve historical notice text
 from the task's later current state. Notice identity and deduplication MUST use
-task ID, turn ID, and lifecycle event; a creation notice without a turn ID MUST
+task ID, turn ref, and lifecycle event; a creation notice without a turn ref MUST
 fall back to task ID plus the immutable creation timestamp. Dashboard revision
 MUST NOT be the sole identity. Identical snapshots, SSE reconnects, idempotent
 reports, schema normalization, and non-semantic rewrites MUST NOT add notices.
@@ -407,13 +420,15 @@ its displayed summary when present, event time, and missing-task state.
 
 ## Task-log migration
 
-`workspace migrate` MUST explicitly convert every supported schema-4/5/6/7 record
+`workspace migrate` MUST explicitly convert every supported schema-4/5/6/7/8 record
 under the shared lock. Each legacy semantic result becomes a request-unknown
 completed turn; a newer working state becomes a final unfinished turn, and a
-schema-7 timeline is preserved losslessly. Migration MUST validate the complete
-source and complete schema-8 candidate before changing the task log,
+schema-7/8 timeline is preserved. Each non-null legacy `turnId` becomes the
+same `turnRef`; each null legacy `turnId` receives one durably persisted UUID.
+Migration MUST validate the complete source, record/turn counts, turn-ref
+invariants, and complete schema-9 candidate before changing the task log,
 create and read back an exclusive recovery backup, atomically replace the log,
-and validate the installed result. A fully schema-8 log MUST be an idempotent
+and validate the installed result. A fully schema-9 log MUST be an idempotent
 no-op without another backup. Invalid/unsupported input MUST remain untouched;
 failures after backup creation MUST report the backup path and MUST never
 partially rewrite individual lines.

package/docs/workflows.md

@@ -89,7 +89,7 @@ sequenceDiagram
   D->>D: Choose one configured and native project
   D->>M: record_task(id, project, title, instruction, null)
   M->>W: recordTask()
-  W->>W: Lock, validate, append schema-8 snapshot
+  W->>W: Lock, validate, append schema-9 snapshot
   W-->>M: working link-pending task
   M-->>D: task
   D->>C: Create executor with marked instruction
@@ -116,9 +116,10 @@ semantic callbacks.
 
 ## State reporting
 
-The executor obtains the turn identity from an exact native read of its own
-linked task. `report_state` records live turn state as a paired request/result
-timeline.
+The executor always establishes a `turnRef` before work. An exact native read
+supplies the same value as optional `turnId` metadata when available; otherwise
+the executor retains a fresh UUID and reports `turnId: null`. `report_state`
+records live turn state as a paired request/result timeline.
 
 That timeline is also the durable GitHub-link source. A working request names a
 known selected repository with its canonical GitHub URL. A terminal result
@@ -134,13 +135,16 @@ sequenceDiagram
   participant C as Native Codex task API
   participant M as TaskChef MCP
   participant W as workspace.js
-  E->>C: Exact read of linked executor
-  C-->>E: Current turn ID
-  E->>M: report_state(..., working, requestSummary)
+  opt Native turn metadata available
+    E->>C: Exact read of linked executor
+    C-->>E: Current turn ID
+  end
+  E->>E: Retain native ID or generate fallback UUID turnRef
+  E->>M: report_state(..., turnRef, turnId, working, requestSummary)
   M->>W: reportTaskState()
   W->>W: Append turn with request and null result
   E->>E: Work, finish, or reach semantic decision
-  E->>M: report_state(..., semantic status, summary)
+  E->>M: report_state(..., same turnRef, same turnId, semantic status, summary)
   M->>W: reportTaskState()
   W->>W: Lock and validate identity and freshness
   alt Same current working turn
@@ -161,8 +165,10 @@ for a user decision or fact required to proceed.
 
 ## Follow-up turns
 
-Turn IDs are freshness tokens for semantic callbacks. Lexical UUIDv7 order lets
-the workspace reject a callback from an older executor turn.
+Turn refs are freshness tokens for semantic callbacks. The workspace rejects a
+callback whose ref belongs to a historical turn. Fallback UUID refs are opaque
+and unordered; native-backed UUIDv7 refs retain native ordering so a delayed,
+previously unseen older start cannot replace newer native state.
 
 ```mermaid
 sequenceDiagram
@@ -181,7 +187,7 @@ sequenceDiagram
   C-->>E: turnB
   E->>M: report_state(..., turnB, working, requestB)
   M->>W: reportTaskState()
-  W->>W: Require turnB greater and append request B
+  W->>W: Require a fresh turnB ref and append request B
   W-->>M: working snapshot plus paired timeline
   M-->>E: working snapshot plus paired timeline
   E->>M: report_state(..., turnB, completed, summaryB)
@@ -190,12 +196,13 @@ sequenceDiagram
   M-->>E: completed snapshot plus result B
   E->>M: report_state(..., turnA, completed, staleSummary)
   M->>W: Validate freshness
-  W-->>M: Error: turn is not newer
+  W-->>M: Error: stale turnRef
   M-->>E: Visible tool error
 ```
 
-The executor contract therefore requires a new exact read on every follow-up;
-cached or inherited turn IDs are invalid.
+The executor contract therefore requires a new `turnRef` on every follow-up.
+Native turn reads are preferred metadata but optional; cached or inherited IDs
+and replacement fallback UUIDs for the same prompt are invalid.
 
 ## Interrupted-turn recovery
 
@@ -211,12 +218,12 @@ sequenceDiagram
   participant M as TaskChef MCP
   participant W as workspace.js
   participant F as tasks.jsonl
-  E->>M: report_state(..., turnB, working, requestB)
+  E->>M: report_state(..., turnRefB, working, requestB)
   M->>W: reportTaskState()
-  W->>W: Acquire workspace lock and validate turnB > turnA
+  W->>W: Acquire workspace lock and validate turnRefB is new
   W->>W: Close unfinished turnA as interrupted
   W->>W: Append turnB with requestB and null result
-  W->>F: One atomic schema-8 replacement
+  W->>F: One atomic schema-9 replacement
   W-->>M: working task projected from turnB
   M-->>E: Idempotent recovery success
   E->>M: late semantic result for turnA
@@ -277,10 +284,11 @@ sequenceDiagram
   W-->>D: Recorded task
   D->>C: Create executor
   C--xD: Creation error
-  D->>M: report_state(taskId, null, null, failed, boundedSummary)
+  D->>D: Generate and retain fallback UUID turnRef
+  D->>M: report_state(taskId, null, turnRef, null, failed, boundedSummary)
   M->>W: Lock and store creation failure
-  W-->>D: Failed task with null IDs
-  D-->>D: Preserve original creation error and task ID
+  W-->>D: Failed task with turnRef and null native IDs
+  D-->>D: Preserve original creation error, task ID, and turnRef
 ```
 
 The summary is bounded and excludes secrets, transcripts, and raw command
@@ -331,8 +339,8 @@ against current configuration.
 
 The browser derives one immutable Updates-panel snapshot when it first observes
 a semantic lifecycle transition. The snapshot keeps its event-time title,
-state/event, turn ID, timestamp, and relevant summary. Its identity combines
-task ID, turn ID, and event, with creation time as the fallback when creation
+state/event, turn ref, optional Codex turn ID, timestamp, and relevant summary.
+Its identity combines task ID, turn ref, and event, with creation time as the fallback when creation
 has no turn. A separate seen-identity set outlives the bounded visible notices,
 individual dismissals, and Clear all, preventing replay after reconnect,
 normalization, or disappearance and reappearance. Per-task semantic signatures
@@ -351,15 +359,16 @@ all, and ordinary rerendering do not re-announce retained history. Toast action
 labels remain concise while `aria-describedby` connects the visible summary,
 event time, and missing-task explanation for assistive technology.
 
-## Schema 4/5/6/7 migration
+## Schema 4-8 migration
 
 `taskchef workspace migrate` acquires the same workspace lock as lifecycle
 writers, validates the complete legacy log, converts schema-4/5/6 results into
 request-unknown completed turns and preserves a newer working turn, then validates the
 complete candidate. Before replacement it writes and reads back an exclusive
-`tasks.jsonl.pre-v8-*.bak` file. Schema-7 timelines are copied losslessly into
-schema 8. The task log is replaced atomically and validated again. A second run
-sees only schema 8 and returns unchanged without
+`tasks.jsonl.pre-v9-*.bak` file. Schema-7/8 timelines gain a durable `turnRef`:
+non-null `turnId` values are copied exactly and null IDs receive persisted UUIDs.
+Task and turn counts plus all refs are validated before and after the atomic
+replacement. A second run sees only schema 9 and returns unchanged without
 another backup. Unsupported or malformed input fails before backup/rewrite;
 after a later filesystem failure, the reported backup is the recovery source.
 
@@ -376,9 +385,9 @@ summary is cryptographically authenticated; this is a local single-user trust
 model. Managed files, instructions, project snapshots, MCP inputs, and dashboard
 requests are validated at every action boundary.
 
-Configuration schema 2 and task schemas 4, 5, 6, 7, and 8 are accepted. Schemas
-4/5/6/7 are read/migration compatibility until an explicit migration or lifecycle
-mutation upgrades each record to schema 8. Schema 8 persists `turns`, including
+Configuration schema 2 and task schemas 4 through 9 are accepted. Schemas
+4-8 are read/migration compatibility until an explicit migration or lifecycle
+mutation upgrades each record to schema 9. Schema 9 persists `turns`, including
 timeline-only interrupted outcomes, and derives semantic-only `results` and
 `lastResult` plus `latestTurn` for compact compatibility. Other schemas
 are rejected without rewrite.

package/package.json

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

package/skills/taskchef-delegate/SKILL.md

@@ -70,5 +70,7 @@ stop and report that the TaskChef plugin must be reloaded or installed.
 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.
-8. If creation fails after recording, call `report_state` with `failed`, null
-   thread/turn IDs, and a bounded summary before returning the failure.
+8. If creation fails after recording, generate a fresh UUID and call
+   `report_state` with it as `turnRef`, `failed`, null thread and Codex turn IDs,
+   and a bounded summary before returning the failure. Retain that UUID for an
+   exact retry.

package/skills/taskchef-executor/SKILL.md

@@ -30,10 +30,14 @@ Complete this lifecycle setup before substantive assignment work:
    that exact thread ID as the first TaskChef action. An identical retry is
    idempotent. On a follow-up, retry the same link only when the prior link
    cannot be established from the task context.
-3. Read this exact Codex thread natively and obtain the current turn ID. Do not
-   infer it or reuse an earlier turn ID.
+3. Establish this prompt's lifecycle identity before reporting. If this exact
+   Codex thread can be read natively and exposes the current turn ID, use that
+   exact value for both `turnRef` and `turnId`. Otherwise generate one fresh
+   UUID locally, retain it for this entire prompt, use it as `turnRef`, and use
+   `turnId: null`. Do not infer a native ID, reuse an earlier prompt's
+   `turnRef`, or let a retry generate a replacement UUID.
 4. Call TaskChef `report_state` with the marked task ID, self-linked thread ID,
-   current turn ID, `status: working`, an omitted or null result summary, and a
+   this prompt's `turnRef` and optional Codex `turnId`, `status: working`, an omitted or null result summary, and a
    concise `requestSummary` describing this turn's assignment or follow-up.
    When the turn targets a known GitHub repository, include its canonical
    `https://github.com/<owner>/<repository>` URL so multi-repository projects
@@ -45,15 +49,17 @@ as interrupted and starts the current turn. Continue the real assignment from
 the current request. Do not manufacture a semantic `failed` result for the old
 turn and do not retry an old terminal report.
 
-If `CODEX_THREAD_ID`, exact native thread reading, or a required TaskChef tool
-is unavailable, or if linking or the working-state report fails, report the
-failure visibly and stop before substantive work. Retry on a later turn. Never
-guess identity or bypass a link-pending state.
+If `CODEX_THREAD_ID` or a required TaskChef tool is unavailable, or if linking
+or the working-state report fails, report the failure visibly and stop before
+substantive work. Native turn reading is optional because the retained fallback
+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.
 
 ## Finish every execution turn
 
-Before ending, read this exact Codex thread again and call `report_state` for
-the current turn with one semantic status and a concise summary:
+Before ending, call `report_state` with the same `turnRef` and `turnId` values
+used by this prompt's working report, one semantic status, and a concise summary:
 
 - `completed` only when the assignment is genuinely complete.
 - `needs_input` only when a semantic decision or missing information must come
@@ -62,16 +68,16 @@ the current turn with one semantic status and a concise summary:
 
 A live native approval prompt is Codex state, not semantic `needs_input`; leave
 the approval live instead of storing it as a TaskChef result. Never invent or
-reuse a turn ID after a follow-up. If a final-report response is lost, an
+reuse a `turnRef` after a follow-up. If a final-report response is lost, an
 identical terminal retry is safe only while the same turn remains current. On
-a later turn, run the start lifecycle with its new current turn ID; TaskChef
+a later prompt, run the start lifecycle with a new `turnRef`; TaskChef
 will preserve the predecessor as interrupted, and only the new turn may receive
 a semantic result. Say reporting failures visibly instead of claiming a tracked
 outcome.
 
 Request and result summaries must omit secrets, transcripts, raw command output, hidden reasoning,
 and unnecessary personal data. Identical lifecycle retries are safe; never
-replace a same-turn report with different content or let an older turn
+replace a same-`turnRef` report with different content or let an older turn
 overwrite newer state.
 
 ### Preserve repository and delivery links

package/src/cli.js

@@ -173,10 +173,12 @@ function taskDetails(task) {
     `Title: ${singleLineDetail(task.title)}`,
     `Project: ${singleLineDetail(task.project.name)}`,
     `Current status: ${singleLineDetail(task.status ?? "unknown")}`,
-    `Current turn ID: ${singleLineDetail(task.turnId ?? "-")}`,
+    `Current turn ref: ${singleLineDetail(task.turnRef ?? "-")}`,
+    `Current Codex turn ID: ${singleLineDetail(task.turnId ?? "-")}`,
     `Last result status: ${singleLineDetail(lastResult?.status ?? "-")}`,
     `Last result summary: ${singleLineDetail(lastResult?.summary ?? "-")}`,
-    `Last result turn ID: ${singleLineDetail(lastResult?.turnId ?? "-")}`,
+    `Last result turn ref: ${singleLineDetail(lastResult?.turnRef ?? "-")}`,
+    `Last result Codex turn ID: ${singleLineDetail(lastResult?.turnId ?? "-")}`,
     `Last result updated: ${singleLineDetail(lastResult?.updatedAt ?? "-")}`,
     `Project path: ${singleLineDetail(task.project.path)}`,
     `Created: ${singleLineDetail(task.createdAt)}`,
@@ -187,7 +189,7 @@ function taskDetails(task) {
     `Turn count: ${task.turns.length}`,
     "Activity timeline (newest first):",
     ...[...task.turns].reverse().map((turn) => (
-      `- ${singleLineDetail(turn.startedAt)} | ${singleLineDetail(turn.result?.status ?? "working")} | turn ${singleLineDetail(turn.turnId ?? "-")} | request: ${singleLineDetail(turn.requestSummary ?? "not recorded")} | result: ${singleLineDetail(turn.result?.summary ?? "in progress")}`
+      `- ${singleLineDetail(turn.startedAt)} | ${singleLineDetail(turn.result?.status ?? "working")} | ref ${singleLineDetail(turn.turnRef ?? "-")} | Codex turn ${singleLineDetail(turn.turnId ?? "-")} | request: ${singleLineDetail(turn.requestSummary ?? "not recorded")} | result: ${singleLineDetail(turn.result?.summary ?? "in progress")}`
     )),
     "Instruction:",
     task.instruction,
@@ -200,7 +202,10 @@ async function migrate(args) {
   print(result, args, (value) => [
     `Task log: ${value.action}`,
     `Tasks: ${value.taskCount}`,
+    `Turns: ${value.turnCount}`,
     `Migrated: ${value.migratedCount}`,
+    `Native turn refs: ${value.nativeTurnRefCount}`,
+    `Fallback turn refs: ${value.fallbackTurnRefCount}`,
     `Backup: ${value.backupPath ?? "not needed"}`,
   ].join("\n"));
   return 0;

package/src/dashboard/app.js

@@ -259,7 +259,7 @@ function notificationAnnouncement(notification) {
     notificationTitle(notification),
     notification.title,
     notification.summary,
-    notification.turnId ? `Turn ${notification.turnId}` : null,
+    notification.turnRef ? `Turn ref ${notification.turnRef}` : null,
     formatRelativeTime(notification.timestamp),
   ].filter(Boolean).join(". ");
 }
@@ -302,7 +302,7 @@ function turnTimeline(task) {
     const turnStatus = presentation.status;
     status.className = `status status-${turnStatus}`;
     status.textContent = turnStatus.replaceAll("_", " ");
-    const turnKey = turn.turnId ?? `no-turn:${index}`;
+    const turnKey = turn.turnRef ?? turn.turnId ?? `no-turn:${index}`;
     const timestamp = timestampControl(presentation.updatedAt, {
       accessibleName: `Turn updated time for ${turnStatus.replaceAll("_", " ")}`,
       key: `detail:${task.id}:turn:${turnKey}`,
@@ -324,9 +324,7 @@ function turnTimeline(task) {
     appendLinkedText(result, presentation.summary, task);
     const turnMetadata = document.createElement("p");
     turnMetadata.className = "result-history-turn";
-    turnMetadata.textContent = turn.turnId
-      ? `Turn ${turn.turnId}`
-      : "No turn ID (creation failure)";
+    turnMetadata.textContent = `Turn ref ${turn.turnRef ?? "not recorded"}; Codex turn ${turn.turnId ?? "unavailable"}`;
     item.append(header, requestLabel, request, resultLabel, result, turnMetadata);
     return item;
   });
@@ -357,9 +355,11 @@ function renderDialog(task) {
   elements.copyThreadId.disabled = !task.threadId;
   elements.dialogMetadata.replaceChildren(
     ...detailRow("Current status", taskStatusLabel(task)),
-    ...detailRow("Current turn ID", task.turnId),
+    ...detailRow("Current turn ref", task.turnRef),
+    ...detailRow("Current Codex turn ID", task.turnId),
     ...detailRow("Last result status", task.lastResult?.status?.replaceAll("_", " ")),
-    ...detailRow("Last result turn ID", task.lastResult?.turnId),
+    ...detailRow("Last result turn ref", task.lastResult?.turnRef),
+    ...detailRow("Last result Codex turn ID", task.lastResult?.turnId),
     ...detailRow("Last result updated", timestampControl(task.lastResult?.updatedAt, {
       accessibleName: `Last result updated time for ${task.title}`,
       key: `detail:${task.id}:last-result-updated`,