taskchef 5.0.1 → 5.1.0

package/.codex-plugin/plugin.json

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

package/BACKLOG.md

@@ -54,3 +54,28 @@ clear data model before implementation.
   one of these APIs. Keep exact marker verification before persisting the
   returned durable ID unless the official contract provides equivalent
   correlation guarantees.
+
+## Structured task recording tool
+
+- Investigate bundling a local stdio MCP server in the TaskChef plugin so Codex
+  can call focused `prepare_dispatch`, `record_task`, and `resolve_task` tools
+  with structured inputs instead of invoking the data CLI through a shell.
+- Reuse the existing `prepareDispatch`, `recordTask`, and `resolveTask` APIs so
+  the MCP layer cannot bypass canonical workspace resolution, exact-field
+  validation, locking, atomic replacement, unique durable-thread correlation,
+  or one-way nullable resolution.
+- Prototype canonical `~/.agents/taskchef` access before committing to this
+  design. Verify how bundled MCP processes interact with Codex filesystem
+  sandboxing and plugin-scoped tool approval on every supported local surface.
+- Keep native Codex task creation outside the MCP server unless Codex exposes a
+  supported task-creation API to plugins. The intended sequence is structured
+  TaskChef preparation, native `create_thread`, then structured TaskChef record
+  and optional resolution.
+- Evaluate tool schemas, approval annotations, failure reporting, installation
+  and upgrade behavior, process lifetime, and latency against the Phase 1 CLI
+  baseline before replacing the CLI path.
+- Relevant official documentation:
+  <https://developers.openai.com/plugins/concepts/plugins>,
+  <https://developers.openai.com/plugins/concepts/mcp-server>,
+  <https://developers.openai.com/plugins/build/mcp-server>, and
+  <https://developers.openai.com/plugins/build/plugins>.

package/README.md

@@ -119,7 +119,9 @@ 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.
+Every delegated instruction begins with a unique
+`<!-- taskchef_id=<UUID> -->` marker followed by a blank line. The valid HTML
+comment stays invisible in rendered Markdown.
 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
@@ -220,6 +222,7 @@ taskchef project add <path>
 taskchef project import [<file> | -]
 taskchef project list
 taskchef project remove <name>
+taskchef dispatch prepare
 taskchef task record
 taskchef task resolve <task-id> --thread-id <thread-id>
 taskchef task show <task-id>
@@ -232,6 +235,12 @@ Workspace resolution is deterministic: `--workspace <path>`, then the
 current directory is never an implicit workspace. Data commands accept
 `--json` for machine-readable output. Run `taskchef help` for every option.
 
+`taskchef dispatch prepare --json` performs the read-only preparation used by
+the delegation skill in one process: it resolves the canonical workspace,
+loads and validates configured projects, and returns a generated task UUID,
+preparation timestamp, and exact correlation marker. `task record` accepts one
+JSON value only from closed, non-interactive standard input.
+
 ### One-time upgrade from an older workspace
 
 TaskChef 5 does not include a general migration command. For a one-time upgrade,
@@ -316,7 +325,7 @@ task lines remain readable without an eager rewrite of the append-only history.
 `project` value is the exact configured project path:
 
 ```sh
-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..."}' |
+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
 ```
 

package/SPEC.md

@@ -134,7 +134,7 @@ schedules, task status, results, host information, or the workspace path.
 `tasks.jsonl` contains one compact JSON object per line, in append order:
 
 ```json
-{"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":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.
@@ -142,7 +142,8 @@ schedules, task status, results, host information, or the workspace path.
 - `project` is the complete configured project snapshot used for routing.
 - `title` is a short task name.
 - `instruction` is the complete executor instruction, including its first-line
-  `# taskchef_id=<full UUID>` correlation marker.
+  `<!-- taskchef_id=<full UUID> -->` correlation marker and the blank line that
+  follows it.
 - `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.
@@ -165,19 +166,32 @@ 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.
+normalize to version 2 in API and CLI output. Historical task entries with the
+old heading-style marker also remain readable. New nullable records, candidate
+matching, and resolution require the exact HTML-comment marker; TaskChef never
+uses an old marker to correlate a thread. Direct records that already have a
+durable thread ID remain marker-independent because they do not use recovery.
+TaskChef does not eagerly rewrite legacy history solely for these compatibility
+cases.
 
 ## Dispatch workflow
 
 For each assignment, `$taskchef-delegate`:
 
-1. loads and validates configured projects
-2. selects one unambiguous target
-3. generates a full UUID and prefixes the instruction with its exact
-   `# taskchef_id=<UUID>` marker
+1. runs `dispatch prepare` and native Codex project discovery concurrently;
+   the preparation command resolves the canonical workspace, loads and
+   validates configured projects, and generates the full UUID, preparation
+   timestamp, and exact marker in one process
+2. selects one unambiguous configured target and matches its exact path against
+   the already-loaded native projects
+3. prefixes the instruction with the prepared exact
+   `<!-- taskchef_id=<UUID> -->` marker as the first line, followed by a blank
+   line
 4. creates a real Codex task at the exact configured path
-5. appends a task entry immediately when creation returns a durable thread ID
+5. appends a task entry immediately through closed, non-interactive stdin when
+   creation returns a durable thread ID; it never opens a TTY or writes a
+   temporary record file, and requests canonical-workspace write permission on
+   the first attempt when the command sandbox does not allow that path
 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
@@ -210,6 +224,12 @@ 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.
 
+`task record` rejects an interactive TTY before reading because its protocol is
+exactly one JSON value followed by EOF. Workspace-lock contention is retried for
+up to seven seconds, while permanent permission failures such as `EPERM` or
+`EACCES` fail immediately so the caller can request the required permission
+without paying the contention retry budget.
+
 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
 it was not recorded.

package/index.js

@@ -10,6 +10,7 @@ export {
   importProjects,
   initializeWorkspace,
   listProjects,
+  prepareDispatch,
   readConfig,
   listTasks,
   readTask,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "taskchef",
-  "version": "5.0.1",
+  "version": "5.1.0",
   "description": "A non-blocking interactive dispatcher for visible Codex tasks.",
   "license": "MIT",
   "author": "Favo Yang",
@@ -24,6 +24,7 @@
     "bin",
     "index.js",
     "SPEC.md",
+    "scripts/benchmark-dispatch-prepare.js",
     "src",
     "skills/taskchef-bootstrap",
     "skills/taskchef-delegate",
@@ -37,6 +38,7 @@
     "yaml": "^2.9.0"
   },
   "scripts": {
+    "benchmark:dispatch": "node scripts/benchmark-dispatch-prepare.js",
     "test": "node --test tests/taskchef.test.js"
   },
   "dependencies": {

package/scripts/benchmark-dispatch-prepare.js

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+
+import { execFileSync } from "node:child_process";
+import { mkdtemp, mkdir } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { performance } from "node:perf_hooks";
+import { fileURLToPath } from "node:url";
+
+import { addProject, initializeWorkspace } from "../index.js";
+
+const repositoryRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const cli = path.join(repositoryRoot, "bin", "taskchef.js");
+const sampleCount = Number.parseInt(process.env.TASKCHEF_BENCHMARK_SAMPLES ?? "30", 10);
+if (!Number.isInteger(sampleCount) || sampleCount < 1) {
+  throw new Error("TASKCHEF_BENCHMARK_SAMPLES must be a positive integer");
+}
+
+const root = await mkdtemp(path.join(os.tmpdir(), "taskchef-dispatch-benchmark-"));
+const workspace = path.join(root, "workspace");
+const project = path.join(root, "project");
+await mkdir(project);
+await initializeWorkspace(workspace);
+await addProject(workspace, { name: "benchmark", path: project, githubRepos: [] });
+
+function runTaskChef(args) {
+  return execFileSync(process.execPath, [cli, ...args], { encoding: "utf8" });
+}
+
+function measure(operation) {
+  const startedAt = performance.now();
+  operation();
+  return performance.now() - startedAt;
+}
+
+const legacy = [];
+const prepared = [];
+for (let index = 0; index < sampleCount; index += 1) {
+  legacy.push(measure(() => {
+    runTaskChef(["workspace", "path", "--json", "--workspace", workspace]);
+    runTaskChef(["project", "list", "--json", "--workspace", workspace]);
+    execFileSync(process.execPath, [
+      "-e",
+      "const { randomUUID } = require('node:crypto'); JSON.stringify({ taskId: randomUUID(), preparedAt: new Date().toISOString() });",
+    ]);
+  }));
+  prepared.push(measure(() => {
+    const result = JSON.parse(runTaskChef([
+      "dispatch", "prepare", "--json", "--workspace", workspace,
+    ]));
+    if (result.projectCount !== 1 || !result.marker.includes(result.taskId)) {
+      throw new Error("dispatch prepare returned an invalid benchmark result");
+    }
+  }));
+}
+
+function statistics(samples) {
+  const sorted = [...samples].sort((left, right) => left - right);
+  const percentile = (value) => sorted[Math.floor((sorted.length - 1) * value)];
+  return {
+    samples: sorted.length,
+    medianMs: Number(percentile(0.5).toFixed(2)),
+    p95Ms: Number(percentile(0.95).toFixed(2)),
+    minMs: Number(sorted[0].toFixed(2)),
+    maxMs: Number(sorted.at(-1).toFixed(2)),
+  };
+}
+
+const legacyStats = statistics(legacy);
+const preparedStats = statistics(prepared);
+process.stdout.write(`${JSON.stringify({
+  schemaVersion: 1,
+  comparison: {
+    legacy: {
+      description: "workspace path + project list + external UUID/timestamp process",
+      processCalls: 3,
+      ...legacyStats,
+    },
+    dispatchPrepare: {
+      description: "dispatch prepare",
+      processCalls: 1,
+      ...preparedStats,
+    },
+    savedProcessCalls: 2,
+    medianSpeedup: Number((legacyStats.medianMs / preparedStats.medianMs).toFixed(2)),
+    medianReductionPercent: Number(
+      ((1 - preparedStats.medianMs / legacyStats.medianMs) * 100).toFixed(1),
+    ),
+  },
+}, null, 2)}\n`);

package/skills/taskchef-delegate/SKILL.md

@@ -27,9 +27,11 @@ for all deterministic workspace and task-record operations.
 
 ## Dispatch
 
-1. Run `<plugin-root>/bin/taskchef.js workspace path --json`, then run
-   `<plugin-root>/bin/taskchef.js project list --json`
-   to load and validate the configured routing targets. Use
+1. In parallel, run `<plugin-root>/bin/taskchef.js dispatch prepare --json`
+   and list the native Codex projects once. The prepare command resolves the
+   canonical workspace, loads and validates the configured routing targets,
+   generates the lowercase full UUID task ID, and returns `preparedAt` plus the
+   exact first-line marker. Use
    `$taskchef-bootstrap` if the workspace is missing or unhealthy.
    The CLI resolves `--workspace`, then `TASKCHEF_WORKSPACE`, then
    `~/.agents/taskchef`; do not substitute the current project. Reject the
@@ -45,19 +47,28 @@ for all deterministic workspace and task-record operations.
    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. 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.
+4. Resolve the selected configured path against the already-loaded native
+   projects and require an exact match. Do not list native projects again.
+5. Use the task ID, preparation time, and marker returned by the preparation
+   command.
+   Prefix the complete executor instruction with
+   exactly `<!-- taskchef_id=<full UUID> -->` as the first line, 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`.
-   Send exactly `id`, `project`, `title`, `instruction`, and `threadId` as JSON
-   on stdin. Use the configured project path for `project`, and send the marked
-   instruction unchanged. Never persist a provisional `clientThreadId` or
+   `<plugin-root>/bin/taskchef.js task record --json` in one non-interactive
+   invocation whose stdin contains exactly one JSON value and is closed at
+   launch. Never open an interactive TTY and never create a temporary record
+   file. When the canonical workspace is outside the command sandbox's writable
+   roots, request permission for that exact write on the first attempt; never
+   use a failed sandbox write as a permission probe. Send exactly `id`,
+   `project`, `title`, `instruction`, and `threadId`. 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
@@ -85,10 +96,13 @@ for all deterministic workspace and task-record operations.
      `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's `<!-- taskchef_id=<full UUID> -->` marker and exactly one
+     candidate matches. Require an immediately following blank line. Reject old
+     heading-style markers, malformed comments, missing blank separators, and
+     marker-like text anywhere else. 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

package/skills/taskchef-report/SKILL.md

@@ -29,8 +29,10 @@ all deterministic task-log operations.
 2. Separate entries whose `threadId` is `null`. For those entries, take one
    `list_threads` snapshot with limit 50, filter by available project metadata,
    and inspect candidate structured delegated inputs. Use title only to
-   prioritize candidates, never to exclude them. When exactly one candidate
-   starts with the task's exact marker, run
+   prioritize candidates, never to exclude them. Require the exact first line
+   `<!-- taskchef_id=<full lowercase UUID> -->` and an immediately following
+   blank line; reject old heading-style markers, malformed comments, and missing
+   blank separators. When exactly one candidate has that exact prefix, run
    `<plugin-root>/bin/taskchef.js task resolve <task-id> --thread-id <thread-id> --json`.
    Do not resolve zero or multiple matches. Report unmatched entries as
    recorded but unresolved and do not pass them to native thread tools.

package/src/cli.js

@@ -12,6 +12,7 @@ import {
   importProjects,
   initializeWorkspace,
   listProjects,
+  prepareDispatch,
   readTask,
   recordTask,
   removeProject,
@@ -27,7 +28,16 @@ async function readStdin() {
   return input;
 }
 
+export function assertTaskRecordStdin(stdin = process.stdin) {
+  if (stdin.isTTY) {
+    throw new Error(
+      "task record requires non-interactive JSON on standard input; pipe one JSON value and close stdin",
+    );
+  }
+}
+
 async function readJsonStdin() {
+  assertTaskRecordStdin();
   const input = await readStdin();
   if (input.trim().length === 0) throw new Error("expected JSON on standard input");
   return JSON.parse(input);
@@ -248,6 +258,20 @@ async function projectList(args) {
   return 0;
 }
 
+async function dispatchPrepare(args) {
+  validateCommandArgs(args, 2, { values: ["--workspace"], switches: ["--json"] });
+  const resolution = workspaceSelection(args);
+  const prepared = await prepareDispatch(resolution.workspace);
+  prepared.workspaceSource = resolution.source;
+  print(prepared, args, (value) => [
+    `Workspace: ${value.workspace}`,
+    `Task ID: ${value.taskId}`,
+    `Prepared: ${value.preparedAt}`,
+    `Projects: ${value.projectCount}`,
+  ].join("\n"));
+  return 0;
+}
+
 async function projectRemove(args) {
   if (!args[2] || args[2].startsWith("--")) throw new Error("project remove requires a name");
   validateCommandArgs(args, 3, {
@@ -332,13 +356,15 @@ Usage:
   taskchef project import [<file> | -] [--replace] [--json] [--workspace <path>]
   taskchef project list [--json] [--workspace <path>]
   taskchef project remove <name> [--json] [--workspace <path>]
+  taskchef dispatch prepare [--json] [--workspace <path>]
   taskchef task record [--json] [--workspace <path>]
   taskchef task resolve <task-id> --thread-id <thread-id> [--json] [--workspace <path>]
   taskchef task show <task-id> [--json] [--workspace <path>]
   taskchef task list [--project <name-or-path>] [--ascending] [--json] [--workspace <path>]
   taskchef task summary [--json] [--workspace <path>]
 
-Task record reads JSON from standard input. Project import reads a JSON
+Task record reads one JSON value from closed, non-interactive standard input.
+Project import reads a JSON
 array from a file, or from standard input when the source is '-' or omitted.
 Workspace resolution precedence is --workspace, TASKCHEF_WORKSPACE, then
 ~/.agents/taskchef.
@@ -357,6 +383,7 @@ export async function runCli(args) {
   if (args[0] === "project" && args[1] === "import") return projectImport(args);
   if (args[0] === "project" && args[1] === "list") return projectList(args);
   if (args[0] === "project" && args[1] === "remove") return projectRemove(args);
+  if (args[0] === "dispatch" && args[1] === "prepare") return dispatchPrepare(args);
   if (args[0] === "task" && args[1] === "record") return taskRecord(args);
   if (args[0] === "task" && args[1] === "resolve") return taskResolve(args);
   if (args[0] === "task" && args[1] === "show" && args[2]) return taskShow(args);

package/src/delegation.js

@@ -5,7 +5,10 @@ export const THREAD_RESOLUTION_TIMEOUT_MS = 30_000;
 export const THREAD_RESOLUTION_RECENT_LIMIT = 50;
 export const THREAD_RESOLUTION_CLOCK_SKEW_MS = 5_000;
 
-const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+const UUID_SOURCE = "[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}";
+const UUID_PATTERN = new RegExp(`^${UUID_SOURCE}$`);
+const TASKCHEF_MARKER_PATTERN = new RegExp(`^<!-- taskchef_id=(${UUID_SOURCE}) -->$`);
+const LEGACY_TASKCHEF_MARKER_PATTERN = new RegExp(`^# taskchef_id=(${UUID_SOURCE})$`);
 
 function requireObject(value, name) {
   if (!value || typeof value !== "object" || Array.isArray(value)) {
@@ -67,14 +70,19 @@ function wait(delayMs) {
 }
 
 export function taskChefMarker(taskId) {
-  return `# taskchef_id=${requireUuid(taskId)}`;
+  return `<!-- taskchef_id=${requireUuid(taskId)} -->`;
 }
 
-export function parseTaskChefMarker(instruction) {
+export function parseTaskChefMarker(instruction, { allowLegacyHeading = false } = {}) {
   if (typeof instruction !== "string") return null;
   const firstLine = instruction.split(/\r?\n/, 1)[0];
-  const match = firstLine.match(/^# taskchef_id=([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$/);
-  return match?.[1] ?? null;
+  const currentMatch = firstLine.match(TASKCHEF_MARKER_PATTERN);
+  if (currentMatch !== null) {
+    const prefix = instruction.match(/^([^\r\n]*)(\r?\n)\2/);
+    return prefix === null ? null : currentMatch[1];
+  }
+  if (!allowLegacyHeading) return null;
+  return firstLine.match(LEGACY_TASKCHEF_MARKER_PATTERN)?.[1] ?? null;
 }
 
 export function prepareDelegation(instruction, { taskId = randomUUID() } = {}) {
@@ -119,9 +127,9 @@ export function structuredDelegatedInputs(result) {
 }
 
 export function hasExactTaskChefMarker(result, taskId) {
-  const marker = taskChefMarker(taskId);
+  const id = requireUuid(taskId);
   return structuredDelegatedInputs(result).some(
-    (input) => input.split(/\r?\n/, 1)[0] === marker,
+    (input) => parseTaskChefMarker(input) === id,
   );
 }
 

package/src/workspace.js

@@ -19,7 +19,11 @@ import { fileURLToPath } from "node:url";
 import path from "node:path";
 import { promisify } from "node:util";
 import lockfile from "proper-lockfile";
-import { normalizeDurableThreadId, parseTaskChefMarker } from "./delegation.js";
+import {
+  normalizeDurableThreadId,
+  parseTaskChefMarker,
+  taskChefMarker,
+} from "./delegation.js";
 import {
   canonicalGithubRepository,
   normalizeGithubRepositories,
@@ -157,15 +161,30 @@ function assertWorkspaceOutsideProject(workspaceRoot, projectPath) {
   }
 }
 
-async function withWorkspaceLock(workspaceRoot, operation) {
+export async function acquireWorkspaceLock(workspaceRoot, {
+  lock = lockfile.lock,
+  waitImpl = (delayMs) => new Promise((resolve) => setTimeout(resolve, delayMs)),
+} = {}) {
   const lockPath = path.join(workspaceRoot, WORKSPACE_LOCK_NAME);
-  const release = await lockfile.lock(workspaceRoot, {
-    realpath: false,
-    lockfilePath: lockPath,
-    stale: 600_000,
-    update: 10_000,
-    retries: { retries: 70, factor: 1, minTimeout: 100, maxTimeout: 100 },
-  });
+  for (let attempt = 0; attempt <= 70; attempt += 1) {
+    try {
+      return await lock(workspaceRoot, {
+        realpath: false,
+        lockfilePath: lockPath,
+        stale: 600_000,
+        update: 10_000,
+        retries: 0,
+      });
+    } catch (error) {
+      if (error.code !== "ELOCKED" || attempt === 70) throw error;
+      await waitImpl(100);
+    }
+  }
+  throw new Error("workspace lock retry loop ended unexpectedly");
+}
+
+async function withWorkspaceLock(workspaceRoot, operation) {
+  const release = await acquireWorkspaceLock(workspaceRoot);
   try {
     return await operation();
   } finally {
@@ -628,6 +647,25 @@ export async function listProjects(workspaceRoot) {
   return [...config.projects].sort((left, right) => left.name.localeCompare(right.name));
 }
 
+export async function prepareDispatch(workspaceRoot, {
+  taskId = randomUUID(),
+  now = () => new Date().toISOString(),
+} = {}) {
+  const workspace = await realpath(path.resolve(workspaceRoot));
+  const projects = await listProjects(workspace);
+  const marker = taskChefMarker(taskId);
+  const preparedAt = requireTimestamp(now(), "preparedAt");
+  return {
+    schemaVersion: 1,
+    workspace,
+    taskId,
+    preparedAt,
+    marker,
+    projectCount: projects.length,
+    projects,
+  };
+}
+
 export async function addProject(workspaceRoot, input) {
   const root = await realpath(path.resolve(workspaceRoot));
   return withWorkspaceLock(root, async () => {
@@ -701,7 +739,11 @@ export async function removeProject(workspaceRoot, name) {
   });
 }
 
-async function validateDispatchShape(dispatch, name = "task") {
+async function validateDispatchShape(
+  dispatch,
+  name = "task",
+  { allowLegacyHeading = false } = {},
+) {
   requireExactFields(dispatch, DISPATCH_FIELDS, name);
   if (![LEGACY_SCHEMA_VERSION, CURRENT_SCHEMA_VERSION].includes(dispatch.schemaVersion)) {
     throw new Error(`unsupported ${name} schemaVersion`);
@@ -724,7 +766,7 @@ async function validateDispatchShape(dispatch, name = "task") {
   };
   if (
     normalized.threadId === null &&
-    parseTaskChefMarker(normalized.instruction) !== normalized.id
+    parseTaskChefMarker(normalized.instruction, { allowLegacyHeading }) !== normalized.id
   ) {
     throw new Error(`${name} with a null threadId must contain its exact TaskChef marker`);
   }
@@ -756,7 +798,9 @@ async function readDispatchRecordsUnlocked(root) {
     records.push({
       line,
       raw: value,
-      normalized: await validateDispatchShape(value, `task line ${index + 1}`),
+      normalized: await validateDispatchShape(value, `task line ${index + 1}`, {
+        allowLegacyHeading: true,
+      }),
     });
   }
   const ids = new Set();
@@ -823,13 +867,13 @@ export async function resolveTask(workspaceRoot, taskId, threadId) {
     const index = dispatches.findIndex((dispatch) => dispatch.id === id);
     if (index === -1) throw new Error(`task not found: ${id}`);
     const dispatch = dispatches[index];
-    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;
     if (dispatch.threadId !== null) {
       throw new Error(`task already has a different threadId: ${id}`);
     }
+    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)) {
       throw new Error(`threadId is already recorded: ${durableThreadId}`);
     }