taskchef 3.0.2 → 4.0.0

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "taskchef",
-  "version": "3.0.2",
+  "version": "4.0.0",
   "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

@@ -73,11 +73,13 @@ tasks.jsonl
 TaskChef scans eligible local Codex projects during setup and adds them to the
 managed project list in `taskchef.json`.
 
-`taskchef.json` defines the available routes. A project name or GitHub pull
-request URL in your request is usually enough for TaskChef to choose the right
-project. If a project needs more context, extend its optional `description`
-field with responsibilities and keywords that distinguish it from nearby
-projects.
+`taskchef.json` defines the available routes. A project name or GitHub issue or
+pull-request URL in your request is usually enough for TaskChef to choose the
+right project. Each project's `githubRepos` field is a list. A managed
+`*-workspace` project lists all child or sub-repositories there, so links into
+any of them route to the workspace. If a project needs more context, extend its
+optional `description` field with responsibilities and keywords that
+distinguish it from nearby projects.
 
 The generated `AGENTS.md` turns ordinary requests in this project into
 delegated work. You do not need to name the delegate skill each time.
@@ -117,9 +119,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
 
@@ -152,7 +163,8 @@ $taskchef-bootstrap Diagnose this TaskChef workspace and fix any repairable conf
 Project paths must exist when you add or dispatch to them. Configure the
 repository root for a Git project. TaskChef also accepts non-Git folders. It
 detects Git status and the canonical GitHub `origin` when adding or importing
-a project.
+a project. Repeat `--github-repo` to configure several repositories, or place a
+`githubRepos` array in an import. URLs are canonicalized and deduplicated.
 
 Removing a project does not rewrite old task entries. Each entry keeps the
 project metadata that TaskChef used when it delegated the work.
@@ -161,8 +173,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 +226,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
@@ -231,6 +245,8 @@ taskchef doctor --workspace <workspace>
 taskchef project add /workspace/payments \
   --name payments \
   --description "Owns payment authorization, capture, and refunds." \
+  --github-repo https://github.com/example/payments-api \
+  --github-repo https://github.com/example/payments-sdk \
   --workspace <workspace>
 
 taskchef project list --workspace <workspace>
@@ -244,20 +260,36 @@ taskchef project import projects.json --workspace <workspace>
 taskchef project import - --workspace <workspace> < projects.json
 ```
 
-Import merges by canonical path and preserves an existing name or description
-when the imported object omits it. `--replace` replaces the configured project
-set.
+Import merges by canonical path, preserves an existing name or description
+when the imported object omits it, and unions repository lists without
+duplicates. `--replace` replaces the configured project set.
+
+The current configuration schema is version 2. Version 1 remains readable:
+legacy `githubRepo: null` normalizes to `githubRepos: []`, and a legacy string
+normalizes to a one-item `githubRepos` list. `workspace init` persists this
+migration atomically; other configuration writes also emit version 2. Legacy
+task lines remain readable without an eager rewrite of the append-only history.
 
 ### 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
@@ -55,20 +54,23 @@ the workspace.
 
 ```json
 {
-  "schemaVersion": 1,
+  "schemaVersion": 2,
   "projects": [
     {
       "name": "payments-api",
       "path": "/workspace/payments-api",
       "isGitRepository": true,
-      "githubRepo": "https://github.com/example/payments-api",
+      "githubRepos": [
+        "https://github.com/example/payments-api",
+        "https://github.com/example/payments-sdk"
+      ],
       "description": "Owns payment authorization, capture, refunds, and provider integrations."
     },
     {
       "name": "local-data-tools",
       "path": "/workspace/local-data-tools",
       "isGitRepository": false,
-      "githubRepo": null
+      "githubRepos": []
     }
   ]
 }
@@ -80,18 +82,31 @@ the workspace.
 - `path` is the normalized, canonical local directory. A Git project must use
   its repository root.
 - `isGitRepository` identifies Git and non-Git projects.
-- `githubRepo` is a canonical GitHub repository URL or `null`.
+- `githubRepos` is a deduplicated list of canonical GitHub repository URLs. Use
+  `[]` when the project advertises no repositories. A managed `*-workspace`
+  project lists each child or sub-repository that should route to it.
 - `description` is optional routing context.
 
-TaskChef classifies work against `name`, `githubRepo`, and `description`. The
-path identifies the checkout but is not a routing hint. TaskChef asks the user
-when metadata does not produce one clear match.
+TaskChef classifies work against `name`, every URL in `githubRepos`, and
+`description`. The path identifies the checkout but is not a routing hint. For
+a GitHub issue or pull-request URL, TaskChef compares canonical,
+case-insensitive owner/repository identities across every configured list. It
+ignores the issue or PR suffix, `http` versus `https`, optional `www`, trailing
+slashes, and trailing `.git`. It routes only when one configured project
+matches; ambiguous and unmatched URLs are never guessed.
 
 `project add` and `project import` detect Git status, exact Git roots, and
-canonical GitHub origins. Import merges by canonical path and preserves an
-existing name or description when omitted. `--replace` replaces the configured
-set. Removing or replacing a project does not alter historical task
-entries.
+canonical GitHub origins. `--github-repo` is repeatable. Import merges by
+canonical path, preserves an existing name or description when omitted, and
+unions existing and imported repository lists without duplicates. `--replace`
+replaces the configured set. Removing or replacing a project does not alter
+historical task entries.
+
+Schema version 2 replaces the string-or-null `githubRepo` field with the
+list-valued `githubRepos` field. Schema-version-1 configurations remain
+compatible: reads normalize a legacy string to one canonical list item and
+legacy `null` to `[]`; `workspace init` persists the migration atomically, and
+any later configuration write emits version 2.
 
 The configuration does not store dispatcher identity, execution modes,
 schedules, task status, results, host information, or the workspace path.
@@ -101,36 +116,81 @@ 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":2,"id":"c0f010ff-84f2-4838-a69d-0ff1f5d721d7","project":{"name":"payments-api","path":"/workspace/payments-api","isGitRepository":true,"githubRepos":["https://github.com/example/payments-api","https://github.com/example/payments-sdk"],"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,
 hidden reasoning, `hostId`, or update timestamps.
 
+New task entries use schema version 2 and list-valued project snapshots.
+Version 1 entries with string or null repository metadata remain readable and
+normalize to version 2 in API and CLI output. TaskChef does not eagerly rewrite
+legacy history solely for this migration.
+
 ## Dispatch workflow
 
 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 +204,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 +234,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/assets/taskchef-dispatcher-instructions.md

@@ -9,6 +9,8 @@ This repository is a TaskChef dispatcher workspace.
 - For every actionable work request, use `$taskchef-delegate`
   automatically, even when the user does not explicitly say "delegate" or
   mention TaskChef.
+- GitHub issue and pull-request URLs may identify any repository advertised by
+  a configured project, including child repositories of managed workspaces.
 - Do not perform delegated work directly in the dispatcher thread.
 - Return immediately after dispatch, as required by `$taskchef-delegate`.
 - Answer directly only when the user explicitly asks about TaskChef itself or

package/index.js

@@ -14,7 +14,31 @@ export {
   listTasks,
   readTask,
   recordTask,
+  resolveTask,
   requireSafeId,
   removeProject,
   validateConfig,
 } from "./src/workspace.js";
+
+export {
+  canonicalGithubRepository,
+  matchProjectForGithubUrl,
+  normalizeGithubRepositories,
+} from "./src/github.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/package.json

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

package/skills/taskchef-bootstrap/SKILL.md

@@ -24,9 +24,8 @@ all deterministic workspace operations.
 
 1. Run `workspace init --json`. It takes no stdin, creates an empty
    configuration when missing, creates the append-only task log, refreshes
-   managed instructions, and migrates legacy task records that have executor
-   thread IDs. The installed plugin provides all three TaskChef skills outside
-   the dispatcher workspace.
+   managed instructions, and removes legacy TaskChef skill links. The installed
+   plugin provides all three TaskChef skills outside the dispatcher workspace.
 2. Run `doctor --json` after setup or when the user asks to diagnose the
    workspace. Doctor is read-only. Rerun `workspace init --json` to repair the
    managed scaffold.
@@ -40,12 +39,34 @@ all deterministic workspace operations.
    projects are outside the v1 contract.
 2. Add one project with `project add <path>`, normally supplying `--name` and a
    curated `--description`. The CLI detects Git status, exact Git root, and a
-   canonical GitHub `origin`. Use `--no-github` or `--github-repo` only to
-   override detection.
+   canonical GitHub `origin`. Repeat `--github-repo <url>` to advertise several
+   repositories, or use `--no-github` for an empty list. A managed
+   `*-workspace` project must list all of its child or sub-repositories so issue
+   and pull-request URLs route to that workspace.
 3. Bulk import with `project import <file|-> --json`. Input is a JSON array of
    objects containing `path` plus optional `name`, `description`, and
-   `githubRepo`. Import merges by canonical path and preserves an existing name
-   or description when omitted. Use `--replace` only when the user explicitly
-   requests replacement.
+   `githubRepos`, which is always a JSON array of GitHub repository URLs. Import
+   merges by canonical path, preserves an existing name or description when
+   omitted, and unions existing and imported repository lists without
+   duplicates. Use `--replace` only when the user explicitly requests
+   replacement.
 4. Inspect configured projects with `project list --json`. Remove by name with
    `project remove`. Existing task entries keep their project snapshots.
+
+Example managed-workspace import entry:
+
+```json
+{
+  "name": "skills-workspace",
+  "path": "/workspace/skills-workspace",
+  "githubRepos": [
+    "https://github.com/example/skill-one",
+    "https://github.com/example/skill-two"
+  ],
+  "description": "Manages the listed child skill repositories."
+}
+```
+
+`workspace init` safely migrates schema-version-1 configuration: a string
+`githubRepo` becomes a one-item `githubRepos` list and `null` becomes
+`githubRepos: []`. All subsequent configuration writes use schema version 2.

package/skills/taskchef-delegate/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: taskchef-delegate
-description: "Dispatch actionable requests from an initialized TaskChef workspace into independently openable Codex project tasks. Use for ordinary work requests in a TaskChef workspace, explicit delegation, or splitting independent work across projects. Record successful dispatches, return immediately, and never use subagents, hooks, schedules, or foreground waiting."
+description: "Dispatch actionable requests from an initialized TaskChef workspace into independently openable Codex project tasks. Use for ordinary work requests in a TaskChef workspace, explicit delegation, or splitting independent work across projects. Preserve unresolved delegations for later marker-based recovery, and never use subagents, hooks, schedules, daemons, or executor-completion waiting."
 ---
 
 # TaskChef Delegate
@@ -17,7 +17,10 @@ for all deterministic workspace and task-record operations.
 - Keep only `AGENTS.md`, `taskchef.json`, and `tasks.jsonl` in a dispatcher
   workspace.
 - Use real Codex tasks, never collaboration or subagent tools.
-- Never use hooks, callbacks, schedules, polling, or daemons.
+- Never use hooks, callbacks, schedules, daemons, indefinite polling, or
+  background monitors.
+- Use only bounded provisional-ID resolution after `create_thread` returns a
+  provisional client ID. Prefer a native Codex wait or resolver when available.
 - Never wait for delegated work after executor creation.
 - Never collect transcripts or hidden reasoning.
 
@@ -29,20 +32,88 @@ for all deterministic workspace and task-record operations.
    `$taskchef-bootstrap` if the workspace is missing or unhealthy.
 2. Split the request into the smallest independently useful outcomes. Include
    constraints, expected testing, and reporting in every instruction.
-3. Classify against configured `name`, `githubRepo`, and `description`. Use
-   `path` only as checkout identity. Ask when metadata does not produce one
-   clear project match.
+3. Classify against configured `name`, every URL in the `githubRepos` list, and
+   `description`. Use `path` only as checkout identity. Managed `*-workspace`
+   projects advertise their child or sub-repositories in this list.
+   When the prompt contains a GitHub issue or pull-request URL, canonicalize
+   its case-insensitive owner/repository identity, ignoring `http` versus
+   `https`, an optional `www`, a trailing slash or `.git`, and the issue or PR
+   suffix. Check that identity against every repository URL of every configured
+   project. Route on this evidence only when exactly one configured project
+   matches. Ask instead of guessing when no project or several projects match.
 4. Resolve native projects once and require the exact configured path.
-5. Create one real Codex task per assignment using the exact configured project
-   and a local environment on its executor host. Generate a unique task ID
-   before creation, but do not write anything yet.
-6. After executor creation returns a thread ID, immediately run
+5. Generate a lowercase full UUID task ID before creation. Prefix the complete
+   executor instruction with exactly `# taskchef_id=<full UUID>`, followed by a
+   blank line and the instruction body. Preserve this marked instruction for
+   recording, and note the creation time. Do not take a pre-creation thread
+   snapshot; the exact random marker is the correlation key.
+6. Create one real Codex task using the exact configured project, a local
+   environment on its executor host, the marked instruction, and a short title.
+7. When `create_thread` returns a durable `threadId`, immediately run
    `<plugin-root>/bin/taskchef.js task record --json --workspace <workspace>`.
    Send exactly `id`, `project`, `title`, `instruction`, and `threadId` as JSON
-   on stdin. Use the configured project path for `project`. Never persist
-   `hostId`, status, results, transcripts, or hidden reasoning.
-7. If executor creation fails, do not record a task. If recording fails
+   on stdin. Use the configured project path for `project`, and send the marked
+   instruction unchanged. Never persist a provisional `clientThreadId` or
+   `pendingWorktreeId` as `threadId`. Never persist `hostId`, status, results,
+   transcripts, or hidden reasoning.
+8. When creation returns only `clientThreadId` or `pendingWorktreeId`, keep it
+   only for the created-thread directive and diagnostic reporting. It is not a
+   durable ID and cannot be passed to thread tools or converted directly.
+   Immediately record the marked instruction with `threadId: null` using the
+   command from step 7, then resolve the durable ID with this bounded workflow:
+
+   - If the current Codex tool surface provides a dedicated operation that
+     accepts the provisional ID and waits for or resolves its durable thread
+     ID, call it exactly once with a timeout of at most 30 seconds. Do not invent
+     an operation or pass the provisional ID to tools that require `threadId`.
+   - When no native operation is available, take at most two `list_threads`
+     snapshots with limit 50, near 10 and 30 seconds after the provisional
+     result. Count tool latency against the 30-second deadline. Do not start a
+     snapshot, candidate read, marker verification, or task-resolution write
+     after it.
+   - Filter Codex candidates by the expected host, project, creation time
+     (allow five seconds of clock skew), and worktree environment whenever
+     those fields are present. Use the title only to prioritize reads; Codex
+     may normalize it, so never exclude a candidate because its title differs.
+   - Read every remaining candidate with `read_thread`, requesting one turn and
+     no command output. Read candidates concurrently when the tool surface
+     permits. Inspect only the structured
+     `userMessage.content[].codexDelegation.input`; do not trust titles,
+     summaries, previews, plain-text echoes, or assistant output as proof.
+   - Accept a candidate only when the structured input's first line is exactly
+     the task's `# taskchef_id=<full UUID>` marker and exactly one candidate
+     matches. Apply the same marker verification to a thread ID returned by a
+     native resolver. Reject any returned or discovered thread ID equal to the
+     provisional identifier or in its `local:` namespace. Then use
+     the task-resolution command under **Later resolution** to atomically fill
+     the nullable field.
+   - Treat native-resolution, snapshot, candidate-read, wait, and task-resolution
+     failures as indeterminate. If the workflow ends with zero exact matches,
+     multiple matches, or errors, leave the already-recorded `threadId: null`,
+     clearly report the unresolved reason and provisional diagnostic ID, and
+     never guess.
+
+9. If executor creation fails, do not record a task. If recording fails
    after creation, still return the created task and clearly say that it is not
    in the task log. Do not delete the executor.
-8. Return immediately with a created-thread directive for every success. Do
-   not read or wait for a newly created executor.
+10. Return immediately after immediate recording or the bounded ID-resolution
+    workflow. Emit the appropriate created-thread directive, but label a
+    client-thread directive as provisional when resolution failed. Treat a
+    nullable record as preserved but unresolved, not as a durable task link. Do
+    not read an executor for progress and never wait for executor work
+    completion.
+
+The package exports pure repository canonicalization and unique URL matching
+helpers from `src/github.js`, plus marker, candidate-filtering, and
+injected-adapter orchestration helpers from `src/delegation.js`, for
+deterministic tests and hosts that can supply thread-tool callbacks. The
+standalone Node CLI cannot call desktop thread tools; perform the tool calls in
+Codex and use the CLI only for validated workspace data operations.
+
+## Later resolution
+
+When a later Codex workflow finds exactly one durable thread whose structured
+delegated input contains an unresolved task's exact marker, run
+`<plugin-root>/bin/taskchef.js task resolve <task-id> --thread-id <thread-id> --json --workspace <workspace>`.
+Never edit `tasks.jsonl` directly. The CLI permits only an idempotent one-way
+transition from `threadId: null` to one unique durable thread ID.