taskchef 6.1.3 → 7.0.0

package/docs/workflows.md

@@ -0,0 +1,236 @@
+# TaskChef workflows
+
+This developer and advanced-agent guide explains how the current implementation
+moves data through TaskChef. The [specification](spec.md) is normative; the
+[README](../README.md) owns user operation. The
+[FirstMate comparison](firstmate-taskchef-comparison.md) is non-normative
+research.
+
+## Implementation map
+
+| Surface | Responsibility |
+| --- | --- |
+| `skills/taskchef-delegate/SKILL.md` | Split, route, record-before-create, create, return. |
+| `skills/taskchef-bootstrap/SKILL.md` | Initialize current workspace and configure projects. |
+| `skills/taskchef-report/SKILL.md` | Select cached tasks and perform bounded live checks. |
+| `src/mcp.js` | Four structured lifecycle tools and MCP annotations. |
+| `src/delegation.js` | UUID marker, executor contract paragraphs, and creation-failure handling. |
+| `src/workspace.js` | Current schemas, validation, locking, atomic JSONL writes, linking, and result freshness. |
+| `src/cli.js` | Administration, inspection, diagnostics, and dashboard startup. |
+| `src/dashboard.js` | Validated snapshots, SSE fan-out, and bounded open actions. |
+
+The MCP process resolves `TASKCHEF_WORKSPACE` once and never accepts a model
+supplied path. The CLI resolves `--workspace`, then the environment, then the
+per-user default.
+
+## Normal delegation and self-linking
+
+The dispatcher uses native Codex project discovery for routing and MCP for
+TaskChef state. It never supplies executor identity.
+
+```mermaid
+sequenceDiagram
+  autonumber
+  actor U as User
+  participant D as Dispatcher skill
+  participant M as TaskChef MCP
+  participant W as workspace.js
+  participant C as Native Codex
+  participant E as Executor
+  U->>D: Request outcome
+  par Route once
+    D->>C: List native projects
+  and Prepare each outcome
+    D->>M: prepare_dispatch()
+    M->>W: prepareDispatch()
+    W-->>M: UUID, marker, projects
+    M-->>D: preparation
+  end
+  D->>D: Choose one configured and native project
+  D->>M: record_task(id, project, title, instruction, null)
+  M->>W: recordTask()
+  W->>W: Lock, validate, append schema-4 snapshot
+  W-->>M: working link-pending task
+  M-->>D: task
+  D->>C: Create executor with marked instruction
+  C-->>D: Created-task reference
+  D-->>U: Return immediately
+  C->>E: Start executor
+  E->>E: Read own CODEX_THREAD_ID
+  E->>M: link_task(taskId, threadId)
+  M->>W: linkTask()
+  W->>W: Lock and replace null identity atomically
+  W-->>E: linked working task
+```
+
+Record-before-create makes native creation failure observable. Executor
+self-linking removes dispatcher-side polling, task search, title matching, and
+parent/child identity inference.
+
+## Result reporting
+
+The executor obtains the turn identity from an exact native read of its own
+linked task. `report_result` updates only the latest semantic snapshot.
+
+```mermaid
+sequenceDiagram
+  autonumber
+  participant E as Executor
+  participant C as Native Codex task API
+  participant M as TaskChef MCP
+  participant W as workspace.js
+  E->>E: Finish or reach semantic decision
+  E->>C: Exact read of linked executor
+  C-->>E: Current turn ID
+  E->>M: report_result(taskId, threadId, turnId, status, summary)
+  M->>W: reportTaskResult()
+  W->>W: Lock and validate identity and freshness
+  alt Fresh result
+    W->>W: Replace status, summary, turnId, updatedAt, updatedBy
+    W-->>M: Updated task
+    M-->>E: Recorded result
+  else Same turn and same result
+    W-->>M: Existing task
+    M-->>E: Idempotent success
+  else Conflict or stale turn
+    W-->>M: Tool error
+    M-->>E: Visible failure
+  end
+```
+
+A native approval prompt is not a semantic result. `needs_input` is reserved
+for a user decision or fact required to proceed.
+
+## Follow-up turns
+
+Turn IDs are freshness tokens for semantic callbacks. Lexical UUIDv7 order lets
+the workspace reject a callback from an older executor turn.
+
+```mermaid
+sequenceDiagram
+  autonumber
+  actor U as User
+  participant E as Linked executor
+  participant C as Native Codex task API
+  participant M as TaskChef MCP
+  participant W as workspace.js
+  E->>M: report_result(..., turnA, needs_input, summaryA)
+  M->>W: Store turnA
+  W-->>E: needs_input snapshot
+  U->>E: Provide decision
+  E->>C: Read exact executor after follow-up
+  C-->>E: turnB
+  E->>M: report_result(..., turnB, completed, summaryB)
+  M->>W: Require turnB greater than turnA
+  W-->>E: completed snapshot
+  E->>M: report_result(..., turnA, completed, staleSummary)
+  M->>W: Validate freshness
+  W-->>E: Error: turn is not newer
+```
+
+The executor contract therefore requires a new exact read on every follow-up;
+cached or inherited turn IDs are invalid.
+
+## Link-pending and failure paths
+
+A failed or interrupted link never authorizes substantive work. The record
+remains a visible retry point for the same executor.
+
+```mermaid
+sequenceDiagram
+  autonumber
+  participant E as Executor
+  participant M as TaskChef MCP
+  participant W as workspace.js
+  E->>M: link_task(taskId, assertedThreadId)
+  M->>W: linkTask()
+  alt Exact eligible record and unused canonical UUIDv7
+    W->>W: Atomic null-to-thread transition
+    W-->>E: Linked task
+  else MCP unavailable or call interrupted
+    M--xE: Visible failure
+    Note over E,W: Record remains link-pending
+  else Wrong task, marker, state, or identity
+    W-->>E: Validation error
+    Note over E,W: No mutation
+  end
+  E->>E: Retry linking on a later turn before work
+```
+
+If `CODEX_THREAD_ID` is missing, the executor reports the problem visibly and
+does not substitute `CODEX_SESSION_ID`, a parent ID, or search results.
+
+Native creation can fail after the durable record exists:
+
+```mermaid
+sequenceDiagram
+  autonumber
+  participant D as Dispatcher
+  participant M as TaskChef MCP
+  participant W as workspace.js
+  participant C as Native Codex
+  D->>M: record_task(..., threadId null)
+  M->>W: Append working record
+  W-->>D: Recorded task
+  D->>C: Create executor
+  C--xD: Creation error
+  D->>M: report_result(taskId, null, null, failed, boundedSummary)
+  M->>W: Lock and store creation failure
+  W-->>D: Failed task with null IDs
+  D-->>D: Preserve original creation error and task ID
+```
+
+The summary is bounded and excludes secrets, transcripts, and raw command
+output. A creation-failure record cannot later be linked.
+
+## Dashboard update flow
+
+Every mutation rewrites `tasks.jsonl` atomically under the workspace lock.
+The monitor tolerates replacement races, validates a complete snapshot, and
+publishes only the newest state to each SSE client.
+
+```mermaid
+sequenceDiagram
+  autonumber
+  participant M as MCP writer
+  participant W as workspace.js
+  participant F as tasks.jsonl
+  participant D as Dashboard monitor
+  participant B as Browser client
+  participant C as Native Codex
+  M->>W: link_task or report_result
+  W->>W: Acquire shared lock
+  W->>F: Atomic replacement
+  W-->>M: Updated task
+  F-->>D: Filesystem change
+  D->>F: Bounded read from one descriptor
+  D->>D: Validate current schema and sort
+  D-->>B: SSE snapshot
+  B->>D: Open task action
+  alt Canonical Codex UUIDv7
+    D->>C: Direct thread navigation
+  else Null or non-native durable ID
+    D->>D: Revalidate current project configuration
+    D->>C: Open configured project
+  end
+```
+
+The dashboard binds to `127.0.0.1`, has no shared session state, limits
+request bodies, and checks origin/authority for stateful local actions. Historical
+project paths are untrusted until matched against current configuration.
+
+## Concurrency and trust boundaries
+
+Configuration and task mutations use the same `proper-lockfile` lock. ID and
+identity uniqueness checks, link eligibility, and result freshness occur
+inside the critical section. Writes use temporary files/hard links and atomic
+rename so readers see complete snapshots.
+
+The dispatcher controls routing and immutable intent. The executor controls its
+cooperatively asserted identity and semantic result. Neither identity nor
+summary is cryptographically authenticated; this is a local single-user trust
+model. Managed files, instructions, project snapshots, MCP inputs, and dashboard
+requests are validated at every action boundary.
+
+Only current configuration schema 2 and task schema 4 are accepted.
+Unsupported data is rejected without rewrite.

package/index.js

@@ -5,7 +5,6 @@ export {
   canonicalGitRoot,
   doctorWorkspace,
   ensureWorkspaceInstructions,
-  ensureWorkspaceSkills,
   filterTasks,
   importProjects,
   initializeWorkspace,
@@ -17,7 +16,6 @@ export {
   readTask,
   recordTask,
   reportTaskResult,
-  resolveTask,
   requireSafeId,
   removeProject,
   validateConfig,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "taskchef",
-  "version": "6.1.3",
+  "version": "7.0.0",
   "description": "A non-blocking interactive dispatcher for visible Codex tasks.",
   "license": "MIT",
   "author": "Favo Yang",
@@ -23,10 +23,11 @@
     "assets",
     "BACKLOG.md",
     "bin",
-    "docs/delegation-design.md",
+    "docs/spec.md",
+    "docs/workflows.md",
+    "docs/firstmate-taskchef-comparison.md",
     "index.js",
     "mcp",
-    "SPEC.md",
     "scripts/benchmark-dispatch-prepare.js",
     "scripts/e2e-benchmark.js",
     "src",

package/scripts/benchmark-dispatch-prepare.js

@@ -33,10 +33,10 @@ function measure(operation) {
   return performance.now() - startedAt;
 }
 
-const legacy = [];
+const baseline = [];
 const prepared = [];
 for (let index = 0; index < sampleCount; index += 1) {
-  legacy.push(measure(() => {
+  baseline.push(measure(() => {
     runTaskChef(["workspace", "path", "--json", "--workspace", workspace]);
     runTaskChef(["project", "list", "--json", "--workspace", workspace]);
     execFileSync(process.execPath, [
@@ -66,15 +66,15 @@ function statistics(samples) {
   };
 }
 
-const legacyStats = statistics(legacy);
+const baselineStats = statistics(baseline);
 const preparedStats = statistics(prepared);
 process.stdout.write(`${JSON.stringify({
   schemaVersion: 1,
   comparison: {
-    legacy: {
+    baseline: {
       description: "workspace path + project list + external UUID/timestamp process",
       processCalls: 3,
-      ...legacyStats,
+      ...baselineStats,
     },
     dispatchPrepare: {
       description: "dispatch prepare",
@@ -82,9 +82,9 @@ process.stdout.write(`${JSON.stringify({
       ...preparedStats,
     },
     savedProcessCalls: 2,
-    medianSpeedup: Number((legacyStats.medianMs / preparedStats.medianMs).toFixed(2)),
+    medianSpeedup: Number((baselineStats.medianMs / preparedStats.medianMs).toFixed(2)),
     medianReductionPercent: Number(
-      ((1 - preparedStats.medianMs / legacyStats.medianMs) * 100).toFixed(1),
+      ((1 - preparedStats.medianMs / baselineStats.medianMs) * 100).toFixed(1),
     ),
   },
 }, null, 2)}\n`);

package/skills/taskchef-bootstrap/SKILL.md

@@ -15,8 +15,8 @@ all deterministic workspace operations.
 ## Boundaries
 
 - Keep implementation, tests, and reports in the TaskChef source repository.
-- Keep only `AGENTS.md`, `taskchef.json`, and `tasks.jsonl` in a dispatcher
-  workspace.
+- Create and manage only `AGENTS.md`, `taskchef.json`, and `tasks.jsonl` in a
+  dispatcher workspace. Preserve unrelated user-owned paths.
 - Do not dispatch tasks or report on executor threads during bootstrap unless
   the user separately requests those actions.
 - Never create hooks, schedules, polling, or daemons. TaskChef executors
@@ -37,9 +37,9 @@ all deterministic workspace operations.
    CLI discovered from the current desktop environment; never invoke
    `codex add` or hard-code an application bundle path.
 3. `workspace init` takes no stdin, creates an empty
-   configuration when missing, creates the one-entry-per-task JSONL log, refreshes
-   managed instructions, and removes legacy TaskChef skill links. The installed
-   plugin provides all three TaskChef skills outside the dispatcher workspace.
+   configuration when missing, creates the one-entry-per-task JSONL log, and
+   refreshes managed instructions. The installed plugin provides all three
+   TaskChef skills outside the dispatcher workspace.
 4. Run `doctor --json` after setup or when the user asks to diagnose the
    workspace. Doctor is read-only. Rerun `workspace init --json` to repair the
    managed scaffold.
@@ -86,6 +86,5 @@ Example managed-workspace import entry:
 }
 ```
 
-`workspace init` safely migrates schema-version-1 configuration: a string
-`githubRepo` becomes a one-item `githubRepos` list and `null` becomes
-`githubRepos: []`. All subsequent configuration writes use schema version 2.
+TaskChef accepts configuration schema version 2 only. `githubRepos` is always
+an array; unsupported configuration is rejected without being rewritten.

package/skills/taskchef-delegate/SKILL.md

@@ -23,8 +23,8 @@ reloaded or installed.
 
 ## Boundaries
 
-- Keep only `AGENTS.md`, `taskchef.json`, and `tasks.jsonl` in the dispatcher
-  workspace.
+- Treat only `AGENTS.md`, `taskchef.json`, and `tasks.jsonl` as TaskChef-managed
+  dispatcher files. Preserve unrelated user-owned paths.
 - Use real Codex tasks, never collaboration or subagent tools.
 - Never use hooks, schedules, daemons, background monitors, recent-task
   searches, transcripts, hidden reasoning, or polling for identity.
@@ -78,10 +78,3 @@ user decision, not live approval UI.
 
 The filesystem watcher surfaces `link_task` and `report_result` writes to the
 dashboard. The linked child ID drives the exact Codex deep link.
-
-## Legacy recovery
-
-`taskchef task resolve` exists only for unresolved records created before the
-self-linking schema. Require an exact marker match and a unique durable child
-ID. The command rejects new self-linking records. Never edit `tasks.jsonl`
-directly.

package/skills/taskchef-report/SKILL.md

@@ -29,8 +29,8 @@ all deterministic task-log operations.
    - Use the full list only when the user asks for an overview of the task history.
 2. For an overview, select only attention-worthy candidates before detailed
    reads:
-   - always include `working`, `needs_input`, null-status legacy entries, and
-     entries with a null `threadId`;
+   - always include `working`, `needs_input`, and entries with a null
+     `threadId`;
    - include `completed` and `failed` entries updated during the last seven
      days;
    - omit older terminal entries by default and report the omitted count;
@@ -75,12 +75,8 @@ all deterministic task-log operations.
    completed, failed, unresolved, or unknown. Show the cached summary when it
    remains fresh. If a newer turn exists without a callback, describe the live
    state and label the cached result stale rather than overwriting it.
-6. Never edit `tasks.jsonl` directly during reporting. The task API preserves
-   each record's persisted `schemaVersion`: a schema 4 null identity is executor
-   link-pending and must be retried by that executor, while a schema 1-3 null
-   identity is a legacy recovery candidate. Manual recovery may call
-   `task resolve` only for the latter after one exact structured marker match.
-   Never persist inferred status,
+6. Never edit `tasks.jsonl` directly during reporting. A null identity is
+   executor link-pending and must be retried by that executor. Never persist inferred status,
    transcripts, prose classifications, or hidden reasoning. Do not poll or wait.
 
 If the task history is empty, say that TaskChef has not recorded any tasks. If

package/src/cli.js

@@ -18,7 +18,6 @@ import {
   recordTask,
   removeProject,
   requireSafeId,
-  resolveTask,
 } from "./workspace.js";
 
 const BLANK_TABLE_CELL = Symbol("blank table cell");
@@ -241,7 +240,6 @@ async function initialize(args) {
     `Configuration: ${value.config.action}`,
     `Task log: ${value.tasks.action}`,
     `Instructions: ${value.instructions.action}`,
-    `Legacy skill links removed: ${value.legacySkills.removed.length}`,
     ...(value.registration ? [`Codex opening: ${value.registration.status}`] : []),
   ].join("\n"));
   return registrationFailed ? 5 : 0;
@@ -353,22 +351,6 @@ async function taskRecord(args) {
   return 0;
 }
 
-async function taskResolve(args) {
-  if (!args[2] || args[2].startsWith("--")) throw new Error("task resolve requires a task ID");
-  validateCommandArgs(args, 3, {
-    values: ["--thread-id", "--workspace"],
-    switches: ["--json"],
-  });
-  if (!args.includes("--thread-id")) throw new Error("task resolve requires --thread-id");
-  const task = await resolveTask(
-    workspaceRoot(args),
-    args[2],
-    option(args, "--thread-id"),
-  );
-  print(task, args, (value) => `Resolved ${value.id}: ${value.threadId}`);
-  return 0;
-}
-
 async function taskShow(args) {
   validateCommandArgs(args, 3, { values: ["--workspace"], switches: ["--json"] });
   print(await readTaskForShow(workspaceRoot(args), args[2]), args, taskDetails);
@@ -464,13 +446,11 @@ Usage:
   taskchef project remove <name> [--json] [--workspace <path>]
   taskchef dispatch prepare [--json] [--workspace <path>]
   taskchef task record [--json] [--workspace <path>]
-  taskchef task resolve <legacy-task-id> --thread-id <thread-id> [--json] [--workspace <path>]
   taskchef task show <task-id-or-8-character-prefix> [--json] [--workspace <path>]
   taskchef task list [--project <name-or-path>] [--ascending] [--full-id] [--json] [--workspace <path>]
   taskchef task summary [--json] [--workspace <path>]
 
 Task record reads one JSON value from closed, non-interactive standard input.
-Task resolve is a legacy migration command and rejects self-linking task records.
 Task show accepts a full task ID or the exact 8-character ID printed by task list.
 Task show prints human-readable details by default; --json prints the complete task object.
 Project import reads a JSON
@@ -497,7 +477,6 @@ export async function runCli(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);
   if (args[0] === "task" && args[1] === "list") return taskList(args);
   if (args[0] === "task" && args[1] === "summary") return taskSummary(args);

package/src/dashboard.js

@@ -521,7 +521,7 @@ export async function createDashboardServer({
         else await openWorkspaceInCodex(canonicalProjectPath);
         sendJson(response, 202, {
           message: task.threadId
-            ? "Opened the project in Codex; this legacy thread ID cannot use direct navigation."
+            ? "Opened the project in Codex; this thread ID cannot use direct navigation."
             : "Opened the project in Codex; this task does not yet have a thread ID.",
         });
       } catch {

package/src/delegation.js

@@ -8,7 +8,6 @@ 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 CODEX_UUID_V7_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
 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)) throw new Error(`${name} must be an object`);
@@ -82,16 +81,13 @@ export function taskChefMarker(taskId) {
   return `<!-- taskchef_id=${requireUuid(taskId)} -->`;
 }
 
-export function parseTaskChefMarker(instruction, { allowLegacyHeading = false } = {}) {
+export function parseTaskChefMarker(instruction) {
   if (typeof instruction !== "string") return null;
   const firstLine = instruction.split(/\r?\n/, 1)[0];
   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;
+  if (currentMatch === null) return null;
+  const prefix = instruction.match(/^([^\r\n]*)(\r?\n)\2/);
+  return prefix === null ? null : currentMatch[1];
 }
 
 export function prepareDelegation(instruction, { taskId = randomUUID() } = {}) {

package/src/github.js

@@ -59,11 +59,7 @@ export function canonicalGithubRepository(value, name = "githubRepos") {
 export function normalizeGithubRepositories(
   value,
   name = "githubRepos",
-  { allowLegacyScalar = false } = {},
 ) {
-  if (allowLegacyScalar && (value === null || typeof value === "string")) {
-    value = value === null ? [] : [value];
-  }
   if (!Array.isArray(value)) throw new Error(`${name} must be an array of GitHub repository URLs`);
   const repositories = [];
   const seen = new Set();

package/src/mcp.js

@@ -18,22 +18,22 @@ const projectSchema = z.object({
 });
 
 const taskSchema = z.object({
-  schemaVersion: z.number(),
+  schemaVersion: z.literal(4),
   id: z.string(),
   project: projectSchema,
   title: z.string(),
   instruction: z.string(),
   threadId: z.string().nullable(),
   createdAt: z.string(),
-  status: z.enum(["working", "needs_input", "completed", "failed"]).nullable(),
+  status: z.enum(["working", "needs_input", "completed", "failed"]),
   summary: z.string().nullable(),
   turnId: z.string().nullable(),
-  updatedAt: z.string().nullable(),
-  updatedBy: z.enum(["dispatcher", "hook", "mcp"]).nullable(),
+  updatedAt: z.string(),
+  updatedBy: z.enum(["dispatcher", "mcp"]),
 });
 
 const preparationSchema = z.object({
-  schemaVersion: z.number(),
+  schemaVersion: z.literal(1),
   workspace: z.string(),
   taskId: z.string(),
   preparedAt: z.string(),