taskchef 5.0.2 → 5.1.0

package/.codex-plugin/plugin.json

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

@@ -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,13 +178,20 @@ 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
@@ -217,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.2",
+  "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,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

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