taskchef 5.0.0 → 5.0.2

package/.codex-plugin/plugin.json

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

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
@@ -281,16 +283,16 @@ taskchef project list
 taskchef project remove payments
 ```
 
-Human-readable project listings show one row per configured GitHub repository.
-Project details repeat on each row so multi-repository projects remain clear.
-A project without a configured repository has one row containing `-` in the
-repository column:
+Human-readable project listings group configured GitHub repositories by
+project. The first row shows the project details; additional repository rows
+leave the repeated name, kind, and path columns blank. A project without a
+configured repository has one row containing `-` in the repository column:
 
 ```text
 NAME      KIND    GITHUB REPOSITORY                        PATH
 notes     folder  -                                        /workspace/notes
 payments  git     https://github.com/example/payments-api  /workspace/payments
-payments  git     https://github.com/example/payments-sdk  /workspace/payments
+                  https://github.com/example/payments-sdk
 ```
 
 Import projects as a JSON array from a file or standard input:
@@ -316,7 +318,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,8 +166,13 @@ 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
 
@@ -175,7 +181,8 @@ 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
+   `<!-- 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
 6. when creation returns only a provisional client ID, immediately appends the

package/package.json

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

package/skills/taskchef-delegate/SKILL.md

@@ -47,10 +47,11 @@ for all deterministic workspace and task-record operations.
    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.
+   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
@@ -85,10 +86,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

@@ -18,6 +18,8 @@ import {
   resolveTask,
 } from "./workspace.js";
 
+const BLANK_TABLE_CELL = Symbol("blank table cell");
+
 async function readStdin() {
   let input = "";
   process.stdin.setEncoding("utf8");
@@ -97,9 +99,11 @@ function print(value, args, human) {
 }
 
 function table(headers, rows) {
-  const display = (value) => value === null || value === undefined || value === ""
-    ? "-"
-    : String(value);
+  const display = (value) => {
+    if (value === BLANK_TABLE_CELL) return "";
+    if (value === null || value === undefined || value === "") return "-";
+    return String(value);
+  };
   const widths = headers.map((header, index) =>
     Math.max(header.length, ...rows.map((row) => display(row[index]).length)));
   const format = (row) => row.map((value, index) => index === row.length - 1
@@ -110,13 +114,18 @@ function table(headers, rows) {
 
 function projectRows(projects) {
   return projects.flatMap((project) => {
-    const repositories = project.githubRepos.length > 0 ? project.githubRepos : [null];
-    return repositories.map((repository) => [
+    const [primaryRepository = null, ...additionalRepositories] = project.githubRepos;
+    return [[
       project.name,
       project.isGitRepository ? "git" : "folder",
-      repository,
+      primaryRepository,
       project.path,
-    ]);
+    ], ...additionalRepositories.map((repository) => [
+      BLANK_TABLE_CELL,
+      BLANK_TABLE_CELL,
+      repository,
+      BLANK_TABLE_CELL,
+    ])];
   });
 }
 

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

@@ -701,7 +701,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 +728,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 +760,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 +829,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}`);
     }