taskchef 3.0.2 → 4.0.0

package/skills/taskchef-report/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: taskchef-report
-description: "Report the live state of Codex tasks recorded in a TaskChef task history. Use only when the user asks for status, outcomes, or a report about delegated work. Queries each relevant task once, never polls or waits, and never persists status or results."
+description: "Report the live state of Codex tasks recorded in a TaskChef task history. Use only when the user asks for status, outcomes, or a report about delegated work. Queries each relevant task once, may resolve a nullable thread ID from one exact marker match, never polls or waits, and never persists status or results."
 ---
 
 # TaskChef Report
@@ -23,16 +23,26 @@ all deterministic task-log operations.
      `<plugin-root>/bin/taskchef.js task list --json --workspace <workspace>`
      once, then select matching entries. Ask the user if the match is ambiguous.
    - Use the full list only when the user asks for an overview of the task history.
-2. Query every selected thread exactly once using immediate native snapshots,
-   with no more than eight targets per call.
-3. Summarize the live state and any reported outcome for each requested task.
+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
+   `<plugin-root>/bin/taskchef.js task resolve <task-id> --thread-id <thread-id> --json --workspace <workspace>`.
+   Do not resolve zero or multiple matches. Report unmatched entries as
+   recorded but unresolved and do not pass them to native thread tools.
+3. Query every resolved or previously durable thread exactly once using
+   immediate native snapshots, with no more than eight targets per call.
+4. Summarize the live state and any reported outcome for each requested task.
    Distinguish active work, requests for user input, completed work, and failed
    or partial attempts.
-4. Treat each Codex task as the source of truth. The task log proves that
-   TaskChef created the task, but it does not contain the task's current state.
-5. Never update `tasks.jsonl`. Never persist status, results, transcripts,
-   or hidden reasoning. Do not poll or wait for future activity.
+5. Treat each Codex task as the source of truth. The task log records what
+   TaskChef submitted, but it does not contain the task's current state.
+6. Never edit `tasks.jsonl` directly. Use `task resolve` only for one exact
+   marker match. Never persist status, results, transcripts, or hidden
+   reasoning. Do not poll or wait for future activity.
 
 If the task history is empty, say that TaskChef has not recorded any tasks. If
-a recorded task cannot be read, identify it by task ID and thread ID, then
-continue with the remaining entries.
+a task has no durable thread ID, identify it by task ID and say that its marker
+remains available for later recovery. If a recorded thread cannot be read,
+identify it by task ID and thread ID, then continue with the remaining entries.

package/src/cli.js

@@ -12,6 +12,7 @@ import {
   readTask,
   recordTask,
   removeProject,
+  resolveTask,
 } from "./workspace.js";
 
 async function readStdin() {
@@ -36,6 +37,14 @@ function option(args, name, fallback) {
   return args[index + 1];
 }
 
+function options(args, name) {
+  const values = [];
+  for (let index = 0; index < args.length; index += 1) {
+    if (args[index] === name) values.push(args[index + 1]);
+  }
+  return values;
+}
+
 function validateCommandArgs(
   args,
   startIndex,
@@ -92,7 +101,6 @@ async function initialize(args) {
     `Workspace: ${value.workspace}`,
     `Configuration: ${value.config.action}`,
     `Task log: ${value.tasks.action}`,
-    `Legacy tasks: ${value.legacyTasks.action}`,
     `Instructions: ${value.instructions.action}`,
     `Legacy skill links removed: ${value.legacySkills.removed.length}`,
   ].join("\n"));
@@ -113,6 +121,7 @@ async function projectAdd(args) {
   validateCommandArgs(args, 3, {
     values: ["--workspace", "--name", "--description", "--github-repo"],
     switches: ["--json", "--no-github"],
+    repeatable: ["--github-repo"],
   });
   if (args.includes("--no-github") && args.includes("--github-repo")) {
     throw new Error("--no-github and --github-repo cannot be used together");
@@ -122,8 +131,8 @@ async function projectAdd(args) {
   const description = option(args, "--description", null);
   if (name !== null) input.name = name;
   if (description !== null) input.description = description;
-  if (args.includes("--no-github")) input.githubRepo = null;
-  else if (args.includes("--github-repo")) input.githubRepo = option(args, "--github-repo");
+  if (args.includes("--no-github")) input.githubRepos = [];
+  else if (args.includes("--github-repo")) input.githubRepos = options(args, "--github-repo");
   const project = await addProject(workspaceRoot(args), input);
   print(project, args, (value) => `Added ${value.name}: ${value.path}`);
   return 0;
@@ -152,10 +161,11 @@ async function projectList(args) {
   validateCommandArgs(args, 2, { values: ["--workspace"], switches: ["--json"] });
   const projects = await listProjects(workspaceRoot(args));
   print({ projectCount: projects.length, projects }, args, (value) => table(
-    ["NAME", "KIND", "PATH"],
+    ["NAME", "KIND", "GITHUB REPOSITORIES", "PATH"],
     value.projects.map((project) => [
       project.name,
       project.isGitRepository ? "git" : "folder",
+      project.githubRepos.join(", ") || "-",
       project.path,
     ]),
   ));
@@ -180,6 +190,22 @@ 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 readTask(workspaceRoot(args), args[2]), args);
@@ -224,11 +250,12 @@ Usage:
   taskchef help
   taskchef doctor [--json] [--workspace <path>]
   taskchef workspace init [--json] [--workspace <path>]
-  taskchef project add <path> [--name <name>] [--description <text>] [--github-repo <url> | --no-github] [--json] [--workspace <path>]
+  taskchef project add <path> [--name <name>] [--description <text>] [--github-repo <url> ... | --no-github] [--json] [--workspace <path>]
   taskchef project import [<file> | -] [--replace] [--json] [--workspace <path>]
   taskchef project list [--json] [--workspace <path>]
   taskchef project remove <name> [--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>] [--json] [--workspace <path>]
   taskchef task summary [--json] [--workspace <path>]
@@ -250,6 +277,7 @@ export async function runCli(args) {
   if (args[0] === "project" && args[1] === "list") return projectList(args);
   if (args[0] === "project" && args[1] === "remove") return projectRemove(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/delegation.js

@@ -0,0 +1,555 @@
+import { randomUUID } from "node:crypto";
+
+export const THREAD_RESOLUTION_CHECKPOINTS_MS = Object.freeze([10_000, 29_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;
+
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+
+function requireObject(value, name) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`${name} must be an object`);
+  }
+  return value;
+}
+
+function requireString(value, name) {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new Error(`${name} must be a non-empty string`);
+  }
+  return value;
+}
+
+function requireUuid(value, name = "taskId") {
+  requireString(value, name);
+  if (!UUID_PATTERN.test(value)) throw new Error(`${name} must be a lowercase full UUID`);
+  return value;
+}
+
+function parseToolResult(value, name) {
+  if (typeof value !== "string") return requireObject(value, name);
+  try {
+    return requireObject(JSON.parse(value), name);
+  } catch (error) {
+    if (error instanceof SyntaxError) throw new Error(`${name} must contain valid JSON`);
+    throw error;
+  }
+}
+
+function timestampMilliseconds(value) {
+  if (typeof value !== "number" || !Number.isFinite(value)) return null;
+  return value < 1_000_000_000_000 ? value * 1_000 : value;
+}
+
+function toolIdentifier(value) {
+  if (typeof value !== "string") return null;
+  const normalized = value.trim();
+  return normalized.length > 0 ? normalized : null;
+}
+
+export function isProvisionalThreadId(value) {
+  const id = toolIdentifier(value);
+  return id !== null && id.startsWith("local:");
+}
+
+export function normalizeDurableThreadId(value, name = "threadId") {
+  const id = toolIdentifier(value);
+  if (id === null) throw new Error(`${name} must be a non-empty string`);
+  if (isProvisionalThreadId(id)) {
+    throw new Error(`${name} must be a durable thread ID, not a provisional local ID`);
+  }
+  return id;
+}
+
+function wait(delayMs) {
+  return new Promise((resolve) => setTimeout(resolve, delayMs));
+}
+
+export function taskChefMarker(taskId) {
+  return `# taskchef_id=${requireUuid(taskId)}`;
+}
+
+export function parseTaskChefMarker(instruction) {
+  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;
+}
+
+export function prepareDelegation(instruction, { taskId = randomUUID() } = {}) {
+  requireString(instruction, "instruction");
+  if (parseTaskChefMarker(instruction) !== null) {
+    throw new Error("instruction already contains a TaskChef marker");
+  }
+  const id = requireUuid(taskId);
+  return {
+    id,
+    instruction: `${taskChefMarker(id)}\n\n${instruction}`,
+  };
+}
+
+export function listThreadEntries(result) {
+  const parsed = parseToolResult(result, "list_threads result");
+  const entries = [...(parsed.pinnedThreads ?? []), ...(parsed.threads ?? [])];
+  const unique = new Map();
+  for (const entry of entries) {
+    const id = toolIdentifier(entry?.id);
+    if (id !== null && !unique.has(id)) {
+      unique.set(id, { ...entry, id });
+    }
+  }
+  return [...unique.values()];
+}
+
+export function structuredDelegatedInputs(result) {
+  const parsed = parseToolResult(result, "read_thread result");
+  const inputs = [];
+  for (const turn of parsed.turns ?? []) {
+    for (const item of turn?.items ?? []) {
+      if (item?.type !== "userMessage") continue;
+      for (const part of item.content ?? []) {
+        if (typeof part?.codexDelegation?.input === "string") {
+          inputs.push(part.codexDelegation.input);
+        }
+      }
+    }
+  }
+  return inputs;
+}
+
+export function hasExactTaskChefMarker(result, taskId) {
+  const marker = taskChefMarker(taskId);
+  return structuredDelegatedInputs(result).some(
+    (input) => input.split(/\r?\n/, 1)[0] === marker,
+  );
+}
+
+export function filterThreadCandidates(result, {
+  baselineThreadIds = new Set(),
+  excludedThreadIds = new Set(),
+  hostId = null,
+  projectId = null,
+  title = null,
+  createdAfter = null,
+  environmentType = null,
+} = {}) {
+  const minimumCreatedAt = createdAfter === null
+    ? null
+    : timestampMilliseconds(createdAfter) - THREAD_RESOLUTION_CLOCK_SKEW_MS;
+  const candidates = listThreadEntries(result).filter((thread) => {
+    if (
+      baselineThreadIds.has(thread.id)
+      || excludedThreadIds.has(thread.id)
+      || isProvisionalThreadId(thread.id)
+      || thread.kind !== "codex"
+    ) return false;
+    if (hostId !== null && thread.hostId !== undefined && thread.hostId !== hostId) return false;
+    if (projectId !== null && thread.projectId !== undefined && thread.projectId !== projectId) {
+      return false;
+    }
+    const candidateEnvironmentType = thread.environment?.type
+      ?? thread.environmentType
+      ?? thread.backing?.environment?.type;
+    if (
+      environmentType !== null &&
+      candidateEnvironmentType !== undefined &&
+      candidateEnvironmentType !== environmentType
+    ) return false;
+    const candidateTime = timestampMilliseconds(thread.createdAt ?? thread.updatedAt);
+    if (minimumCreatedAt !== null && candidateTime !== null && candidateTime < minimumCreatedAt) {
+      return false;
+    }
+    return true;
+  });
+  if (title === null) return candidates;
+  return candidates.sort((left, right) =>
+    Number(right.title === title) - Number(left.title === title));
+}
+
+function validateResolutionSchedule(checkpointsMs, timeoutMs) {
+  if (!Array.isArray(checkpointsMs) || checkpointsMs.length === 0) {
+    throw new Error("checkpointsMs must contain at least one checkpoint");
+  }
+  if (!Number.isInteger(timeoutMs) || timeoutMs < 1) {
+    throw new Error("timeoutMs must be positive");
+  }
+  let previous = 0;
+  for (const checkpoint of checkpointsMs) {
+    if (!Number.isInteger(checkpoint) || checkpoint <= previous || checkpoint > timeoutMs) {
+      throw new Error("checkpointsMs must be strictly increasing positive integers within timeoutMs");
+    }
+    previous = checkpoint;
+  }
+}
+
+async function inspectCandidates(candidates, {
+  readThread,
+  taskId,
+  attempt,
+  canVerify = () => true,
+}) {
+  const inspected = await Promise.all(candidates.map(async (candidate) => {
+    try {
+      const readResult = await readThread({
+        threadId: candidate.id,
+        ...(candidate.hostId ? { hostId: candidate.hostId } : {}),
+        turnLimit: 1,
+        includeOutputs: false,
+      });
+      if (!canVerify()) {
+        return { candidate, matches: false, error: null };
+      }
+      return {
+        candidate,
+        matches: hasExactTaskChefMarker(readResult, taskId),
+        error: null,
+      };
+    } catch (error) {
+      return {
+        candidate,
+        matches: false,
+        error: {
+          attempt,
+          operation: "readThread",
+          threadId: candidate.id,
+          message: error instanceof Error ? error.message : String(error),
+        },
+      };
+    }
+  }));
+  return {
+    exactMatches: inspected.filter((item) => item.matches).map((item) => item.candidate),
+    errors: inspected.flatMap((item) => item.error === null ? [] : [item.error]),
+  };
+}
+
+export async function createAndRecordDelegation({
+  project,
+  title,
+  instruction,
+  target,
+  expected = {},
+  createThread,
+  listThreads,
+  readThread,
+  recordTask,
+  resolveRecordedTask = null,
+  resolveProvisionalThread = null,
+  taskId = randomUUID(),
+  checkpointsMs = THREAD_RESOLUTION_CHECKPOINTS_MS,
+  timeoutMs = THREAD_RESOLUTION_TIMEOUT_MS,
+  recentLimit = THREAD_RESOLUTION_RECENT_LIMIT,
+  now = Date.now,
+  waitImpl = wait,
+}) {
+  requireString(project, "project");
+  requireString(title, "title");
+  requireObject(target, "target");
+  for (const [value, name] of [
+    [createThread, "createThread"],
+    [listThreads, "listThreads"],
+    [readThread, "readThread"],
+    [recordTask, "recordTask"],
+  ]) {
+    if (typeof value !== "function") throw new Error(`${name} must be a function`);
+  }
+  if (resolveProvisionalThread !== null && typeof resolveProvisionalThread !== "function") {
+    throw new Error("resolveProvisionalThread must be a function or null");
+  }
+  if (resolveRecordedTask !== null && typeof resolveRecordedTask !== "function") {
+    throw new Error("resolveRecordedTask must be a function or null");
+  }
+  validateResolutionSchedule(checkpointsMs, timeoutMs);
+
+  const prepared = prepareDelegation(instruction, { taskId });
+  const discoveryErrors = [];
+  const createdAfter = now();
+  const createResult = parseToolResult(await createThread({
+    prompt: prepared.instruction,
+    title,
+    target,
+  }), "create_thread result");
+  const clientThreadId = toolIdentifier(createResult.clientThreadId);
+  const pendingWorktreeId = toolIdentifier(createResult.pendingWorktreeId);
+  const returnedThreadId = toolIdentifier(createResult.threadId);
+  const returnedProvisionalId = isProvisionalThreadId(returnedThreadId)
+    ? returnedThreadId
+    : null;
+  const provisional = clientThreadId ?? pendingWorktreeId ?? returnedProvisionalId;
+  const resolutionStartedAt = provisional === null ? null : now();
+  const provisionalIds = new Set([
+    clientThreadId,
+    pendingWorktreeId,
+    returnedProvisionalId,
+  ].filter(Boolean));
+  const durableThreadId = !isProvisionalThreadId(returnedThreadId)
+    && !provisionalIds.has(returnedThreadId)
+    ? returnedThreadId
+    : null;
+
+  if (durableThreadId !== null) {
+    await recordTask({
+      id: prepared.id,
+      project,
+      title,
+      instruction: prepared.instruction,
+      threadId: durableThreadId,
+    });
+    return {
+      status: "recorded",
+      resolution: "immediate",
+      ...prepared,
+      threadId: durableThreadId,
+      hostId: createResult.hostId ?? expected.hostId ?? null,
+      provisional,
+      attempts: 0,
+      discoveryErrors,
+    };
+  }
+
+  if (provisional === null) {
+    await recordTask({
+      id: prepared.id,
+      project,
+      title,
+      instruction: prepared.instruction,
+      threadId: null,
+    });
+    return {
+      status: "recorded-unresolved",
+      reason: "create-returned-no-thread-identifier",
+      ...prepared,
+      threadId: null,
+      provisional: null,
+      attempts: 0,
+      matchingThreadIds: [],
+      discoveryErrors,
+    };
+  }
+
+  await recordTask({
+    id: prepared.id,
+    project,
+    title,
+    instruction: prepared.instruction,
+    threadId: null,
+  });
+
+  if (resolveRecordedTask === null) {
+    return {
+      status: "recorded-unresolved",
+      reason: "task-resolution-unavailable",
+      ...prepared,
+      threadId: null,
+      provisional,
+      attempts: 0,
+      matchingThreadIds: [],
+      discoveryErrors,
+    };
+  }
+
+  const resolutionDeadline = resolutionStartedAt + timeoutMs;
+  let deadlineExpired = false;
+  const hasResolutionTime = () => {
+    if (now() < resolutionDeadline) return true;
+    deadlineExpired = true;
+    return false;
+  };
+
+  const acceptResolvedThread = async (thread, resolution, attempt, { verified = false } = {}) => {
+    const threadId = toolIdentifier(thread.id);
+    if (
+      threadId === null
+      || provisionalIds.has(threadId)
+      || isProvisionalThreadId(threadId)
+    ) {
+      discoveryErrors.push({
+        attempt,
+        operation: "validateThreadId",
+        ...(threadId === null ? {} : { threadId }),
+        message: "resolved threadId is not a durable identifier",
+      });
+      return null;
+    }
+    const durableThread = { ...thread, id: threadId };
+    if (!hasResolutionTime()) return null;
+    if (!verified) {
+      const inspected = await inspectCandidates([durableThread], {
+        readThread,
+        taskId: prepared.id,
+        attempt,
+        canVerify: hasResolutionTime,
+      });
+      discoveryErrors.push(...inspected.errors);
+      if (inspected.exactMatches.length !== 1 || inspected.errors.length > 0) return null;
+    }
+    if (!hasResolutionTime()) return null;
+    try {
+      await resolveRecordedTask({ id: prepared.id, threadId });
+    } catch (error) {
+      discoveryErrors.push({
+        attempt,
+        operation: "resolveRecordedTask",
+        threadId,
+        message: error instanceof Error ? error.message : String(error),
+      });
+      return null;
+    }
+    return {
+      status: "recorded",
+      resolution,
+      ...prepared,
+      threadId,
+      hostId: durableThread.hostId ?? expected.hostId ?? null,
+      provisional,
+      attempts: attempt,
+      discoveryErrors,
+    };
+  };
+
+  if (resolveProvisionalThread !== null) {
+    let nativeResult = null;
+    let nativeAttempts = 0;
+    const remainingTimeoutMs = timeoutMs - (now() - resolutionStartedAt);
+    if (remainingTimeoutMs > 0) {
+      nativeAttempts = 1;
+      try {
+        const nativeResponse = await resolveProvisionalThread({
+          provisionalId: provisional,
+          ...(clientThreadId ? { clientThreadId } : {}),
+          ...(pendingWorktreeId ? { pendingWorktreeId } : {}),
+          timeoutMs: remainingTimeoutMs,
+        });
+        if (hasResolutionTime()) {
+          nativeResult = parseToolResult(nativeResponse, "provisional thread resolver result");
+        }
+      } catch (error) {
+        if (hasResolutionTime()) {
+          discoveryErrors.push({
+            attempt: 1,
+            operation: "resolveProvisionalThread",
+            message: error instanceof Error ? error.message : String(error),
+          });
+        }
+      }
+    }
+    hasResolutionTime();
+    const nativeThreadId = toolIdentifier(nativeResult?.threadId);
+    if (nativeThreadId !== null) {
+      const resolved = await acceptResolvedThread({
+        id: nativeThreadId,
+        hostId: nativeResult.hostId ?? expected.hostId ?? null,
+      }, "native", 1);
+      if (resolved !== null) return resolved;
+    }
+    return {
+      status: "recorded-unresolved",
+      reason: discoveryErrors.length > 0
+        ? "thread-discovery-error"
+        : deadlineExpired
+          ? "resolution-deadline-exhausted"
+          : "native-resolution-unresolved",
+      ...prepared,
+      threadId: null,
+      provisional,
+      attempts: nativeAttempts,
+      matchingThreadIds: [],
+      discoveryErrors,
+    };
+  }
+
+  let exactMatches = [];
+  let ambiguousMatches = [];
+  let attemptsMade = 0;
+  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;
+    if (remainingDelayMs > 0) {
+      try {
+        await waitImpl(remainingDelayMs);
+      } catch (error) {
+        discoveryErrors.push({
+          attempt,
+          operation: "wait",
+          message: error instanceof Error ? error.message : String(error),
+        });
+        break;
+      }
+    }
+    if (!hasResolutionTime()) break;
+    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,
+        });
+      }
+    } catch (error) {
+      if (hasResolutionTime()) {
+        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
+      && ambiguousMatches.length === 0
+      && !attemptFailed
+      && discoveryErrors.length === 0
+    ) {
+      const resolved = await acceptResolvedThread(
+        exactMatches[0],
+        "discovered",
+        attempt,
+        { verified: true },
+      );
+      if (resolved !== null) return resolved;
+    }
+  }
+
+  const reason = ambiguousMatches.length > 1
+    ? "multiple-exact-marker-matches"
+    : discoveryErrors.length > 0
+      ? "thread-discovery-error"
+      : deadlineExpired
+        ? "resolution-deadline-exhausted"
+        : "no-exact-marker-match";
+  return {
+    status: "recorded-unresolved",
+    reason,
+    ...prepared,
+    threadId: null,
+    provisional,
+    attempts: attemptsMade,
+    discoveryErrors,
+    matchingThreadIds: (ambiguousMatches.length > 1 ? ambiguousMatches : exactMatches)
+      .map((thread) => thread.id),
+  };
+}