taskchef 5.12.0 → 6.1.0

package/src/mcp.js

@@ -2,9 +2,9 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import {
   prepareDispatch,
+  linkTask,
   recordTask,
   reportTaskResult,
-  resolveTask,
 } from "./workspace.js";
 import { parseTaskChefMarker } from "./delegation.js";
 import { resolveWorkspacePath } from "./workspace-path.js";
@@ -54,13 +54,13 @@ export function createTaskChefMcpServer({
   prepare = prepareDispatch,
   record = recordTask,
   reportResult = reportTaskResult,
-  resolve = resolveTask,
+  link = linkTask,
 } = {}) {
   const server = new McpServer(
     { name: "taskchef", version: "1.0.0" },
     {
       instructions:
-        "Prepare with prepare_dispatch, call record_task before creating the Codex task, then create it natively. Use resolve_task for a durable root thread ID. Executors must call report_result before ending with completed, needs_input, or failed.",
+        "Prepare with prepare_dispatch, call record_task before creating the Codex task, then create it natively and return immediately. The executor must call link_task before other work and report_result before ending.",
     },
   );
 
@@ -89,13 +89,13 @@ export function createTaskChefMcpServer({
     {
       title: "Record TaskChef task",
       description:
-        "Atomically append one prepared TaskChef task before creating its Codex executor. Pass the exact marked instruction and use null for threadId until a durable root ID is known.",
+        "Atomically append one prepared TaskChef task before creating its Codex executor. Pass the exact marked instruction and null threadId; only the executor may self-link it.",
       inputSchema: {
         id: z.string().min(1),
         project: z.string().min(1),
         title: z.string().min(1),
         instruction: z.string().min(1),
-        threadId: z.string().min(1).nullable(),
+        threadId: z.null(),
       },
       outputSchema: { task: taskSchema },
       annotations: {
@@ -114,11 +114,11 @@ export function createTaskChefMcpServer({
   );
 
   server.registerTool(
-    "resolve_task",
+    "link_task",
     {
-      title: "Resolve TaskChef task",
+      title: "Link TaskChef executor",
       description:
-        "Atomically fill one recorded TaskChef task's nullable thread ID after exactly one structured marker match. The one-way transition cannot overwrite another durable ID.",
+        "Register this executor's asserted durable Codex thread ID. The atomic one-way transition is idempotent and rejects conflicts or thread reuse.",
       inputSchema: {
         taskId: z.string().min(1),
         threadId: z.string().min(1),
@@ -131,8 +131,8 @@ export function createTaskChefMcpServer({
       },
     },
     async ({ taskId, threadId }) => {
-      const task = await resolve(workspace, taskId, threadId);
-      return toolResult("task", task, `Resolved TaskChef task ${task.id}.`);
+      const task = await link(workspace, taskId, threadId);
+      return toolResult("task", task, `Linked TaskChef task ${task.id}.`);
     },
   );
 

package/src/workspace.js

@@ -20,6 +20,7 @@ import path from "node:path";
 import { promisify } from "node:util";
 import lockfile from "proper-lockfile";
 import {
+  normalizeCodexThreadId,
   normalizeDurableThreadId,
   parseTaskChefMarker,
   taskChefMarker,
@@ -47,7 +48,8 @@ const DISPATCH_FILE_NAME = "tasks.jsonl";
 const WORKSPACE_LOCK_NAME = ".taskchef-workspace.lock";
 const SAFE_ID = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
 const CURRENT_CONFIG_SCHEMA_VERSION = 2;
-const CURRENT_TASK_SCHEMA_VERSION = 3;
+const CURRENT_TASK_SCHEMA_VERSION = 4;
+const PREVIOUS_STATEFUL_TASK_SCHEMA_VERSION = 3;
 const LEGACY_SCHEMA_VERSION = 1;
 const PREVIOUS_SCHEMA_VERSION = 2;
 const CONFIG_FIELDS = new Set(["schemaVersion", "projects"]);
@@ -786,6 +788,7 @@ async function validateDispatchShape(
   const supportedVersions = [
     LEGACY_SCHEMA_VERSION,
     PREVIOUS_SCHEMA_VERSION,
+    PREVIOUS_STATEFUL_TASK_SCHEMA_VERSION,
     CURRENT_TASK_SCHEMA_VERSION,
   ];
   if (!supportedVersions.includes(dispatch?.schemaVersion)) {
@@ -793,7 +796,7 @@ async function validateDispatchShape(
   }
   requireExactFields(
     dispatch,
-    dispatch.schemaVersion === CURRENT_TASK_SCHEMA_VERSION
+    dispatch.schemaVersion >= PREVIOUS_STATEFUL_TASK_SCHEMA_VERSION
       ? DISPATCH_FIELDS
       : LEGACY_DISPATCH_FIELDS,
     name,
@@ -804,7 +807,7 @@ async function validateDispatchShape(
     allowLegacyGithubRepo: dispatch.schemaVersion === LEGACY_SCHEMA_VERSION,
   });
   const normalized = {
-    schemaVersion: CURRENT_TASK_SCHEMA_VERSION,
+    schemaVersion: dispatch.schemaVersion,
     id,
     project,
     title: requireString(dispatch.title, `${name}.title`).trim(),
@@ -813,21 +816,21 @@ async function validateDispatchShape(
       ? null
       : normalizeDurableThreadId(dispatch.threadId, `${name}.threadId`),
     createdAt: requireTimestamp(dispatch.createdAt, `${name}.createdAt`),
-    status: dispatch.schemaVersion === CURRENT_TASK_SCHEMA_VERSION
+    status: dispatch.schemaVersion >= PREVIOUS_STATEFUL_TASK_SCHEMA_VERSION
       ? requireEnum(dispatch.status, TASK_STATUSES, `${name}.status`)
       : null,
-    summary: dispatch.schemaVersion === CURRENT_TASK_SCHEMA_VERSION
+    summary: dispatch.schemaVersion >= PREVIOUS_STATEFUL_TASK_SCHEMA_VERSION
       ? optionalString(dispatch.summary, `${name}.summary`, {
         maxLength: MAX_RESULT_SUMMARY_LENGTH,
       })
       : null,
-    turnId: dispatch.schemaVersion === CURRENT_TASK_SCHEMA_VERSION
+    turnId: dispatch.schemaVersion >= PREVIOUS_STATEFUL_TASK_SCHEMA_VERSION
       ? optionalString(dispatch.turnId, `${name}.turnId`, { maxLength: 256 })
       : null,
-    updatedAt: dispatch.schemaVersion === CURRENT_TASK_SCHEMA_VERSION
+    updatedAt: dispatch.schemaVersion >= PREVIOUS_STATEFUL_TASK_SCHEMA_VERSION
       ? requireTimestamp(dispatch.updatedAt, `${name}.updatedAt`)
       : null,
-    updatedBy: dispatch.schemaVersion === CURRENT_TASK_SCHEMA_VERSION
+    updatedBy: dispatch.schemaVersion >= PREVIOUS_STATEFUL_TASK_SCHEMA_VERSION
       ? requireEnum(dispatch.updatedBy, TASK_UPDATE_SOURCES, `${name}.updatedBy`)
       : null,
   };
@@ -881,15 +884,24 @@ async function parseDispatchRecordsUnlocked(root, content) {
   const threadIds = new Set();
   for (const { normalized: dispatch } of records) {
     if (ids.has(dispatch.id)) throw new Error(`duplicate task ID: ${dispatch.id}`);
-    if (dispatch.threadId !== null && threadIds.has(dispatch.threadId)) {
+    const threadKey = dispatch.threadId === null ? null : threadIdentityKey(dispatch.threadId);
+    if (threadKey !== null && threadIds.has(threadKey)) {
       throw new Error(`duplicate task threadId: ${dispatch.threadId}`);
     }
     ids.add(dispatch.id);
-    if (dispatch.threadId !== null) threadIds.add(dispatch.threadId);
+    if (threadKey !== null) threadIds.add(threadKey);
   }
   return records;
 }
 
+function threadIdentityKey(threadId) {
+  try {
+    return `codex:${normalizeCodexThreadId(threadId)}`;
+  } catch {
+    return `opaque:${threadId}`;
+  }
+}
+
 async function readDispatchRecordsUnlocked(root) {
   const filePath = path.join(root, DISPATCH_FILE_NAME);
   if (!(await managedRegularFileExists(filePath))) {
@@ -942,10 +954,19 @@ export async function recordTask(workspaceRoot, input, { now } = {}) {
     }
     if (
       dispatch.threadId !== null &&
-      existing.some((item) => item.threadId === dispatch.threadId)
+      existing.some((item) => (
+        item.threadId !== null
+        && threadIdentityKey(item.threadId) === threadIdentityKey(dispatch.threadId)
+      ))
     ) {
       throw new Error(`threadId is already recorded: ${dispatch.threadId}`);
     }
+    if (
+      dispatch.threadId !== null
+      && parseTaskChefMarker(dispatch.instruction) === dispatch.id
+    ) {
+      throw new Error("a marked self-linking task must be recorded with threadId: null");
+    }
     await appendDispatchesAtomic(root, [dispatch]);
     return dispatch;
   });
@@ -960,6 +981,10 @@ export async function resolveTask(workspaceRoot, taskId, threadId, { now } = {})
     const dispatches = records.map((record) => record.normalized);
     const index = dispatches.findIndex((dispatch) => dispatch.id === id);
     if (index === -1) throw new Error(`task not found: ${id}`);
+    const currentRecord = records[index];
+    if (currentRecord.raw.schemaVersion >= CURRENT_TASK_SCHEMA_VERSION) {
+      throw new Error(`task resolve is only available for legacy pre-self-linking records: ${id}`);
+    }
     const dispatch = dispatches[index];
     if (dispatch.threadId === durableThreadId) return dispatch;
     if (dispatch.threadId !== null) {
@@ -968,86 +993,101 @@ export async function resolveTask(workspaceRoot, taskId, threadId, { now } = {})
     if (parseTaskChefMarker(dispatch.instruction) !== dispatch.id) {
       throw new Error(`task instruction does not contain its exact TaskChef marker: ${id}`);
     }
-    if (dispatches.some((item) => item.threadId === durableThreadId)) {
+    if (dispatches.some((item) => (
+      item.threadId !== null
+      && threadIdentityKey(item.threadId) === threadIdentityKey(durableThreadId)
+    ))) {
       throw new Error(`threadId is already recorded: ${durableThreadId}`);
     }
-    const currentRecord = records[index];
-    const resolved = currentRecord.raw.schemaVersion === CURRENT_TASK_SCHEMA_VERSION
-      ? await validateDispatchShape({
-        ...dispatch,
+    const statefulLegacy = currentRecord.raw.schemaVersion === PREVIOUS_STATEFUL_TASK_SCHEMA_VERSION;
+    const rawResolved = statefulLegacy
+      ? {
+        ...currentRecord.raw,
         threadId: durableThreadId,
         updatedAt: now ?? new Date().toISOString(),
         updatedBy: "dispatcher",
-      })
+      }
+      : { ...currentRecord.raw, threadId: durableThreadId };
+    const resolved = statefulLegacy
+      ? await validateDispatchShape(rawResolved)
       : { ...dispatch, threadId: durableThreadId };
     const lines = records.map((record, recordIndex) => recordIndex === index
-      ? currentRecord.raw.schemaVersion === CURRENT_TASK_SCHEMA_VERSION
-        ? dispatchLineWithState(resolved, {})
-        : JSON.stringify({ ...record.raw, threadId: durableThreadId })
+      ? JSON.stringify(rawResolved)
       : record.line);
     await writeDispatchLinesAtomic(root, lines);
     return resolved;
   });
 }
 
-function dispatchLineWithState(dispatch, patch) {
-  return JSON.stringify({
-    ...dispatch,
-    schemaVersion: CURRENT_TASK_SCHEMA_VERSION,
-    ...patch,
-  });
-}
-
-export async function startTaskFromHook(
-  workspaceRoot,
-  taskId,
-  threadId,
-  turnId,
-  { now } = {},
-) {
+export async function linkTask(workspaceRoot, taskId, threadId, { now } = {}) {
   const id = requireSafeId(taskId, "taskId");
-  const durableThreadId = normalizeDurableThreadId(threadId);
-  const currentTurnId = optionalString(turnId, "turnId", { maxLength: 256 });
+  const durableThreadId = normalizeCodexThreadId(threadId);
   const root = await realpath(path.resolve(workspaceRoot));
   return withWorkspaceLock(root, async () => {
     const records = await readDispatchRecordsUnlocked(root);
     const dispatches = records.map((record) => record.normalized);
     const index = dispatches.findIndex((dispatch) => dispatch.id === id);
     if (index === -1) throw new Error(`task not found: ${id}`);
+    const currentRecord = records[index];
+    if (currentRecord.raw.schemaVersion < CURRENT_TASK_SCHEMA_VERSION) {
+      throw new Error(`link_task accepts only self-linking task records: ${id}`);
+    }
     const dispatch = dispatches[index];
-    if (parseTaskChefMarker(dispatch.instruction) !== dispatch.id) {
-      throw new Error(`task instruction does not contain its exact TaskChef marker: ${id}`);
+    const sameIdentity = dispatch.threadId?.toLowerCase() === durableThreadId;
+    if (sameIdentity && dispatch.updatedBy === "mcp") {
+      if (parseTaskChefMarker(dispatch.instruction) !== dispatch.id) {
+        throw new Error(`task instruction does not contain its exact TaskChef marker: ${id}`);
+      }
+      if (dispatch.threadId === durableThreadId) return dispatch;
+      const canonical = await validateDispatchShape({
+        ...dispatch,
+        threadId: durableThreadId,
+        updatedAt: now ?? new Date().toISOString(),
+        updatedBy: "mcp",
+      });
+      const lines = records.map((record, recordIndex) => recordIndex === index
+        ? dispatchLineWithState(canonical, {})
+        : record.line);
+      await writeDispatchLinesAtomic(root, lines);
+      return canonical;
     }
-    if (dispatch.threadId !== null && dispatch.threadId !== durableThreadId) {
+    if (dispatch.threadId !== null && dispatch.updatedBy === "mcp") {
       throw new Error(`task already has a different threadId: ${id}`);
     }
     if (
-      dispatch.threadId === null
-      && dispatches.some((item) => item.id !== id && item.threadId === durableThreadId)
+      dispatch.threadId !== null
+      || dispatch.status !== "working"
+      || dispatch.updatedBy !== "dispatcher"
     ) {
-      throw new Error(`threadId is already recorded: ${durableThreadId}`);
+      throw new Error(`task is not an eligible link-pending dispatcher record: ${id}`);
     }
-    if (dispatch.threadId === durableThreadId && dispatch.updatedBy === "mcp") {
-      return dispatch;
+    if (parseTaskChefMarker(dispatch.instruction) !== dispatch.id) {
+      throw new Error(`task instruction does not contain its exact TaskChef marker: ${id}`);
     }
-    if (dispatch.threadId === durableThreadId && dispatch.updatedBy === "hook") {
-      return dispatch;
+    if (dispatches.some((item) => (
+      item.id !== id && item.threadId?.toLowerCase() === durableThreadId
+    ))) {
+      throw new Error(`threadId is already recorded: ${durableThreadId}`);
     }
-    const updatedAt = now ?? new Date().toISOString();
-    const started = await validateDispatchShape({
+    const linked = await validateDispatchShape({
       ...dispatch,
       threadId: durableThreadId,
-      status: "working",
-      summary: null,
-      turnId: currentTurnId,
-      updatedAt,
-      updatedBy: "hook",
+      updatedAt: now ?? new Date().toISOString(),
+      updatedBy: "mcp",
     });
     const lines = records.map((record, recordIndex) => recordIndex === index
-      ? dispatchLineWithState(started, {})
+      ? dispatchLineWithState(linked, {})
       : record.line);
     await writeDispatchLinesAtomic(root, lines);
-    return started;
+    return linked;
+  });
+}
+
+function dispatchLineWithState(dispatch, patch) {
+  return JSON.stringify({
+    ...dispatch,
+    schemaVersion: CURRENT_TASK_SCHEMA_VERSION,
+    ...patch,
   });
 }
 
@@ -1074,28 +1114,55 @@ export async function reportTaskResult(workspaceRoot, input, { now } = {}) {
     const index = dispatches.findIndex((dispatch) => dispatch.id === id);
     if (index === -1) throw new Error(`task not found: ${id}`);
     const dispatch = dispatches[index];
+    const isSelfLinkingJourney = (
+      records[index].raw.schemaVersion >= CURRENT_TASK_SCHEMA_VERSION
+      && dispatch.threadId !== null
+      && parseTaskChefMarker(dispatch.instruction) === dispatch.id
+    );
+    let resultTurnId = turnId;
+    if (isSelfLinkingJourney) {
+      if (dispatch.updatedBy === "dispatcher") {
+        throw new Error(`self-linking task must link before reporting a result: ${id}`);
+      }
+      resultTurnId = normalizeCodexThreadId(turnId, "turnId");
+    }
     if (dispatch.threadId === null) {
-      if (threadId !== null || turnId !== null || status !== "failed") {
+      if (threadId !== null || resultTurnId !== null || status !== "failed") {
         throw new Error(`task without a durable threadId accepts only failed with null thread/turn IDs: ${id}`);
       }
     } else {
-      if (threadId !== dispatch.threadId) {
+      if (threadIdentityKey(threadId) !== threadIdentityKey(dispatch.threadId)) {
         throw new Error(`task result threadId does not match recorded threadId: ${id}`);
       }
-      if (turnId === null) {
+      if (resultTurnId === null) {
         throw new Error(`task result turnId is required for a linked task: ${id}`);
       }
     }
+    if (dispatch.updatedBy === "mcp" && resultTurnId === dispatch.turnId) {
+      if (status === dispatch.status && summary === dispatch.summary) return dispatch;
+      throw new Error(`task turn already has a different semantic result: ${id}`);
+    }
+    if (
+      isSelfLinkingJourney
+      && dispatch.turnId !== null
+      && resultTurnId <= dispatch.turnId
+    ) {
+      throw new Error(`task result turnId must be newer than the stored turnId: ${id}`);
+    }
+    const persistedSchemaVersion = records[index].raw.schemaVersion >= CURRENT_TASK_SCHEMA_VERSION
+      ? CURRENT_TASK_SCHEMA_VERSION
+      : PREVIOUS_STATEFUL_TASK_SCHEMA_VERSION;
     const updated = await validateDispatchShape({
       ...dispatch,
+      schemaVersion: persistedSchemaVersion,
       status,
       summary,
-      turnId,
+      turnId: resultTurnId,
       updatedAt: now ?? new Date().toISOString(),
       updatedBy: "mcp",
     });
     const lines = records.map((record, recordIndex) => recordIndex === index
-      ? dispatchLineWithState(updated, {})
+      ? dispatchLineWithState(updated, { schemaVersion: persistedSchemaVersion })
       : record.line);
     await writeDispatchLinesAtomic(root, lines);
     return updated;

package/hooks/hooks.json

@@ -1,18 +0,0 @@
-{
-  "description": "Link TaskChef executor identity and provide the current callback turn.",
-  "hooks": {
-    "UserPromptSubmit": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node \"$PLUGIN_ROOT/hooks/taskchef-initial-prompt.js\"",
-            "commandWindows": "node \"%PLUGIN_ROOT%\\hooks\\taskchef-initial-prompt.js\"",
-            "timeout": 40,
-            "statusMessage": "Linking TaskChef task"
-          }
-        ]
-      }
-    ]
-  }
-}

package/hooks/taskchef-initial-prompt.js

@@ -1,17 +0,0 @@
-#!/usr/bin/env node
-
-import { handleInitialPromptHook } from "../src/hook.js";
-
-let raw = "";
-process.stdin.setEncoding("utf8");
-for await (const chunk of process.stdin) raw += chunk;
-
-try {
-  const input = JSON.parse(raw);
-  process.stdout.write(`${JSON.stringify(await handleInitialPromptHook(input))}\n`);
-} catch (error) {
-  process.stdout.write(`${JSON.stringify({
-    continue: true,
-    systemMessage: `TaskChef initial identity hook failed: ${error instanceof Error ? error.message : String(error)}`,
-  })}\n`);
-}

package/src/hook.js

@@ -1,96 +0,0 @@
-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()
-    : null;
-}
-
-function hookContext(taskId, threadId, turnId) {
-  return {
-    continue: true,
-    hookSpecificOutput: {
-      hookEventName: "UserPromptSubmit",
-      additionalContext: [
-        `This is TaskChef task ${taskId} in root thread ${threadId}, current turn ${turnId}.`,
-        "Before ending the task, call the TaskChef report_result MCP tool with the semantic outcome needs_input, completed, or failed and a concise summary.",
-        "Pass this exact task ID, root thread ID, and current turn ID to report_result.",
-        "Use needs_input only for a decision or information the user must provide; native approval prompts are reported from live Codex state.",
-        "Do not include secrets, transcripts, or raw command output in the summary.",
-      ].join(" "),
-    },
-  };
-}
-
-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 (turnId === null || (taskId === null && threadId === null)) {
-    if (taskId === null) return { continue: true };
-    return {
-      continue: true,
-      systemMessage: "TaskChef could not prepare this initial task because the hook payload lacked a turn ID.",
-    };
-  }
-  if (taskId !== null) {
-    const root = workspace ?? resolveWorkspace();
-    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 {
-    const root = workspace ?? resolveWorkspace();
-    const task = (await listTaskSnapshots(root)).find((item) => item.threadId === threadId);
-    return task === undefined
-      ? { continue: true }
-      : hookContext(task.id, threadId, turnId);
-  } catch {
-    // An unrelated prompt must not surface TaskChef workspace setup failures.
-    return { continue: true };
-  }
-}