taskchef 5.11.0 → 5.11.1

package/.codex-plugin/plugin.json

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

package/BACKLOG.md

@@ -50,7 +50,8 @@ clear data model before implementation.
   `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 whether the initial-hook identity link and exact-marker manual
-  recovery can be simplified when Codex exposes one of these APIs. Keep exact
-  correlation verification before persisting the returned durable ID unless
-  the official contract provides equivalent guarantees.
+- Replace bounded exact-marker discovery when Codex exposes one of these APIs.
+  The initial hook intentionally never links from `session_id`, because Codex
+  documents that subagent hooks use the parent session ID. Keep exact
+  correlation verification unless an official contract provides equivalent
+  guarantees.

package/README.md

@@ -140,9 +140,12 @@ Every delegated instruction begins with a unique
 executor-ownership paragraph, a result-callback paragraph, and the assignment. The
 valid HTML comment stays invisible in rendered Markdown.
 TaskChef records the marked delegation before executor creation. If creation
-does not return a durable thread ID, the trusted initial-prompt hook receives
-the root session ID and atomically links it to the existing entry. Delegation
-does not wait, poll, list tasks, or retry discovery.
+does not return a durable thread ID, the dispatcher performs bounded checks at
+10 and 30 seconds and accepts only one recently created task whose structured
+initial input contains the exact marker. The initial-prompt hook may wait for
+that verified link, but never treats its session ID as executor identity:
+subagent hooks can carry the parent session ID. If no unique match appears,
+TaskChef leaves the entry unresolved instead of risking a wrong link.
 
 ### Ask for a live report
 
@@ -433,11 +436,10 @@ printf '%s\n' '{"id":"c0f010ff-84f2-4838-a69d-0ff1f5d721d7","project":"/workspac
   taskchef task record --json
 ```
 
-If a task has `threadId: null`, the initial plugin hook normally resolves its
-exact marker to the root session ID. Direct manual recovery may use the
-equivalent CLI operation below after verifying one exact structured marker
-match. Both hook and CLI reach the same locked atomic logic, which permits only
-the one-way transition from null to one unique thread ID:
+If a task still has `threadId: null` after bounded resolution, direct manual
+recovery may use the CLI operation below after verifying one exact structured
+marker match. The same locked atomic logic permits only the one-way transition
+from null to one unique thread ID:
 
 ```sh
 taskchef task resolve c0f010ff-84f2-4838-a69d-0ff1f5d721d7 \

package/SPEC.md

@@ -22,8 +22,8 @@ latest useful semantic result, not a second lifecycle or event database.
 4. It embeds a generated TaskChef UUID marker, executor-ownership sentence, and
    result-callback instruction, then records the task with `threadId: null`.
 5. It creates an independently openable Codex task. A durable returned ID is
-   resolved immediately; otherwise the initial-prompt hook links the root
-   session ID without polling.
+   resolved immediately; otherwise bounded recent-task checks accept exactly
+   one child whose structured initial input contains the exact marker.
 6. It returns without waiting for executor work to complete.
 7. Executors report `completed`, `needs_input`, or `failed` through MCP. Reports
    filter old terminal entries, use one live metadata snapshot, and read only
@@ -217,15 +217,17 @@ For each assignment, `$taskchef-delegate`:
    before executor creation
 5. creates a real Codex task at the exact configured path
 6. calls `resolve_task` when creation returns a durable thread ID; otherwise it
-   returns immediately and the initial `UserPromptSubmit` hook resolves the root
-   session ID against the exact marker
+   checks at 10 and 30 seconds and resolves only one recent task whose
+   structured initial input contains the exact marker
 7. records executor-creation failure as a `failed` semantic result on the
    already-existing entry
-8. never lists, reads, waits for, or polls threads during delegation.
+8. returns after the bounded identity check without waiting for executor work.
 
 Recording first closes the creation/hook race. On the exact marked prompt, the
-hook receives the root session ID and initial turn ID and writes only identity
-plus `working`. On later prompts whose session ID matches a recorded executor,
+hook waits for the separately verified canonical identity, then writes only the
+initial turn plus `working`. It never persists the hook `session_id`, because a
+subagent hook can receive its parent's session ID. On later prompts whose
+session ID matches a recorded executor,
 the same `UserPromptSubmit` hook reads the task history and supplies the current
 turn ID as callback context without writing. No permission, tool, stop,
 notification, or session hook writes task lifecycle state. A provisional
@@ -369,7 +371,7 @@ TaskChef does not include:
 2. Project metadata routes an unambiguous request to the correct local project.
 3. A delegation records `working` before creating a visible Codex task.
 4. A durable creation resolves immediately; a provisional creation is linked
-   by the initial exact-marker hook without polling.
+   only after bounded discovery verifies one exact structured-marker match.
 5. The dispatcher returns without waiting for execution.
 6. Several independent assignments can create several entries, including
    multiple entries for the same project.

package/docs/delegation-design.md

@@ -27,8 +27,11 @@ sequenceDiagram
     alt Durable ID returned
         D->>M: resolve_task
     else Provisional ID returned
+        D->>C: Bounded recent-task checks
+        D->>C: Read candidates and verify exact marker
+        D->>M: resolve_task(verified child ID)
         C->>H: Initial UserPromptSubmit
-        H->>W: Resolve root session ID and initial turn
+        H->>W: Wait for verified link; record initial turn
     end
     D-->>U: Return immediately
     C->>M: report_result(needs_input | completed | failed)
@@ -37,8 +40,8 @@ sequenceDiagram
 
 Recording happens before creation. This closes the only important race: when
 the initial hook runs, the exact TaskChef marker already has an entry to update.
-There is no 10/30-second discovery loop, scheduler, daemon, or dispatcher
-wakeup.
+The dispatcher performs only the bounded 10/30-second identity checks. There is
+no scheduler, daemon, indefinite polling, or dispatcher wakeup.
 
 Every executor receives this ownership instruction unchanged:
 
@@ -49,8 +52,8 @@ Every executor receives this ownership instruction unchanged:
 | Writer | Trigger and condition | Fields it owns |
 | --- | --- | --- |
 | Dispatcher via `record_task` | Before executor creation | New entry, `status: working`, null identity/result, server timestamps |
-| Dispatcher via `resolve_task` | Creation immediately returns a durable root ID | `threadId` only |
-| Initial `UserPromptSubmit` hook | Prompt starts with the exact TaskChef marker and the entry exists | `threadId`, initial `turnId`, `status: working`, `updatedAt`, `updatedBy: hook` |
+| Dispatcher via `resolve_task` | Creation returns a durable ID, or bounded discovery verifies one exact-marker child | `threadId` only |
+| Initial `UserPromptSubmit` hook | Prompt starts with the exact TaskChef marker and the verified link exists | Initial `turnId`, `status: working`, `updatedAt`, `updatedBy: hook` |
 | Follow-up `UserPromptSubmit` hook | Session ID exactly matches a recorded executor | Nothing; reads the snapshot and injects the current `turnId` for the MCP callback |
 | Executor via `report_result` | Work has a semantic outcome | `status`, bounded `summary`, result `turnId`, `updatedAt`, `updatedBy: mcp` |
 | Reporter | On explicit report request | Nothing; inferred live state is never persisted |
@@ -147,7 +150,8 @@ provide the stronger check whenever a targeted response is necessary.
 ## Permission and follow-up example
 
 1. Delegation records one `working` entry with null identity.
-2. The initial hook resolves the root thread and initial turn.
+2. The dispatcher verifies and resolves the child thread; the initial hook then
+   records its initial turn without trusting the inherited session ID.
 3. The executor reaches a real product decision and calls `report_result` with
    `needs_input` plus “Approve deployment to production.”
 4. The user opens that executor and approves. The same hook reads the matching
@@ -168,7 +172,7 @@ live task state.
 - lifecycle event types beyond `UserPromptSubmit`
 - fork tracking or result merging
 - SQLite
-- polling, reconciliation schedules, daemons, and dispatcher wakeups
+- indefinite polling, reconciliation schedules, daemons, and dispatcher wakeups
 - durable report watermarks
 - transcript or assistant-prose classification
 - transport-authenticated caller thread/turn identity

package/hooks/hooks.json

@@ -8,7 +8,7 @@
             "type": "command",
             "command": "node \"$PLUGIN_ROOT/hooks/taskchef-initial-prompt.js\"",
             "commandWindows": "node \"%PLUGIN_ROOT%\\hooks\\taskchef-initial-prompt.js\"",
-            "timeout": 10,
+            "timeout": 40,
             "statusMessage": "Linking TaskChef task"
           }
         ]

package/index.js

@@ -70,4 +70,4 @@ export {
 
 export { createTaskChefMcpServer } from "./src/mcp.js";
 
-export { handleInitialPromptHook } from "./src/hook.js";
+export { INITIAL_LINK_CHECKPOINTS_MS, handleInitialPromptHook } from "./src/hook.js";

package/package.json

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

package/skills/taskchef-delegate/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: taskchef-delegate
-description: "Dispatch actionable requests through the per-user TaskChef workspace into independently openable Codex project tasks. Use automatically for actionable work received in the canonical TaskChef dispatcher workspace. From any other project, use only when the user explicitly asks to delegate or split separate work into Codex tasks; TaskChef-related subject matter alone is not delegation intent. Record before creation, rely on the initial TaskChef hook for provisional identity, and never wait for executor completion."
+description: "Dispatch actionable requests through the per-user TaskChef workspace into independently openable Codex project tasks. Use automatically for actionable work received in the canonical TaskChef dispatcher workspace. From any other project, use only when the user explicitly asks to delegate or split separate work into Codex tasks; TaskChef-related subject matter alone is not delegation intent. Record before creation, resolve provisional identity by exact marker within a strict bound, and never wait for executor completion."
 ---
 
 # TaskChef Delegate
@@ -32,11 +32,13 @@ explicitly requested benchmark artifact.
 - Keep only `AGENTS.md`, `taskchef.json`, and `tasks.jsonl` in a dispatcher
   workspace.
 - Use real Codex tasks, never collaboration or subagent tools.
-- Use only TaskChef's `UserPromptSubmit` hook: it resolves initial identity and
-  provides read-only current-turn context on follow-up prompts. Never infer
+- Use only TaskChef's `UserPromptSubmit` hook: after identity is separately
+  verified, it records the initial turn and provides read-only current-turn
+  context on follow-up prompts. Never infer
   lifecycle state from hooks.
-- Never use schedules, daemons, polling, thread-discovery retries, or background
-  monitors.
+- Never use schedules, daemons, background monitors, or indefinite polling.
+  The only permitted thread discovery is the bounded exact-marker resolution
+  after a provisional creation result.
 - Never wait for delegated work after executor creation.
 - Never collect transcripts or hidden reasoning.
 
@@ -88,13 +90,32 @@ explicitly requested benchmark artifact.
    environment on its executor host, the marked instruction, and a short title.
 8. If creation returns a durable `threadId`, call `resolve_task` immediately.
    If creation returns only `clientThreadId`, `pendingWorktreeId`, or a `local:`
-   ID, retain it only for the created-thread directive. Return immediately; the
-   initial TaskChef hook will atomically fill the durable root thread ID. Never
-   list, read, wait for, or poll threads to resolve it.
+   ID, retain it only for the created-thread directive and run this one bounded
+   identity-resolution sequence:
+   - Check immediately, then at 10 and 30 seconds after creation. At each
+     checkpoint, call the native recent-task listing once.
+   - Restrict candidates to Codex tasks created no earlier than five seconds
+     before `preparedAt`, on the returned host and selected project when those
+     fields are available. Prefer the exact title only as an ordering hint.
+   - Read each remaining bounded candidate at most once per checkpoint and
+     accept only the single task whose structured initial
+     `codexDelegation.input` begins with this outcome's exact marker.
+   - Call `resolve_task` only for that one verified durable child ID. Never use
+     `session_id`, a source/parent ID, title similarity, or a provisional ID as
+     identity proof.
+   - Stop at 30 seconds. Zero matches remain unresolved; multiple exact matches
+     are an ambiguity and also remain unresolved. Never guess or continue
+     polling.
+
+   The initial hook may wait for this canonical record transition so it can
+   inject the verified child ID and current turn ID. Codex documents that
+   subagent hooks receive the parent `session_id`, so the hook must never write
+   that field into `threadId`.
 
 9. If executor creation fails, call `report_result` for the already-recorded
    task with `failed`, null thread/turn IDs, and a concise creation error.
-10. Emit the appropriate created-thread directive and return immediately.
+10. Emit the appropriate created-thread directive and return after the bounded
+    identity step.
     Treat a nullable record as preserved but not yet linked. Do not read an
     executor for progress and never wait for executor work completion.
 
@@ -107,17 +128,20 @@ Keep the CLI for bootstrap, manual inspection, and recovery outside delegation.
 
 ## Later resolution
 
-The trusted initial hook normally resolves an unresolved task. For manual
-recovery, require one exact structured marker match, then call `resolve_task`
-once. Never edit `tasks.jsonl` directly. Resolution is an idempotent one-way
-transition from `threadId: null` to one unique durable root thread ID.
+The trusted initial hook never resolves identity from its `session_id`. It uses
+only the child ID already stored by immediate or bounded exact-marker
+resolution. For manual recovery, require one exact structured marker match,
+then call `resolve_task` once. Never edit `tasks.jsonl` directly. Resolution is
+an idempotent one-way transition from `threadId: null` to one unique durable
+child thread ID.
 
 ## Legacy benchmark compatibility
 
 The schema-v1 benchmark fixtures below describe the removed snapshot resolver
 and remain only for historical-result validation. Do not use that resolver for
 new delegation benchmarks. A future benchmark schema should measure record,
-creation, initial-hook resolution, and result callback without polling. The
+creation, bounded exact-marker resolution, and result callback without
+indefinite polling. The
 legacy fixture starts from
 `<plugin-root>/assets/e2e-benchmark-example.json`. Capture one ISO start/end
 interval for the parallel preparation/project-list operation, followed by

package/src/delegation.js

@@ -1,8 +1,7 @@
 import { randomUUID } from "node:crypto";
 
-// Deprecated v5 compatibility exports. TaskChef no longer uses bounded thread
-// discovery, but keeping these pure helpers avoids breaking existing imports
-// before the next major release.
+// Bounded discovery parameters used when Codex returns only a provisional
+// client ID. Candidate content still needs exact-marker verification.
 export const THREAD_RESOLUTION_CHECKPOINTS_MS = Object.freeze([10_000, 30_000]);
 export const THREAD_RESOLUTION_TIMEOUT_MS = 30_000;
 export const THREAD_RESOLUTION_RECENT_LIMIT = 50;
@@ -310,7 +309,7 @@ export async function createAndRecordDelegation(input) {
 
   return {
     status: "recorded-unresolved",
-    reason: "awaiting-initial-hook",
+    reason: "awaiting-bounded-marker-resolution",
     ...prepared,
     threadId: null,
     provisional,

package/src/hook.js

@@ -2,6 +2,10 @@ import { parseTaskChefMarker } from "./delegation.js";
 import { listTasks, startTaskFromHook } from "./workspace.js";
 import { resolveWorkspacePath } from "./workspace-path.js";
 
+// The final hook check trails the dispatcher's 30-second resolver checkpoint
+// so a simultaneous final match is visible before the hook fails closed.
+export const INITIAL_LINK_CHECKPOINTS_MS = Object.freeze([0, 250, 1_000, 3_000, 10_000, 32_000]);
+
 function nonEmptyString(value) {
   return typeof value === "string" && value.trim().length > 0
     ? value.trim()
@@ -24,27 +28,59 @@ function hookContext(taskId, threadId, turnId) {
   };
 }
 
+async function waitForLinkedTask(root, taskId, {
+  checkpoints = INITIAL_LINK_CHECKPOINTS_MS,
+  listTaskSnapshots = listTasks,
+  waitImpl = (delayMs) => new Promise((resolve) => setTimeout(resolve, delayMs)),
+} = {}) {
+  let previousCheckpoint = 0;
+  for (const checkpoint of checkpoints) {
+    if (!Number.isFinite(checkpoint) || checkpoint < previousCheckpoint) {
+      throw new Error("initial-link checkpoints must be finite, non-decreasing milliseconds");
+    }
+    const delay = checkpoint - previousCheckpoint;
+    if (delay > 0) await waitImpl(delay);
+    previousCheckpoint = checkpoint;
+    const task = (await listTaskSnapshots(root)).find((item) => item.id === taskId);
+    if (task?.threadId) return task;
+  }
+  return null;
+}
+
 export async function handleInitialPromptHook(input, {
   workspace = null,
   resolveWorkspace = () => resolveWorkspacePath().workspace,
   startTask = startTaskFromHook,
   listTaskSnapshots = listTasks,
+  linkCheckpoints = INITIAL_LINK_CHECKPOINTS_MS,
+  waitImpl = (delayMs) => new Promise((resolve) => setTimeout(resolve, delayMs)),
 } = {}) {
   if (input?.hook_event_name !== "UserPromptSubmit") return { continue: true };
   const taskId = parseTaskChefMarker(input.prompt);
   const threadId = nonEmptyString(input.session_id);
   const turnId = nonEmptyString(input.turn_id);
-  if (threadId === null || turnId === null) {
+  if (turnId === null || (taskId === null && threadId === null)) {
     if (taskId === null) return { continue: true };
     return {
       continue: true,
-      systemMessage: "TaskChef could not link this initial task because the hook payload lacked a session or turn ID.",
+      systemMessage: "TaskChef could not prepare this initial task because the hook payload lacked a turn ID.",
     };
   }
   if (taskId !== null) {
     const root = workspace ?? resolveWorkspace();
-    await startTask(root, taskId, threadId, turnId);
-    return hookContext(taskId, threadId, turnId);
+    const linked = await waitForLinkedTask(root, taskId, {
+      checkpoints: linkCheckpoints,
+      listTaskSnapshots,
+      waitImpl,
+    });
+    if (linked === null) {
+      return {
+        continue: true,
+        systemMessage: "TaskChef left this task unresolved because its durable child task ID could not be verified. Do not report a semantic result until the recorded identity is repaired.",
+      };
+    }
+    await startTask(root, taskId, linked.threadId, turnId);
+    return hookContext(taskId, linked.threadId, turnId);
   }
 
   try {