taskchef 3.0.1 → 3.0.3

package/.codex-plugin/plugin.json

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

package/BACKLOG.md

@@ -39,3 +39,18 @@ clear data model before implementation.
 - Evaluate automatic project discovery rules and exclusions.
 - Consider multiple executor threads for one logical assignment if a real
   workflow requires it.
+
+## Codex provisional thread lifecycle
+
+- Track [openai/codex#26861](https://github.com/openai/codex/issues/26861),
+  where worktree creation can return only a provisional `clientThreadId` or
+  `pendingWorktreeId` with no supported mapping to the durable `threadId`.
+- Prefer an official bounded operation such as
+  `wait_for_thread(clientThreadId, timeoutMs) -> { status, threadId? }` or
+  `resolve_client_thread(clientThreadId) -> { status, threadId? }`. Returning a
+  reserved durable ID from `create_thread`, or emitting a materialization event
+  containing it, would also close the lifecycle gap.
+- Re-evaluate TaskChef's sparse marker-discovery fallback when Codex exposes
+  one of these APIs. Keep exact marker verification before persisting the
+  returned durable ID unless the official contract provides equivalent
+  correlation guarantees.

package/README.md

@@ -117,9 +117,18 @@ the same project.
 Open an executor and prompt it like any other Codex task. Its thread is the
 live source of truth for progress, questions, and results.
 
-The dispatcher workspace keeps `tasks.jsonl`, an append-only history of
-successful delegations. It records what TaskChef sent, when it sent it, which
-project it selected, and which Codex task received the work.
+The dispatcher workspace keeps `tasks.jsonl`, a history of submitted
+delegations. New tasks are appended; the only later change allowed is filling
+an unresolved task's nullable thread ID. The log records what TaskChef sent,
+when it sent it, which project it selected, and which Codex task received the
+work.
+
+Every delegated instruction includes a unique `# taskchef_id=<UUID>` marker.
+If worktree creation does not return a thread ID immediately, TaskChef records
+the marked delegation as unresolved, then waits briefly for the durable task.
+It prefers a native Codex client-ID resolver when available and otherwise makes
+two exact-marker checks during a short bounded window. If it still cannot
+identify exactly one task, the recorded marker remains available for recovery.
 
 ### Ask for a live report
 
@@ -161,8 +170,9 @@ project metadata that TaskChef used when it delegated the work.
 
 - TaskChef is an interactive dispatcher. It is not a scheduler, daemon, hook
   service, or background worker.
-- Executors are visible Codex tasks. The dispatcher does not supervise them or
-  wait for them to finish.
+- Executors are visible Codex tasks. The dispatcher may wait briefly to resolve
+  a worktree task's thread ID, but it does not supervise executors or wait for
+  them to finish.
 - TaskChef routes only to projects on the same local execution host.
 - The task history contains successful delegations, not current task status or
   task results.
@@ -213,6 +223,7 @@ taskchef project import [<file> | -]
 taskchef project list
 taskchef project remove <name>
 taskchef task record
+taskchef task resolve <task-id> --thread-id <thread-id>
 taskchef task show <task-id>
 taskchef task list
 taskchef task summary
@@ -250,14 +261,24 @@ set.
 
 ### Task history
 
-`task record` reads one successful delegation from standard input. The
+`task record` reads one submitted delegation from standard input. The
 `project` value is the exact configured project path:
 
 ```sh
-printf '%s\n' '{"id":"t1","project":"/workspace/payments","title":"Add retry logs","instruction":"Add structured logs for failed retries and test them.","threadId":"019f..."}' |
+printf '%s\n' '{"id":"c0f010ff-84f2-4838-a69d-0ff1f5d721d7","project":"/workspace/payments","title":"Add retry logs","instruction":"# taskchef_id=c0f010ff-84f2-4838-a69d-0ff1f5d721d7\n\nAdd structured logs for failed retries and test them.","threadId":"019f..."}' |
   taskchef task record --json --workspace <workspace>
 ```
 
+If a task has `threadId: null`, Codex can later find its exact marker and pass
+the verified durable ID to the CLI. Resolution is atomic and only permits the
+one-way transition from null to one unique thread ID:
+
+```sh
+taskchef task resolve c0f010ff-84f2-4838-a69d-0ff1f5d721d7 \
+  --thread-id 019f9d46-f42c-7482-9707-3c107bf241ee \
+  --workspace <workspace>
+```
+
 Inspect the task history without querying Codex tasks:
 
 ```sh

package/SPEC.md

@@ -3,8 +3,9 @@
 ## Purpose
 
 TaskChef is an interactive Codex dispatcher. It routes independent assignments
-to real Codex tasks in configured local projects, records each successful
-delegation in an append-only task history, and returns immediately.
+to real Codex tasks in configured local projects, records each submitted
+delegation in a task history, and returns immediately. New tasks append; only a
+nullable thread ID may later transition to its durable value.
 
 Codex tasks remain authoritative for their progress and results. TaskChef does
 not maintain a second lifecycle database.
@@ -16,8 +17,10 @@ not maintain a second lifecycle database.
 3. It selects each target using configured project metadata and validates the
    selected local path.
 4. It creates an independently openable Codex task in that project.
-5. After creation returns a thread ID, it appends one task entry.
-6. It returns without waiting for the executor.
+5. It embeds a generated TaskChef UUID marker in the initial instruction before
+   creation. It appends one task entry as soon as creation returns, using
+   `threadId: null` while a provisional client ID is briefly resolved.
+6. It returns without waiting for executor work to complete.
 7. When requested, TaskChef can read task entries, query the relevant Codex
    tasks once, and present a live report without persisting the fetched state.
 
@@ -38,15 +41,11 @@ live report requests to `$taskchef-report`. Bootstrap preserves unrelated
 instructions and refreshes only the managed block.
 
 `workspace init` is idempotent. It creates an empty configuration and task
-log when missing, refreshes managed instructions, removes legacy TaskChef skill
-symlinks, and migrates legacy task records that contain executor thread IDs.
-It stops on a legacy pending record with no thread ID rather than discarding
-that record. If a legacy record refers to a project that was removed from the
-configuration, migration reconstructs its project snapshot from the existing
-local project path.
+log when missing, refreshes managed instructions, and removes legacy TaskChef
+skill symlinks.
 
 `doctor` validates configuration, project paths, the JSONL log, managed
-instructions, and the absence of legacy workspace structures without modifying
+instructions, and the absence of legacy TaskChef skill links without modifying
 the workspace.
 
 ## Project configuration
@@ -101,22 +100,30 @@ schedules, task status, results, host information, or the workspace path.
 `tasks.jsonl` contains one compact JSON object per line, in append order:
 
 ```json
-{"schemaVersion":1,"id":"d1-retry-logs","project":{"name":"payments-api","path":"/workspace/payments-api","isGitRepository":true,"githubRepo":"https://github.com/example/payments-api","description":"Owns payment authorization, capture, refunds, and provider integrations."},"title":"Add payment retry logs","instruction":"Add structured logs for failed payment retries and test them.","threadId":"019f9d46-f42c-7482-9707-3c107bf241ee","createdAt":"2026-08-08T10:00:00.000Z"}
+{"schemaVersion":1,"id":"c0f010ff-84f2-4838-a69d-0ff1f5d721d7","project":{"name":"payments-api","path":"/workspace/payments-api","isGitRepository":true,"githubRepo":"https://github.com/example/payments-api","description":"Owns payment authorization, capture, refunds, and provider integrations."},"title":"Add payment retry logs","instruction":"# taskchef_id=c0f010ff-84f2-4838-a69d-0ff1f5d721d7\n\nAdd structured logs for failed payment retries and test them.","threadId":"019f9d46-f42c-7482-9707-3c107bf241ee","createdAt":"2026-08-08T10:00:00.000Z"}
 ```
 
 - `schemaVersion` identifies the task entry format.
 - `id` is a unique TaskChef task identifier.
 - `project` is the complete configured project snapshot used for routing.
 - `title` is a short task name.
-- `instruction` is the complete executor instruction.
-- `threadId` identifies the created Codex task.
+- `instruction` is the complete executor instruction, including its first-line
+  `# taskchef_id=<full UUID>` correlation marker.
+- `threadId` identifies the created Codex task, or is `null` when creation was
+  accepted but bounded marker resolution did not find one durable task ID.
 - `createdAt` is the dispatch time as an ISO 8601 timestamp.
 
-Every entry has exactly these fields. IDs and thread IDs must be unique. The
-file is empty or newline terminated, with no blank lines. TaskChef rejects a
-malformed log instead of skipping bad entries. Writers replace the complete
-validated file atomically under a workspace lock, so an interrupted write
-leaves either the old history or the complete new history.
+Every entry has exactly these fields. IDs and non-null thread IDs must be
+unique; any number of unresolved entries may have `threadId: null`. The file is
+empty or newline terminated, with no blank lines. TaskChef rejects a malformed
+log instead of skipping bad entries. Writers replace the complete validated
+file atomically under a workspace lock, so an interrupted write leaves either
+the old history or the complete new history.
+
+Task creation appends entries. The only permitted mutation is an atomic,
+idempotent `task resolve` transition from `threadId: null` to one unique durable
+thread ID. Resolution requires the stored instruction's exact marker to match
+the task ID. A resolved or mismatched entry cannot be overwritten.
 
 The project snapshot preserves the route even if the project is renamed,
 moved, or removed later. Entries never contain status, result, transcript,
@@ -128,9 +135,41 @@ For each assignment, `$taskchef-delegate`:
 
 1. loads and validates configured projects
 2. selects one unambiguous target
-3. creates a real Codex task at the exact configured path
-4. appends a task entry only after receiving the task's thread ID
-5. returns the created task link without reading or waiting for that task.
+3. generates a full UUID and prefixes the instruction with its exact
+   `# taskchef_id=<UUID>` marker
+4. creates a real Codex task at the exact configured path
+5. appends a task entry immediately when creation returns a durable thread ID
+6. when creation returns only a provisional client ID, immediately appends the
+   marked entry with `threadId: null`, then prefers one native client-ID wait or
+   resolution call with a 30-second timeout when Codex exposes one
+7. when no native operation is available, takes at most two recent-thread
+   snapshots near 10 and 30 seconds after the provisional result, filters
+   candidates by available host/project/time/worktree metadata, uses title only
+   as an advisory ordering hint, and accepts only one thread whose structured
+   delegated input starts with the exact marker
+8. atomically fills the nullable thread ID after an exact match
+9. returns after recording or after reporting that bounded resolution was
+   unresolved, without waiting for executor work completion.
+
+The exact random marker makes a pre-creation thread snapshot unnecessary.
+Creation-time filtering allows five seconds of clock skew. Candidate reads run
+concurrently where the host permits and inspect only structured
+`codexDelegation.input`, never untrusted title, summary, preview, or plain-text
+marker echoes. A native resolver result is verified against the same structured
+marker before persistence. Zero exact matches time out unresolved; multiple
+exact matches are ambiguous. Snapshot, candidate-read, native-resolution, or
+task-resolution errors leave the already-recorded nullable entry intact. No
+snapshot, candidate read, marker verification, or task-resolution write starts
+after the 30-second deadline, so tool latency can reduce the number of attempts.
+A `clientThreadId`, `pendingWorktreeId`, or ID in the documented provisional
+`local:` namespace remains diagnostic context and is rejected from every path
+that could persist the canonical `threadId` field.
+
+Desktop thread tools are available to the Codex skill, not to the standalone
+Node CLI. The package therefore exposes testable marker/filter/orchestration
+helpers with injected thread-tool callbacks, while the skill owns the actual
+desktop-tool calls and the CLI remains responsible only for validated data
+operations.
 
 A failed executor creation produces no entry. If executor creation succeeds but
 the append fails, the executor remains valid and TaskChef tells the user that
@@ -144,19 +183,23 @@ The CLI reads persisted history without contacting Codex:
 - `task list` returns entries in append order, optionally filtered by
   historical project name or exact path.
 - `task summary` returns the total and per-project counts.
+- `task resolve <id> --thread-id <thread-id>` atomically fills one nullable
+  thread ID after Codex verifies the exact structured marker match.
 
-When the user requests current state or outcomes, `$taskchef-report` loads the
-relevant entries and queries every recorded Codex task exactly once, in batches
-of no more than eight. It reports the snapshot and discards it. The report does
-not update `tasks.jsonl`, poll, wait, or create a scheduled job.
+When the user requests current state or outcomes, `$taskchef-report` makes one
+marker-based discovery pass for nullable entries and uses `task resolve` only
+for a single exact match. It reports unmatched entries as unresolved and
+queries every durable thread ID exactly once, in batches of no more than eight.
+The report does not poll, wait, persist status or results, or create a scheduled
+job.
 
 ## Boundaries
 
 TaskChef does not include:
 
 - lifecycle status or result persistence
-- task callbacks, hooks, polling, daemons, heartbeats, or schedules
-- arbitrary Codex task discovery
+- task callbacks, hooks, indefinite polling, daemons, heartbeats, or schedules
+- arbitrary Codex task discovery beyond bounded marker-based creation recovery
 - remote hosts or `hostId` storage
 - transcript or hidden-reasoning collection
 - one-active-task-per-project restrictions
@@ -170,10 +213,13 @@ TaskChef does not include:
 2. Project metadata routes an unambiguous request to the correct local project.
 3. A successful delegation creates a visible Codex task and appends its thread
    ID with a project snapshot.
-4. The dispatcher returns without waiting for execution.
-5. Several independent assignments can create several entries, including
+4. A provisional creation with one exact marker match records its durable
+   thread ID; zero or multiple matches record `threadId: null` for later
+   recovery.
+5. The dispatcher returns without waiting for execution.
+6. Several independent assignments can create several entries, including
    multiple entries for the same project.
-6. Task history commands return deterministic entries and project counts.
-7. A live report queries each relevant task once and writes nothing.
-8. Malformed JSONL, duplicate IDs, duplicate thread IDs, and symlinked managed
+7. Task history commands return deterministic entries and project counts.
+8. A live report queries each relevant task once and writes nothing.
+9. Malformed JSONL, duplicate IDs, duplicate thread IDs, and symlinked managed
    files fail safely.

package/index.js

@@ -14,7 +14,25 @@ export {
   listTasks,
   readTask,
   recordTask,
+  resolveTask,
   requireSafeId,
   removeProject,
   validateConfig,
 } from "./src/workspace.js";
+
+export {
+  THREAD_RESOLUTION_CHECKPOINTS_MS,
+  THREAD_RESOLUTION_CLOCK_SKEW_MS,
+  THREAD_RESOLUTION_RECENT_LIMIT,
+  THREAD_RESOLUTION_TIMEOUT_MS,
+  createAndRecordDelegation,
+  filterThreadCandidates,
+  hasExactTaskChefMarker,
+  listThreadEntries,
+  isProvisionalThreadId,
+  normalizeDurableThreadId,
+  parseTaskChefMarker,
+  prepareDelegation,
+  structuredDelegatedInputs,
+  taskChefMarker,
+} from "./src/delegation.js";

package/node_modules/graceful-fs/LICENSE

@@ -0,0 +1,15 @@
+The ISC License
+
+Copyright (c) 2011-2022 Isaac Z. Schlueter, Ben Noordhuis, and Contributors
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR
+IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/node_modules/graceful-fs/README.md

@@ -0,0 +1,143 @@
+# graceful-fs
+
+graceful-fs functions as a drop-in replacement for the fs module,
+making various improvements.
+
+The improvements are meant to normalize behavior across different
+platforms and environments, and to make filesystem access more
+resilient to errors.
+
+## Improvements over [fs module](https://nodejs.org/api/fs.html)
+
+* Queues up `open` and `readdir` calls, and retries them once
+  something closes if there is an EMFILE error from too many file
+  descriptors.
+* fixes `lchmod` for Node versions prior to 0.6.2.
+* implements `fs.lutimes` if possible. Otherwise it becomes a noop.
+* ignores `EINVAL` and `EPERM` errors in `chown`, `fchown` or
+  `lchown` if the user isn't root.
+* makes `lchmod` and `lchown` become noops, if not available.
+* retries reading a file if `read` results in EAGAIN error.
+
+On Windows, it retries renaming a file for up to one second if `EACCESS`
+or `EPERM` error occurs, likely because antivirus software has locked
+the directory.
+
+## USAGE
+
+```javascript
+// use just like fs
+var fs = require('graceful-fs')
+
+// now go and do stuff with it...
+fs.readFile('some-file-or-whatever', (err, data) => {
+  // Do stuff here.
+})
+```
+
+## Sync methods
+
+This module cannot intercept or handle `EMFILE` or `ENFILE` errors from sync
+methods.  If you use sync methods which open file descriptors then you are
+responsible for dealing with any errors.
+
+This is a known limitation, not a bug.
+
+## Global Patching
+
+If you want to patch the global fs module (or any other fs-like
+module) you can do this:
+
+```javascript
+// Make sure to read the caveat below.
+var realFs = require('fs')
+var gracefulFs = require('graceful-fs')
+gracefulFs.gracefulify(realFs)
+```
+
+This should only ever be done at the top-level application layer, in
+order to delay on EMFILE errors from any fs-using dependencies.  You
+should **not** do this in a library, because it can cause unexpected
+delays in other parts of the program.
+
+## Changes
+
+This module is fairly stable at this point, and used by a lot of
+things.  That being said, because it implements a subtle behavior
+change in a core part of the node API, even modest changes can be
+extremely breaking, and the versioning is thus biased towards
+bumping the major when in doubt.
+
+The main change between major versions has been switching between
+providing a fully-patched `fs` module vs monkey-patching the node core
+builtin, and the approach by which a non-monkey-patched `fs` was
+created.
+
+The goal is to trade `EMFILE` errors for slower fs operations.  So, if
+you try to open a zillion files, rather than crashing, `open`
+operations will be queued up and wait for something else to `close`.
+
+There are advantages to each approach.  Monkey-patching the fs means
+that no `EMFILE` errors can possibly occur anywhere in your
+application, because everything is using the same core `fs` module,
+which is patched.  However, it can also obviously cause undesirable
+side-effects, especially if the module is loaded multiple times.
+
+Implementing a separate-but-identical patched `fs` module is more
+surgical (and doesn't run the risk of patching multiple times), but
+also imposes the challenge of keeping in sync with the core module.
+
+The current approach loads the `fs` module, and then creates a
+lookalike object that has all the same methods, except a few that are
+patched.  It is safe to use in all versions of Node from 0.8 through
+7.0.
+
+### v4
+
+* Do not monkey-patch the fs module.  This module may now be used as a
+  drop-in dep, and users can opt into monkey-patching the fs builtin
+  if their app requires it.
+
+### v3
+
+* Monkey-patch fs, because the eval approach no longer works on recent
+  node.
+* fixed possible type-error throw if rename fails on windows
+* verify that we *never* get EMFILE errors
+* Ignore ENOSYS from chmod/chown
+* clarify that graceful-fs must be used as a drop-in
+
+### v2.1.0
+
+* Use eval rather than monkey-patching fs.
+* readdir: Always sort the results
+* win32: requeue a file if error has an OK status
+
+### v2.0
+
+* A return to monkey patching
+* wrap process.cwd
+
+### v1.1
+
+* wrap readFile
+* Wrap fs.writeFile.
+* readdir protection
+* Don't clobber the fs builtin
+* Handle fs.read EAGAIN errors by trying again
+* Expose the curOpen counter
+* No-op lchown/lchmod if not implemented
+* fs.rename patch only for win32
+* Patch fs.rename to handle AV software on Windows
+* Close #4 Chown should not fail on einval or eperm if non-root
+* Fix isaacs/fstream#1 Only wrap fs one time
+* Fix #3 Start at 1024 max files, then back off on EMFILE
+* lutimes that doens't blow up on Linux
+* A full on-rewrite using a queue instead of just swallowing the EMFILE error
+* Wrap Read/Write streams as well
+
+### 1.0
+
+* Update engines for node 0.6
+* Be lstat-graceful on Windows
+* first

package/node_modules/graceful-fs/clone.js

@@ -0,0 +1,23 @@
+'use strict'
+
+module.exports = clone
+
+var getPrototypeOf = Object.getPrototypeOf || function (obj) {
+  return obj.__proto__
+}
+
+function clone (obj) {
+  if (obj === null || typeof obj !== 'object')
+    return obj
+
+  if (obj instanceof Object)
+    var copy = { __proto__: getPrototypeOf(obj) }
+  else
+    var copy = Object.create(null)
+
+  Object.getOwnPropertyNames(obj).forEach(function (key) {
+    Object.defineProperty(copy, key, Object.getOwnPropertyDescriptor(obj, key))
+  })
+
+  return copy
+}