taskchef 5.0.2 → 5.1.1

package/.codex-plugin/plugin.json

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

@@ -222,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>
@@ -234,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,

package/SPEC.md

@@ -178,21 +178,30 @@ cases.
 
 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
+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
 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
+   snapshots on a nominal 10- and 30-second schedule after the provisional
+   result; a late first checkpoint runs immediately, and the second starts at
+   least 20 seconds after the first actually started. It 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.
@@ -202,11 +211,13 @@ 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.
+marker before persistence. Zero exact matches remain unresolved; multiple exact
+matches are ambiguous. Snapshot, candidate-read, native-resolution, or
+task-resolution errors leave the already-recorded nullable entry intact. The
+fallback is bounded by two snapshots rather than an absolute wall-clock cutoff:
+mandatory recording or tool latency can shift both attempts later, but cannot
+erase an attempt or reduce the minimum 20-second interval between their start
+times.
 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.
@@ -217,6 +228,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.2",
+  "version": "5.1.1",
   "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,20 +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> -->` as the
-   first line, followed by a blank line and the instruction body. Preserve this
+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
@@ -72,10 +82,14 @@ for all deterministic workspace and task-record operations.
      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.
+     snapshots with limit 50. The nominal schedule is 10 and 30 seconds after
+     the provisional result. Treat the first checkpoint as due, not expired: if
+     nullable recording or other required work finishes after 10 seconds, take
+     the first snapshot immediately. Start the second snapshot no sooner than
+     20 seconds after the first snapshot actually started. Useful candidate
+     work counts toward that interval; when it finishes sooner, wait only the
+     remainder. Never suppress either snapshot merely because an earlier step
+     ran late, and never take a third snapshot.
    - 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

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

@@ -1,6 +1,6 @@
 import { randomUUID } from "node:crypto";
 
-export const THREAD_RESOLUTION_CHECKPOINTS_MS = Object.freeze([10_000, 29_000]);
+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;
 export const THREAD_RESOLUTION_CLOCK_SKEW_MS = 5_000;
@@ -179,6 +179,9 @@ function validateResolutionSchedule(checkpointsMs, timeoutMs) {
   if (!Array.isArray(checkpointsMs) || checkpointsMs.length === 0) {
     throw new Error("checkpointsMs must contain at least one checkpoint");
   }
+  if (checkpointsMs.length > 2) {
+    throw new Error("checkpointsMs must contain at most two checkpoints");
+  }
   if (!Number.isInteger(timeoutMs) || timeoutMs < 1) {
     throw new Error("timeoutMs must be positive");
   }
@@ -189,6 +192,9 @@ function validateResolutionSchedule(checkpointsMs, timeoutMs) {
     }
     previous = checkpoint;
   }
+  if (checkpointsMs.length === 2 && checkpointsMs[1] - checkpointsMs[0] < 20_000) {
+    throw new Error("checkpointsMs must keep two checkpoints at least 20000ms apart");
+  }
 }
 
 async function inspectCandidates(candidates, {
@@ -365,7 +371,11 @@ export async function createAndRecordDelegation({
     return false;
   };
 
-  const acceptResolvedThread = async (thread, resolution, attempt, { verified = false } = {}) => {
+  const acceptResolvedThread = async (thread, resolution, attempt, {
+    verified = false,
+    enforceDeadline = true,
+  } = {}) => {
+    const canContinue = enforceDeadline ? hasResolutionTime : () => true;
     const threadId = toolIdentifier(thread.id);
     if (
       threadId === null
@@ -381,18 +391,18 @@ export async function createAndRecordDelegation({
       return null;
     }
     const durableThread = { ...thread, id: threadId };
-    if (!hasResolutionTime()) return null;
+    if (!canContinue()) return null;
     if (!verified) {
       const inspected = await inspectCandidates([durableThread], {
         readThread,
         taskId: prepared.id,
         attempt,
-        canVerify: hasResolutionTime,
+        canVerify: canContinue,
       });
       discoveryErrors.push(...inspected.errors);
       if (inspected.exactMatches.length !== 1 || inspected.errors.length > 0) return null;
     }
-    if (!hasResolutionTime()) return null;
+    if (!canContinue()) return null;
     try {
       await resolveRecordedTask({ id: prepared.id, threadId });
     } catch (error) {
@@ -470,12 +480,14 @@ export async function createAndRecordDelegation({
   let exactMatches = [];
   let ambiguousMatches = [];
   let attemptsMade = 0;
+  let previousAttemptStartedAt = resolutionStartedAt;
   for (let index = 0; index < checkpointsMs.length; index += 1) {
     const attempt = index + 1;
-    const checkpointMs = checkpointsMs[index];
-    const elapsedBeforeAttempt = now() - resolutionStartedAt;
-    if (elapsedBeforeAttempt > timeoutMs) break;
-    const remainingDelayMs = checkpointMs - elapsedBeforeAttempt;
+    const intervalMs = index === 0
+      ? checkpointsMs[0]
+      : checkpointsMs[index] - checkpointsMs[index - 1];
+    const dueAt = previousAttemptStartedAt + intervalMs;
+    const remainingDelayMs = dueAt - now();
     if (remainingDelayMs > 0) {
       try {
         await waitImpl(remainingDelayMs);
@@ -488,43 +500,36 @@ export async function createAndRecordDelegation({
         break;
       }
     }
-    if (!hasResolutionTime()) break;
+    previousAttemptStartedAt = now();
     attemptsMade = attempt;
     let candidates = [];
     let attemptFailed = false;
     try {
       const snapshot = await listThreads({ limit: recentLimit });
-      if (hasResolutionTime()) {
-        candidates = filterThreadCandidates(snapshot, {
-          excludedThreadIds: provisionalIds,
-          hostId: expected.hostId ?? null,
-          projectId: expected.projectId ?? target.projectId ?? null,
-          title,
-          createdAfter,
-          environmentType: expected.environmentType ?? target.environment?.type ?? null,
-        });
-      }
+      candidates = filterThreadCandidates(snapshot, {
+        excludedThreadIds: provisionalIds,
+        hostId: expected.hostId ?? null,
+        projectId: expected.projectId ?? target.projectId ?? null,
+        title,
+        createdAfter,
+        environmentType: expected.environmentType ?? target.environment?.type ?? null,
+      });
     } catch (error) {
-      if (hasResolutionTime()) {
-        attemptFailed = true;
-        discoveryErrors.push({
-          attempt,
-          operation: "listThreads",
-          message: error instanceof Error ? error.message : String(error),
-        });
-      }
+      attemptFailed = true;
+      discoveryErrors.push({
+        attempt,
+        operation: "listThreads",
+        message: error instanceof Error ? error.message : String(error),
+      });
     }
-    if (!hasResolutionTime()) break;
     const inspected = await inspectCandidates(candidates, {
       readThread,
       taskId: prepared.id,
       attempt,
-      canVerify: hasResolutionTime,
     });
     exactMatches = inspected.exactMatches;
     discoveryErrors.push(...inspected.errors);
     if (inspected.errors.length > 0) attemptFailed = true;
-    if (!hasResolutionTime()) break;
     if (exactMatches.length > 1) ambiguousMatches = exactMatches;
     if (
       exactMatches.length === 1
@@ -536,7 +541,7 @@ export async function createAndRecordDelegation({
         exactMatches[0],
         "discovered",
         attempt,
-        { verified: true },
+        { verified: true, enforceDeadline: false },
       );
       if (resolved !== null) return resolved;
     }

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 () => {