taskchef 6.1.3 → 7.1.0

package/src/workspace.js

@@ -5,17 +5,14 @@ import {
   lstat,
   mkdir,
   readFile,
-  readdir,
   realpath,
   link,
   rename,
-  rmdir,
   stat,
   unlink,
   writeFile,
 } from "node:fs/promises";
 import { randomUUID } from "node:crypto";
-import { fileURLToPath } from "node:url";
 import path from "node:path";
 import { promisify } from "node:util";
 import lockfile from "proper-lockfile";
@@ -37,32 +34,22 @@ const DISPATCHER_INSTRUCTIONS_URL = new URL(
 );
 const DISPATCHER_INSTRUCTIONS_START = "<!-- taskchef:dispatcher-instructions:start -->";
 const DISPATCHER_INSTRUCTIONS_END = "<!-- taskchef:dispatcher-instructions:end -->";
-const TASKCHEF_SKILL_NAMES = [
-  "taskchef-bootstrap",
-  "taskchef-delegate",
-  "taskchef-report",
-];
-const LEGACY_TASKCHEF_SKILL_NAMES = [...TASKCHEF_SKILL_NAMES, "taskchef-reconcile"];
-const SKILLS_SOURCE_ROOT = fileURLToPath(new URL("../skills/", import.meta.url));
 const DISPATCH_FILE_NAME = "tasks.jsonl";
 const WORKSPACE_LOCK_NAME = ".taskchef-workspace.lock";
 const SAFE_ID = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
 const CURRENT_CONFIG_SCHEMA_VERSION = 2;
-const CURRENT_TASK_SCHEMA_VERSION = 4;
-const PREVIOUS_STATEFUL_TASK_SCHEMA_VERSION = 3;
-const LEGACY_SCHEMA_VERSION = 1;
-const PREVIOUS_SCHEMA_VERSION = 2;
+const CURRENT_TASK_SCHEMA_VERSION = 5;
+const PREVIOUS_SELF_LINKING_TASK_SCHEMA_VERSION = 4;
 const CONFIG_FIELDS = new Set(["schemaVersion", "projects"]);
 const PROJECT_FIELDS = new Set([
   "name",
   "path",
   "isGitRepository",
-  "githubRepo",
   "githubRepos",
   "description",
 ]);
 const PROJECT_INPUT_FIELDS = new Set(["name", "path", "githubRepos", "description"]);
-const DISPATCH_FIELDS = new Set([
+const STATEFUL_DISPATCH_FIELDS = new Set([
   "schemaVersion",
   "id",
   "project",
@@ -76,15 +63,7 @@ const DISPATCH_FIELDS = new Set([
   "updatedAt",
   "updatedBy",
 ]);
-const LEGACY_DISPATCH_FIELDS = new Set([
-  "schemaVersion",
-  "id",
-  "project",
-  "title",
-  "instruction",
-  "threadId",
-  "createdAt",
-]);
+const DISPATCH_FIELDS = new Set([...STATEFUL_DISPATCH_FIELDS, "lastResult"]);
 const RECORD_DISPATCH_FIELDS = new Set([
   "id",
   "project",
@@ -94,8 +73,9 @@ const RECORD_DISPATCH_FIELDS = new Set([
 ]);
 const RESULT_STATUSES = new Set(["needs_input", "completed", "failed"]);
 const TASK_STATUSES = new Set(["working", ...RESULT_STATUSES]);
-const TASK_UPDATE_SOURCES = new Set(["dispatcher", "hook", "mcp"]);
+const TASK_UPDATE_SOURCES = new Set(["dispatcher", "mcp"]);
 const MAX_RESULT_SUMMARY_LENGTH = 2_000;
+const LAST_RESULT_FIELDS = new Set(["status", "summary", "turnId", "updatedAt"]);
 
 function requireExactFields(value, fields, name) {
   if (!value || typeof value !== "object" || Array.isArray(value)) {
@@ -123,6 +103,13 @@ function requireTimestamp(value, name) {
   return value;
 }
 
+function transitionTimestamp(now, currentUpdatedAt) {
+  const candidate = requireTimestamp(now ?? new Date().toISOString(), "transition timestamp");
+  return Date.parse(candidate) < Date.parse(currentUpdatedAt)
+    ? currentUpdatedAt
+    : candidate;
+}
+
 function optionalString(value, name, { maxLength = null } = {}) {
   if (value === null) return null;
   const normalized = requireString(value, name).trim();
@@ -347,75 +334,6 @@ export async function ensureWorkspaceInstructions(workspaceRoot) {
   return { path: filePath, action };
 }
 
-async function findLegacySkillLinks(workspaceRoot) {
-  const agentsDirectory = path.join(workspaceRoot, ".agents");
-  const agentsDetails = await lstat(agentsDirectory).catch((error) => {
-    if (error.code === "ENOENT") return null;
-    throw error;
-  });
-  if (agentsDetails === null) return { agentsDirectory: null, skillsDirectory: null, links: [] };
-  if (agentsDetails.isSymbolicLink() || !agentsDetails.isDirectory()) {
-    return { agentsDirectory: null, skillsDirectory: null, links: [] };
-  }
-
-  const skillsDirectory = path.join(agentsDirectory, "skills");
-  const skillsDetails = await lstat(skillsDirectory).catch((error) => {
-    if (error.code === "ENOENT") return null;
-    throw error;
-  });
-  if (skillsDetails === null) return { agentsDirectory, skillsDirectory, links: [] };
-  if (skillsDetails.isSymbolicLink() || !skillsDetails.isDirectory()) {
-    return { agentsDirectory, skillsDirectory: null, links: [] };
-  }
-
-  const links = [];
-  for (const skillName of LEGACY_TASKCHEF_SKILL_NAMES) {
-    const skillPath = path.join(skillsDirectory, skillName);
-    const details = await lstat(skillPath).catch((error) => {
-      if (error.code === "ENOENT") return null;
-      throw error;
-    });
-    if (details === null) continue;
-    if (!details.isSymbolicLink()) {
-      throw new Error(`legacy TaskChef skill path is not a symlink: ${skillPath}`);
-    }
-    links.push({ name: skillName, path: skillPath });
-  }
-  return { agentsDirectory, skillsDirectory, links };
-}
-
-async function removeLegacySkillLinks(workspaceRoot) {
-  const legacy = await findLegacySkillLinks(workspaceRoot);
-  for (const link of legacy.links) await unlink(link.path);
-  const removedDirectories = [];
-  if (legacy.skillsDirectory && (await readdir(legacy.skillsDirectory)).length === 0) {
-    await rmdir(legacy.skillsDirectory);
-    removedDirectories.push(legacy.skillsDirectory);
-  }
-  if (legacy.agentsDirectory && (await readdir(legacy.agentsDirectory).catch((error) => {
-    if (error.code === "ENOENT") return null;
-    throw error;
-  }))?.length === 0) {
-    await rmdir(legacy.agentsDirectory);
-    removedDirectories.push(legacy.agentsDirectory);
-  }
-  return { removed: legacy.links, removedDirectories };
-}
-
-export async function ensureWorkspaceSkills(workspaceRoot) {
-  const root = await realpath(path.resolve(workspaceRoot));
-  const legacySkills = await removeLegacySkillLinks(root);
-  return {
-    directory: null,
-    skills: TASKCHEF_SKILL_NAMES.map((name) => ({
-      name,
-      path: path.join(SKILLS_SOURCE_ROOT, name),
-      action: "provided-by-plugin",
-    })),
-    legacySkills,
-  };
-}
-
 export async function canonicalGitRoot(projectPath) {
   const requested = await canonicalDirectory(projectPath);
   const { stdout } = await execFile("git", ["rev-parse", "--show-toplevel"], {
@@ -445,7 +363,7 @@ export async function canonicalDirectory(projectPath) {
 async function normalizeProject(
   project,
   index,
-  { checkPath = true, allowLegacyGithubRepo = false } = {},
+  { checkPath = true } = {},
 ) {
   const field = `projects[${index}]`;
   if (!project || typeof project !== "object" || Array.isArray(project)) {
@@ -453,12 +371,7 @@ async function normalizeProject(
   }
   const unexpected = Object.keys(project).find((key) => !PROJECT_FIELDS.has(key));
   if (unexpected) throw new Error(`${field} has unsupported field: ${unexpected}`);
-  const repositoryField = allowLegacyGithubRepo ? "githubRepo" : "githubRepos";
-  const unsupportedRepositoryField = allowLegacyGithubRepo ? "githubRepos" : "githubRepo";
-  if (unsupportedRepositoryField in project) {
-    throw new Error(`${field} has unsupported field: ${unsupportedRepositoryField}`);
-  }
-  for (const required of ["name", "path", "isGitRepository", repositoryField]) {
+  for (const required of ["name", "path", "isGitRepository", "githubRepos"]) {
     if (!(required in project)) throw new Error(`${field} is missing field: ${required}`);
   }
   const name = requireString(project.name, `${field}.name`).trim();
@@ -476,9 +389,7 @@ async function normalizeProject(
       throw new Error(`${field}.path must be a normalized absolute path`);
     }
   }
-  const githubRepos = normalizeGithubRepositories(project[repositoryField], `${field}.${repositoryField}`, {
-    allowLegacyScalar: allowLegacyGithubRepo,
-  });
+  const githubRepos = normalizeGithubRepositories(project.githubRepos, `${field}.githubRepos`);
   const normalized = {
     name,
     path: projectPath,
@@ -496,14 +407,13 @@ async function normalizeProject(
 
 async function normalizeProjects(
   projects,
-  { checkPaths = true, allowLegacyGithubRepo = false } = {},
+  { checkPaths = true } = {},
 ) {
   if (!Array.isArray(projects)) throw new Error("projects must be an array");
   const normalized = [];
   for (const [index, project] of projects.entries()) {
     normalized.push(await normalizeProject(project, index, {
       checkPath: checkPaths,
-      allowLegacyGithubRepo,
     }));
   }
   if (new Set(normalized.map((project) => project.path)).size !== normalized.length) {
@@ -594,15 +504,12 @@ async function inspectProject(input, index = 0) {
 
 export async function validateConfig(config, { checkPaths = true } = {}) {
   requireExactFields(config, CONFIG_FIELDS, "taskchef.json");
-  if (![LEGACY_SCHEMA_VERSION, CURRENT_CONFIG_SCHEMA_VERSION].includes(config.schemaVersion)) {
+  if (config.schemaVersion !== CURRENT_CONFIG_SCHEMA_VERSION) {
     throw new Error("unsupported configuration schemaVersion");
   }
   return {
     schemaVersion: CURRENT_CONFIG_SCHEMA_VERSION,
-    projects: await normalizeProjects(config.projects, {
-      checkPaths,
-      allowLegacyGithubRepo: config.schemaVersion === LEGACY_SCHEMA_VERSION,
-    }),
+    projects: await normalizeProjects(config.projects, { checkPaths }),
   };
 }
 
@@ -630,9 +537,6 @@ export async function initializeWorkspace(workspaceRoot) {
   return withWorkspaceLock(root, async () => {
     const configPath = path.join(root, "taskchef.json");
     const configExists = await managedRegularFileExists(configPath);
-    const storedConfigVersion = configExists
-      ? JSON.parse(await readFile(configPath, "utf8")).schemaVersion
-      : null;
     const config = configExists
       ? await readConfig(root, { checkPaths: false })
       : { schemaVersion: CURRENT_CONFIG_SCHEMA_VERSION, projects: [] };
@@ -640,11 +544,7 @@ export async function initializeWorkspace(workspaceRoot) {
     if (configExists && (await managedRegularFileExists(dispatchPath))) {
       await readDispatchesUnlocked(root);
     }
-    const { legacySkills } = await ensureWorkspaceSkills(root);
     if (!configExists) await writeJsonAtomic(configPath, config, { exclusive: true });
-    else if (storedConfigVersion !== CURRENT_CONFIG_SCHEMA_VERSION) {
-      await writeJsonAtomic(configPath, config);
-    }
     const tasks = await ensureDispatchFile(root);
     const instructions = await ensureWorkspaceInstructions(root).catch(async (error) => {
       if (!configExists) await unlink(configPath).catch(() => {});
@@ -656,14 +556,11 @@ export async function initializeWorkspace(workspaceRoot) {
       workspace: root,
       config: {
         path: configPath,
-        action: !configExists
-          ? "created"
-          : storedConfigVersion === CURRENT_CONFIG_SCHEMA_VERSION ? "unchanged" : "migrated",
+        action: configExists ? "unchanged" : "created",
         value: config,
       },
       tasks,
       instructions,
-      legacySkills,
     };
   });
 }
@@ -780,15 +677,9 @@ export async function removeProject(workspaceRoot, name) {
   });
 }
 
-async function validateDispatchShape(
-  dispatch,
-  name = "task",
-  { allowLegacyHeading = false } = {},
-) {
+async function validateDispatchShape(dispatch, name = "task") {
   const supportedVersions = [
-    LEGACY_SCHEMA_VERSION,
-    PREVIOUS_SCHEMA_VERSION,
-    PREVIOUS_STATEFUL_TASK_SCHEMA_VERSION,
+    PREVIOUS_SELF_LINKING_TASK_SCHEMA_VERSION,
     CURRENT_TASK_SCHEMA_VERSION,
   ];
   if (!supportedVersions.includes(dispatch?.schemaVersion)) {
@@ -796,16 +687,51 @@ async function validateDispatchShape(
   }
   requireExactFields(
     dispatch,
-    dispatch.schemaVersion >= PREVIOUS_STATEFUL_TASK_SCHEMA_VERSION
+    dispatch.schemaVersion >= CURRENT_TASK_SCHEMA_VERSION
       ? DISPATCH_FIELDS
-      : LEGACY_DISPATCH_FIELDS,
+      : STATEFUL_DISPATCH_FIELDS,
     name,
   );
   const id = requireSafeId(dispatch.id, `${name}.id`);
-  const project = await normalizeProject(dispatch.project, 0, {
-    checkPath: false,
-    allowLegacyGithubRepo: dispatch.schemaVersion === LEGACY_SCHEMA_VERSION,
+  const project = await normalizeProject(dispatch.project, 0, { checkPath: false });
+  const status = requireEnum(dispatch.status, TASK_STATUSES, `${name}.status`);
+  const summary = optionalString(dispatch.summary, `${name}.summary`, {
+    maxLength: MAX_RESULT_SUMMARY_LENGTH,
   });
+  const turnId = optionalString(dispatch.turnId, `${name}.turnId`, { maxLength: 256 });
+  const updatedAt = requireTimestamp(dispatch.updatedAt, `${name}.updatedAt`);
+  let lastResult = null;
+  if (dispatch.schemaVersion >= CURRENT_TASK_SCHEMA_VERSION) {
+    if (dispatch.lastResult !== null) {
+      requireExactFields(dispatch.lastResult, LAST_RESULT_FIELDS, `${name}.lastResult`);
+      lastResult = {
+        status: requireEnum(
+          dispatch.lastResult.status,
+          RESULT_STATUSES,
+          `${name}.lastResult.status`,
+        ),
+        summary: optionalString(
+          dispatch.lastResult.summary,
+          `${name}.lastResult.summary`,
+          { maxLength: MAX_RESULT_SUMMARY_LENGTH },
+        ),
+        turnId: optionalString(
+          dispatch.lastResult.turnId,
+          `${name}.lastResult.turnId`,
+          { maxLength: 256 },
+        ),
+        updatedAt: requireTimestamp(
+          dispatch.lastResult.updatedAt,
+          `${name}.lastResult.updatedAt`,
+        ),
+      };
+      if (lastResult.summary === null) {
+        throw new Error(`${name}.lastResult.summary must be a non-empty string`);
+      }
+    }
+  } else if (RESULT_STATUSES.has(status)) {
+    lastResult = { status, summary, turnId, updatedAt };
+  }
   const normalized = {
     schemaVersion: dispatch.schemaVersion,
     id,
@@ -816,39 +742,101 @@ async function validateDispatchShape(
       ? null
       : normalizeDurableThreadId(dispatch.threadId, `${name}.threadId`),
     createdAt: requireTimestamp(dispatch.createdAt, `${name}.createdAt`),
-    status: dispatch.schemaVersion >= PREVIOUS_STATEFUL_TASK_SCHEMA_VERSION
-      ? requireEnum(dispatch.status, TASK_STATUSES, `${name}.status`)
-      : null,
-    summary: dispatch.schemaVersion >= PREVIOUS_STATEFUL_TASK_SCHEMA_VERSION
-      ? optionalString(dispatch.summary, `${name}.summary`, {
-        maxLength: MAX_RESULT_SUMMARY_LENGTH,
-      })
-      : null,
-    turnId: dispatch.schemaVersion >= PREVIOUS_STATEFUL_TASK_SCHEMA_VERSION
-      ? optionalString(dispatch.turnId, `${name}.turnId`, { maxLength: 256 })
-      : null,
-    updatedAt: dispatch.schemaVersion >= PREVIOUS_STATEFUL_TASK_SCHEMA_VERSION
-      ? requireTimestamp(dispatch.updatedAt, `${name}.updatedAt`)
-      : null,
-    updatedBy: dispatch.schemaVersion >= PREVIOUS_STATEFUL_TASK_SCHEMA_VERSION
-      ? requireEnum(dispatch.updatedBy, TASK_UPDATE_SOURCES, `${name}.updatedBy`)
-      : null,
+    status,
+    summary,
+    turnId,
+    updatedAt,
+    updatedBy: requireEnum(dispatch.updatedBy, TASK_UPDATE_SOURCES, `${name}.updatedBy`),
+    lastResult,
   };
+  const isSelfLinkingRecord = normalized.threadId !== null
+    && parseTaskChefMarker(normalized.instruction) === normalized.id;
+  if (isSelfLinkingRecord) {
+    if (normalized.turnId !== null) {
+      normalizeCodexThreadId(normalized.turnId, `${name}.turnId`);
+    }
+    if (normalized.lastResult?.turnId != null) {
+      normalizeCodexThreadId(
+        normalized.lastResult.turnId,
+        `${name}.lastResult.turnId`,
+      );
+    }
+  }
+  if (normalized.schemaVersion >= PREVIOUS_SELF_LINKING_TASK_SCHEMA_VERSION) {
+    if (normalized.threadId === null) {
+      const isLinkPending = normalized.status === "working"
+        && normalized.summary === null
+        && normalized.turnId === null
+        && normalized.lastResult === null
+        && normalized.updatedBy === "dispatcher";
+      const isCreationFailure = normalized.status === "failed"
+        && normalized.summary !== null
+        && normalized.turnId === null
+        && normalized.lastResult?.status === "failed"
+        && normalized.lastResult.turnId === null
+        && normalized.updatedBy === "mcp";
+      if (!isLinkPending && !isCreationFailure) {
+        throw new Error(`${name} has an invalid unlinked lifecycle state`);
+      }
+    } else {
+      if (RESULT_STATUSES.has(normalized.status) && normalized.turnId === null) {
+        throw new Error(`${name}.turnId is required for a linked semantic state`);
+      }
+      if (normalized.lastResult !== null && normalized.lastResult.turnId === null) {
+        throw new Error(`${name}.lastResult.turnId is required for a linked result`);
+      }
+    }
+  }
   if (normalized.status === "working" && normalized.summary !== null) {
     throw new Error(`${name}.summary must be null while status is working`);
   }
   if (RESULT_STATUSES.has(normalized.status) && normalized.summary === null) {
     throw new Error(`${name}.summary is required for status ${normalized.status}`);
   }
+  if (normalized.schemaVersion >= CURRENT_TASK_SCHEMA_VERSION) {
+    if (RESULT_STATUSES.has(normalized.status)) {
+      if (
+        normalized.lastResult === null
+        || normalized.lastResult.status !== normalized.status
+        || normalized.lastResult.summary !== normalized.summary
+        || normalized.lastResult.turnId !== normalized.turnId
+        || normalized.lastResult.updatedAt !== normalized.updatedAt
+      ) {
+        throw new Error(`${name}.lastResult must match the current semantic state`);
+      }
+    }
+    if (
+      normalized.lastResult !== null
+      && Date.parse(normalized.lastResult.updatedAt) < Date.parse(normalized.createdAt)
+    ) {
+      throw new Error(`${name}.lastResult.updatedAt must not be earlier than createdAt`);
+    }
+    if (
+      normalized.lastResult !== null
+      && Date.parse(normalized.lastResult.updatedAt) > Date.parse(normalized.updatedAt)
+    ) {
+      throw new Error(`${name}.lastResult.updatedAt must not be later than updatedAt`);
+    }
+    if (
+      normalized.status === "working"
+      && isSelfLinkingRecord
+      && normalized.lastResult?.turnId != null
+      && (
+        normalized.turnId === null
+        || normalized.turnId <= normalized.lastResult.turnId
+      )
+    ) {
+      throw new Error(`${name}.turnId must be newer than lastResult.turnId while working`);
+    }
+  }
   if (
-    normalized.updatedAt !== null
-    && Date.parse(normalized.updatedAt) < Date.parse(normalized.createdAt)
+    Date.parse(normalized.updatedAt) < Date.parse(normalized.createdAt)
   ) {
     throw new Error(`${name}.updatedAt must not be earlier than createdAt`);
   }
   if (
     normalized.threadId === null &&
-    parseTaskChefMarker(normalized.instruction, { allowLegacyHeading }) !== normalized.id
+    parseTaskChefMarker(normalized.instruction) !== normalized.id
   ) {
     throw new Error(`${name} with a null threadId must contain its exact TaskChef marker`);
   }
@@ -875,9 +863,7 @@ async function parseDispatchRecordsUnlocked(root, content) {
     records.push({
       line,
       raw: value,
-      normalized: await validateDispatchShape(value, `task line ${index + 1}`, {
-        allowLegacyHeading: true,
-      }),
+      normalized: await validateDispatchShape(value, `task line ${index + 1}`),
     });
   }
   const ids = new Set();
@@ -947,6 +933,7 @@ export async function recordTask(workspaceRoot, input, { now } = {}) {
       turnId: null,
       updatedAt: createdAt,
       updatedBy: "dispatcher",
+      lastResult: null,
     });
     const existing = await readDispatchesUnlocked(root);
     if (existing.some((item) => item.id === dispatch.id)) {
@@ -972,53 +959,6 @@ export async function recordTask(workspaceRoot, input, { now } = {}) {
   });
 }
 
-export async function resolveTask(workspaceRoot, taskId, threadId, { now } = {}) {
-  const id = requireSafeId(taskId, "taskId");
-  const durableThreadId = normalizeDurableThreadId(threadId);
-  const root = await realpath(path.resolve(workspaceRoot));
-  return withWorkspaceLock(root, async () => {
-    const records = await readDispatchRecordsUnlocked(root);
-    const dispatches = records.map((record) => record.normalized);
-    const index = dispatches.findIndex((dispatch) => dispatch.id === id);
-    if (index === -1) throw new Error(`task not found: ${id}`);
-    const currentRecord = records[index];
-    if (currentRecord.raw.schemaVersion >= CURRENT_TASK_SCHEMA_VERSION) {
-      throw new Error(`task resolve is only available for legacy pre-self-linking records: ${id}`);
-    }
-    const dispatch = dispatches[index];
-    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 !== null
-      && threadIdentityKey(item.threadId) === threadIdentityKey(durableThreadId)
-    ))) {
-      throw new Error(`threadId is already recorded: ${durableThreadId}`);
-    }
-    const statefulLegacy = currentRecord.raw.schemaVersion === PREVIOUS_STATEFUL_TASK_SCHEMA_VERSION;
-    const rawResolved = statefulLegacy
-      ? {
-        ...currentRecord.raw,
-        threadId: durableThreadId,
-        updatedAt: now ?? new Date().toISOString(),
-        updatedBy: "dispatcher",
-      }
-      : { ...currentRecord.raw, threadId: durableThreadId };
-    const resolved = statefulLegacy
-      ? await validateDispatchShape(rawResolved)
-      : { ...dispatch, threadId: durableThreadId };
-    const lines = records.map((record, recordIndex) => recordIndex === index
-      ? JSON.stringify(rawResolved)
-      : record.line);
-    await writeDispatchLinesAtomic(root, lines);
-    return resolved;
-  });
-}
-
 export async function linkTask(workspaceRoot, taskId, threadId, { now } = {}) {
   const id = requireSafeId(taskId, "taskId");
   const durableThreadId = normalizeCodexThreadId(threadId);
@@ -1028,10 +968,6 @@ export async function linkTask(workspaceRoot, taskId, threadId, { now } = {}) {
     const dispatches = records.map((record) => record.normalized);
     const index = dispatches.findIndex((dispatch) => dispatch.id === id);
     if (index === -1) throw new Error(`task not found: ${id}`);
-    const currentRecord = records[index];
-    if (currentRecord.raw.schemaVersion < CURRENT_TASK_SCHEMA_VERSION) {
-      throw new Error(`link_task accepts only self-linking task records: ${id}`);
-    }
     const dispatch = dispatches[index];
     const sameIdentity = dispatch.threadId?.toLowerCase() === durableThreadId;
     if (sameIdentity && dispatch.updatedBy === "mcp") {
@@ -1041,8 +977,9 @@ export async function linkTask(workspaceRoot, taskId, threadId, { now } = {}) {
       if (dispatch.threadId === durableThreadId) return dispatch;
       const canonical = await validateDispatchShape({
         ...dispatch,
+        schemaVersion: CURRENT_TASK_SCHEMA_VERSION,
         threadId: durableThreadId,
-        updatedAt: now ?? new Date().toISOString(),
+        updatedAt: transitionTimestamp(now, dispatch.updatedAt),
         updatedBy: "mcp",
       });
       const lines = records.map((record, recordIndex) => recordIndex === index
@@ -1071,8 +1008,9 @@ export async function linkTask(workspaceRoot, taskId, threadId, { now } = {}) {
     }
     const linked = await validateDispatchShape({
       ...dispatch,
+      schemaVersion: CURRENT_TASK_SCHEMA_VERSION,
       threadId: durableThreadId,
-      updatedAt: now ?? new Date().toISOString(),
+      updatedAt: transitionTimestamp(now, dispatch.updatedAt),
       updatedBy: "mcp",
     });
     const lines = records.map((record, recordIndex) => recordIndex === index
@@ -1091,22 +1029,53 @@ function dispatchLineWithState(dispatch, patch) {
   });
 }
 
-export async function reportTaskResult(workspaceRoot, input, { now } = {}) {
-  requireExactFields(
-    input,
-    new Set(["taskId", "threadId", "turnId", "status", "summary"]),
-    "task result",
-  );
+function normalizeTaskStateInput(input, { allowWorking }) {
+  const fields = new Set(["taskId", "threadId", "turnId", "status", "summary"]);
+  if (!input || typeof input !== "object" || Array.isArray(input)) {
+    throw new Error("task state must be an object");
+  }
+  const unexpected = Object.keys(input).find((key) => !fields.has(key));
+  if (unexpected) throw new Error(`task state has unsupported field: ${unexpected}`);
+  for (const field of ["taskId", "threadId", "turnId", "status"]) {
+    if (!(field in input)) throw new Error(`task state is missing field: ${field}`);
+  }
   const id = requireSafeId(input.taskId, "taskId");
   const threadId = input.threadId === null
     ? null
     : normalizeDurableThreadId(input.threadId, "threadId");
   const turnId = optionalString(input.turnId, "turnId", { maxLength: 256 });
-  const status = requireEnum(input.status, RESULT_STATUSES, "status");
-  const summary = optionalString(input.summary, "summary", {
+  const status = requireEnum(
+    input.status,
+    allowWorking ? TASK_STATUSES : RESULT_STATUSES,
+    "status",
+  );
+  const summary = optionalString("summary" in input ? input.summary : null, "summary", {
     maxLength: MAX_RESULT_SUMMARY_LENGTH,
   });
-  if (summary === null) throw new Error("summary must be a non-empty string");
+  if (status === "working" && summary !== null) {
+    throw new Error("summary must be null while status is working");
+  }
+  if (status !== "working" && summary === null) {
+    throw new Error(`summary is required for status ${status}`);
+  }
+  return { id, threadId, turnId, status, summary };
+}
+
+function sameLastResult(lastResult, { status, summary, turnId }) {
+  return lastResult !== null
+    && lastResult.status === status
+    && lastResult.summary === summary
+    && lastResult.turnId === turnId;
+}
+
+async function reportTaskStateInternal(
+  workspaceRoot,
+  input,
+  { now, compatibilityAlias = false } = {},
+) {
+  const { id, threadId, turnId, status, summary } = normalizeTaskStateInput(input, {
+    allowWorking: !compatibilityAlias,
+  });
   const root = await realpath(path.resolve(workspaceRoot));
   return withWorkspaceLock(root, async () => {
     const records = await readDispatchRecordsUnlocked(root);
@@ -1115,60 +1084,142 @@ export async function reportTaskResult(workspaceRoot, input, { now } = {}) {
     if (index === -1) throw new Error(`task not found: ${id}`);
     const dispatch = dispatches[index];
     const isSelfLinkingJourney = (
-      records[index].raw.schemaVersion >= CURRENT_TASK_SCHEMA_VERSION
-      && dispatch.threadId !== null
+      dispatch.threadId !== null
       && parseTaskChefMarker(dispatch.instruction) === dispatch.id
     );
-    let resultTurnId = turnId;
+    if (
+      !compatibilityAlias
+      && dispatch.threadId !== null
+      && !isSelfLinkingJourney
+    ) {
+      throw new Error(`report_state accepts only self-linked task records: ${id}`);
+    }
+    let stateTurnId = turnId;
     if (isSelfLinkingJourney) {
       if (dispatch.updatedBy === "dispatcher") {
         throw new Error(`self-linking task must link before reporting a result: ${id}`);
       }
-      resultTurnId = normalizeCodexThreadId(turnId, "turnId");
+      stateTurnId = normalizeCodexThreadId(turnId, "turnId");
     }
     if (dispatch.threadId === null) {
-      if (threadId !== null || resultTurnId !== null || status !== "failed") {
+      if (threadId !== null || stateTurnId !== null || status !== "failed") {
         throw new Error(`task without a durable threadId accepts only failed with null thread/turn IDs: ${id}`);
       }
+      if (!compatibilityAlias) {
+        const rawSchemaVersion = records[index].raw.schemaVersion;
+        const hasCurrentMarker = rawSchemaVersion
+          >= PREVIOUS_SELF_LINKING_TASK_SCHEMA_VERSION
+          && parseTaskChefMarker(dispatch.instruction) === dispatch.id;
+        const isFreshCreationFailure = hasCurrentMarker
+          && dispatch.status === "working"
+          && dispatch.turnId === null
+          && dispatch.lastResult === null
+          && dispatch.updatedBy === "dispatcher";
+        const isIdenticalCreationFailureRetry = hasCurrentMarker
+          && dispatch.status === "failed"
+          && dispatch.turnId === null
+          && dispatch.updatedBy === "mcp"
+          && sameLastResult(dispatch.lastResult, {
+            status,
+            summary,
+            turnId: stateTurnId,
+          });
+        if (!isFreshCreationFailure && !isIdenticalCreationFailureRetry) {
+          throw new Error(`report_state unlinked failure requires a fresh link-pending task: ${id}`);
+        }
+      }
     } else {
       if (threadIdentityKey(threadId) !== threadIdentityKey(dispatch.threadId)) {
         throw new Error(`task result threadId does not match recorded threadId: ${id}`);
       }
-      if (resultTurnId === null) {
-        throw new Error(`task result turnId is required for a linked task: ${id}`);
+      if (stateTurnId === null) {
+        throw new Error(`task state turnId is required for a linked task: ${id}`);
       }
     }
-    if (dispatch.updatedBy === "mcp" && resultTurnId === dispatch.turnId) {
-      if (status === dispatch.status && summary === dispatch.summary) return dispatch;
-      throw new Error(`task turn already has a different semantic result: ${id}`);
+    if (status === "working") {
+      if (dispatch.status === "working" && stateTurnId === dispatch.turnId) return dispatch;
+      if (isSelfLinkingJourney) {
+        if (dispatch.turnId !== null && stateTurnId <= dispatch.turnId) {
+          throw new Error(`working turnId must be newer than the current task turnId: ${id}`);
+        }
+        if (dispatch.lastResult?.turnId != null && stateTurnId <= dispatch.lastResult.turnId) {
+          throw new Error(`working turnId must be newer than the last result turnId: ${id}`);
+        }
+      }
+      const updatedAt = transitionTimestamp(now, dispatch.updatedAt);
+      const updated = await validateDispatchShape({
+        ...dispatch,
+        schemaVersion: CURRENT_TASK_SCHEMA_VERSION,
+        status,
+        summary: null,
+        turnId: stateTurnId,
+        updatedAt,
+        updatedBy: "mcp",
+        lastResult: dispatch.lastResult,
+      });
+      const lines = records.map((record, recordIndex) => recordIndex === index
+        ? dispatchLineWithState(updated, {})
+        : record.line);
+      await writeDispatchLinesAtomic(root, lines);
+      return updated;
     }
     if (
-      isSelfLinkingJourney
-      && dispatch.turnId !== null
-      && resultTurnId <= dispatch.turnId
+      dispatch.status === status
+      && dispatch.turnId === stateTurnId
+      && dispatch.summary === summary
+      && sameLastResult(dispatch.lastResult, { status, summary, turnId: stateTurnId })
     ) {
-      throw new Error(`task result turnId must be newer than the stored turnId: ${id}`);
+      return dispatch;
+    }
+    if (dispatch.turnId === stateTurnId && dispatch.status !== "working") {
+      throw new Error(`task turn already has a different semantic result: ${id}`);
     }
-    const persistedSchemaVersion = records[index].raw.schemaVersion >= CURRENT_TASK_SCHEMA_VERSION
-      ? CURRENT_TASK_SCHEMA_VERSION
-      : PREVIOUS_STATEFUL_TASK_SCHEMA_VERSION;
-    const updated = await validateDispatchShape({
+    if (compatibilityAlias) {
+      const matchesWorkingTurn = dispatch.status === "working"
+        && dispatch.turnId === stateTurnId;
+      if (!matchesWorkingTurn && isSelfLinkingJourney) {
+        if (dispatch.turnId !== null && stateTurnId <= dispatch.turnId) {
+          throw new Error(`task result turnId must be newer than the stored turnId: ${id}`);
+        }
+        if (dispatch.lastResult?.turnId != null && stateTurnId <= dispatch.lastResult.turnId) {
+          throw new Error(`task result turnId must be newer than the last result turnId: ${id}`);
+        }
+      }
+    } else if (dispatch.status !== "working" || dispatch.turnId !== stateTurnId) {
+      throw new Error(`task result must match the current working turnId: ${id}`);
+    }
+    const updatedAt = transitionTimestamp(now, dispatch.updatedAt);
+    const lastResult = { status, summary, turnId: stateTurnId, updatedAt };
+    const candidate = {
       ...dispatch,
-      schemaVersion: persistedSchemaVersion,
+      schemaVersion: CURRENT_TASK_SCHEMA_VERSION,
       status,
       summary,
-      turnId: resultTurnId,
-      updatedAt: now ?? new Date().toISOString(),
+      turnId: stateTurnId,
+      updatedAt,
       updatedBy: "mcp",
-    });
+      lastResult,
+    };
+    const updated = await validateDispatchShape(candidate);
     const lines = records.map((record, recordIndex) => recordIndex === index
-      ? dispatchLineWithState(updated, { schemaVersion: persistedSchemaVersion })
+      ? dispatchLineWithState(updated, {})
       : record.line);
     await writeDispatchLinesAtomic(root, lines);
     return updated;
   });
 }
 
+export async function reportTaskState(workspaceRoot, input, { now } = {}) {
+  return reportTaskStateInternal(workspaceRoot, input, { now });
+}
+
+export async function reportTaskResult(workspaceRoot, input, options = {}) {
+  return reportTaskStateInternal(workspaceRoot, input, {
+    ...options,
+    compatibilityAlias: true,
+  });
+}
+
 export async function readTask(workspaceRoot, taskId) {
   const id = requireSafeId(taskId, "taskId");
   const dispatch = (await listTasks(workspaceRoot)).find((item) => item.id === id);
@@ -1234,12 +1285,5 @@ export async function doctorWorkspace(workspaceRoot) {
     }
     return "managed AGENTS.md instructions current";
   });
-  await check("legacy-skill-links", async () => {
-    const legacy = await findLegacySkillLinks(root);
-    if (legacy.links.length > 0) {
-      throw new Error("legacy TaskChef skill links remain; run workspace init to remove them");
-    }
-    return "no legacy TaskChef skill links";
-  });
   return { workspace: root, ok: checks.every((item) => item.status === "pass"), checks };
 }