@tea-agent/loop-agent 0.12.0 → 0.13.0-beta.0

package/dist/worker/pool/migrate-state.js

@@ -0,0 +1,303 @@
+import { randomUUID } from "node:crypto";
+import { copyFile, mkdir, readFile, rename, rm, unlink, writeFile, } from "node:fs/promises";
+import path from "node:path";
+import { diagnoseTaskPoolStates, loadOperatorMapping, } from "./doctor.js";
+import { getEventsJsonlPath, getLegacyTaskStatePath, getRunsJsonlPath, getTaskPoolRoot, getTaskStatePath, pathExists, sha256File, sha256Text, } from "./run-store.js";
+import { TASK_POOL_STATE_ERROR_CODES, TaskPoolStateError, } from "./types.js";
+/**
+ * Migrate legacy flat Task Pool states to feature-scoped v2.
+ * Defaults to dry-run (zero writes). Apply requires --owner and --reason.
+ */
+export async function migrateTaskPoolStates(input) {
+    const apply = input.apply === true;
+    const migrationId = input.migrationId ??
+        `migration-${(input.now ?? new Date()).toISOString().replace(/[:.]/g, "-")}-${randomUUID().slice(0, 8)}`;
+    const mapping = input.mapping ?? (await loadOperatorMapping(input.mappingPath));
+    const doctor = await diagnoseTaskPoolStates(input.repoRoot, { mapping });
+    const planned = [];
+    const skipped = [];
+    for (const item of doctor.legacy) {
+        if (item.resolution === "ambiguous") {
+            skipped.push({
+                taskId: item.taskId,
+                reason: item.detail ?? "identity ambiguous",
+                code: TASK_POOL_STATE_ERROR_CODES.IDENTITY_AMBIGUOUS,
+            });
+            continue;
+        }
+        if (item.resolution === "unresolved" || !item.featureId) {
+            skipped.push({
+                taskId: item.taskId,
+                reason: item.detail ?? "no unique identity evidence",
+                code: TASK_POOL_STATE_ERROR_CODES.MIGRATION_REQUIRED,
+            });
+            continue;
+        }
+        const ref = {
+            featureId: item.featureId,
+            taskId: item.taskId,
+        };
+        const v2Path = getTaskStatePath(input.repoRoot, ref);
+        const alreadyMigrated = await pathExists(v2Path);
+        if (alreadyMigrated) {
+            // Idempotent: if v2 already exists with matching identity, skip write.
+            planned.push({
+                taskId: item.taskId,
+                legacyPath: item.legacyPath,
+                legacySha256: item.sha256,
+                featureId: item.featureId,
+                v2Path,
+                resolution: item.resolution,
+                alreadyMigrated: true,
+            });
+            continue;
+        }
+        // Conflict: v2 path occupied by different content is handled at apply time.
+        planned.push({
+            taskId: item.taskId,
+            legacyPath: item.legacyPath,
+            legacySha256: item.sha256,
+            featureId: item.featureId,
+            v2Path,
+            resolution: item.resolution,
+            alreadyMigrated: false,
+        });
+    }
+    const runsPath = getRunsJsonlPath(input.repoRoot);
+    const eventsPath = getEventsJsonlPath(input.repoRoot);
+    const runsHashBefore = (await pathExists(runsPath))
+        ? await sha256File(runsPath)
+        : null;
+    const eventsHashBefore = (await pathExists(eventsPath))
+        ? await sha256File(eventsPath)
+        : null;
+    if (!apply) {
+        return {
+            schemaVersion: 1,
+            mode: "dry-run",
+            status: planned.length === 0 && skipped.length === 0 ? "noop" : "planned",
+            migrationId,
+            planned,
+            skipped,
+            jsonlUnchanged: { runs: true, events: true },
+            doctor,
+        };
+    }
+    if (!input.owner?.trim()) {
+        throw new TaskPoolStateError(TASK_POOL_STATE_ERROR_CODES.CONFLICT, "pool migrate-state --apply requires a non-empty --owner");
+    }
+    if (!input.reason?.trim()) {
+        throw new TaskPoolStateError(TASK_POOL_STATE_ERROR_CODES.CONFLICT, "pool migrate-state --apply requires a non-empty --reason");
+    }
+    if (skipped.some((item) => item.code === TASK_POOL_STATE_ERROR_CODES.IDENTITY_AMBIGUOUS)) {
+        return {
+            schemaVersion: 1,
+            mode: "apply",
+            status: "failed",
+            migrationId,
+            owner: input.owner,
+            reason: input.reason,
+            planned,
+            skipped,
+            jsonlUnchanged: { runs: true, events: true },
+            doctor,
+            error: {
+                code: TASK_POOL_STATE_ERROR_CODES.IDENTITY_AMBIGUOUS,
+                message: "refusing apply while any legacy identity is ambiguous",
+            },
+        };
+    }
+    const actionable = planned.filter((item) => !item.alreadyMigrated);
+    if (actionable.length === 0 && planned.every((item) => item.alreadyMigrated)) {
+        // Idempotent re-run: move any remaining legacy files that match already-migrated v2.
+        // If legacy still present with alreadyMigrated, still archive them.
+    }
+    const artifactDir = path.join(getTaskPoolRoot(input.repoRoot), "artifacts", "migrations", migrationId);
+    const beforeDir = path.join(artifactDir, "before");
+    const stagingDir = path.join(artifactDir, "staging");
+    const writtenV2 = [];
+    const movedLegacy = [];
+    try {
+        await mkdir(beforeDir, { recursive: true });
+        await mkdir(stagingDir, { recursive: true });
+        // Stage all v2 payloads first.
+        const staged = [];
+        for (const item of planned) {
+            const legacyBytes = await readFile(item.legacyPath);
+            const legacyText = legacyBytes.toString("utf-8");
+            const hash = await sha256Text(legacyText);
+            if (hash !== item.legacySha256) {
+                throw new TaskPoolStateError(TASK_POOL_STATE_ERROR_CODES.CONFLICT, `legacy state changed during migration: ${item.taskId}`);
+            }
+            const parsed = JSON.parse(legacyText);
+            const payload = {
+                ...parsed,
+                schemaVersion: 2,
+                featureId: item.featureId,
+                taskId: item.taskId,
+            };
+            const stagedPath = path.join(stagingDir, `${item.featureId}__${item.taskId}.json`);
+            await writeFile(stagedPath, `${JSON.stringify(payload, null, 2)}\n`, "utf-8");
+            staged.push({ item, stagedPath, payload, legacyBytes });
+        }
+        // Conflict checks against existing v2 targets.
+        for (const entry of staged) {
+            if (await pathExists(entry.item.v2Path)) {
+                const existing = JSON.parse(await readFile(entry.item.v2Path, "utf-8"));
+                if (existing.featureId === entry.item.featureId &&
+                    existing.taskId === entry.item.taskId) {
+                    // already migrated — ok, will only archive legacy
+                    continue;
+                }
+                throw new TaskPoolStateError(TASK_POOL_STATE_ERROR_CODES.CONFLICT, `v2 target already exists with different identity: ${entry.item.v2Path}`);
+            }
+        }
+        // Atomic rename of staged v2 files.
+        for (const entry of staged) {
+            if (await pathExists(entry.item.v2Path)) {
+                // already migrated
+                continue;
+            }
+            await mkdir(path.dirname(entry.item.v2Path), { recursive: true });
+            const tempPath = `${entry.item.v2Path}.${randomUUID()}.tmp`;
+            try {
+                await copyFile(entry.stagedPath, tempPath);
+                await input.faultInjector?.("before-v2-rename", entry.item.taskId);
+                await rename(tempPath, entry.item.v2Path);
+                writtenV2.push(entry.item.v2Path);
+            }
+            finally {
+                await unlink(tempPath).catch(() => { });
+            }
+        }
+        await input.faultInjector?.("after-partial-v2");
+        // Move legacy into artifact before/.
+        for (const entry of staged) {
+            const dest = path.join(beforeDir, path.basename(entry.item.legacyPath));
+            await input.faultInjector?.("before-legacy-move", entry.item.taskId);
+            if (await pathExists(entry.item.legacyPath)) {
+                // Preserve exact bytes
+                await writeFile(dest, entry.legacyBytes);
+                await unlink(entry.item.legacyPath);
+                movedLegacy.push({
+                    from: entry.item.legacyPath,
+                    to: dest,
+                    originalBytes: entry.legacyBytes,
+                });
+            }
+        }
+        const mappingDoc = {
+            schemaVersion: 1,
+            migrationId,
+            items: planned.map((item) => ({
+                taskId: item.taskId,
+                featureId: item.featureId,
+                resolution: item.resolution,
+                legacySha256: item.legacySha256,
+                v2Path: item.v2Path,
+                alreadyMigrated: item.alreadyMigrated,
+            })),
+            skipped,
+        };
+        const manifest = {
+            schemaVersion: 1,
+            migrationId,
+            owner: input.owner,
+            reason: input.reason,
+            appliedAt: (input.now ?? new Date()).toISOString(),
+            plannedCount: planned.length,
+            skippedCount: skipped.length,
+        };
+        const resultDoc = {
+            schemaVersion: 1,
+            status: "applied",
+            migrationId,
+            writtenV2,
+            archivedLegacy: movedLegacy.map((item) => item.to),
+        };
+        await writeFile(path.join(artifactDir, "mapping.json"), `${JSON.stringify(mappingDoc, null, 2)}\n`, "utf-8");
+        await writeFile(path.join(artifactDir, "manifest.json"), `${JSON.stringify(manifest, null, 2)}\n`, "utf-8");
+        await writeFile(path.join(artifactDir, "result.json"), `${JSON.stringify(resultDoc, null, 2)}\n`, "utf-8");
+        // Clean staging
+        await rm(stagingDir, { recursive: true, force: true }).catch(() => { });
+        const runsHashAfter = (await pathExists(runsPath))
+            ? await sha256File(runsPath)
+            : null;
+        const eventsHashAfter = (await pathExists(eventsPath))
+            ? await sha256File(eventsPath)
+            : null;
+        return {
+            schemaVersion: 1,
+            mode: "apply",
+            status: "applied",
+            migrationId,
+            owner: input.owner,
+            reason: input.reason,
+            planned,
+            skipped,
+            artifactDir,
+            jsonlUnchanged: {
+                runs: runsHashBefore === runsHashAfter,
+                events: eventsHashBefore === eventsHashAfter,
+            },
+            doctor,
+        };
+    }
+    catch (error) {
+        // Full rollback: restore legacy, remove half-written v2.
+        for (const v2Path of writtenV2) {
+            await unlink(v2Path).catch(() => { });
+        }
+        for (const moved of movedLegacy) {
+            await writeFile(moved.from, moved.originalBytes).catch(() => { });
+            await unlink(moved.to).catch(() => { });
+        }
+        // Also restore any legacy that was deleted without movedLegacy tracking
+        // (should not happen with current flow).
+        for (const item of planned) {
+            if (!(await pathExists(item.legacyPath))) {
+                // try recover from beforeDir if present
+                const dest = path.join(beforeDir, path.basename(item.legacyPath));
+                if (await pathExists(dest)) {
+                    await copyFile(dest, item.legacyPath).catch(() => { });
+                }
+            }
+            if (!item.alreadyMigrated &&
+                (await pathExists(item.v2Path)) &&
+                writtenV2.includes(item.v2Path)) {
+                await unlink(item.v2Path).catch(() => { });
+            }
+        }
+        await rm(stagingDir, { recursive: true, force: true }).catch(() => { });
+        const detail = error instanceof Error ? error.message : String(error);
+        const code = error instanceof TaskPoolStateError
+            ? error.code
+            : TASK_POOL_STATE_ERROR_CODES.CONFLICT;
+        return {
+            schemaVersion: 1,
+            mode: "apply",
+            status: "failed",
+            migrationId,
+            owner: input.owner,
+            reason: input.reason,
+            planned,
+            skipped,
+            artifactDir,
+            jsonlUnchanged: { runs: true, events: true },
+            doctor,
+            error: { code, message: detail },
+        };
+    }
+}
+/** Helper for tests: write a legacy flat state file without going through writeTaskPoolState. */
+export async function writeLegacyTaskPoolState(repoRoot, state) {
+    const statePath = getLegacyTaskStatePath(repoRoot, state.taskId);
+    await mkdir(path.dirname(statePath), { recursive: true });
+    const payload = {
+        schemaVersion: 1,
+        ...state,
+    };
+    delete payload.featureId;
+    await writeFile(statePath, `${JSON.stringify(payload, null, 2)}\n`, "utf-8");
+    return statePath;
+}

package/dist/worker/pool/run-store.js

@@ -1,7 +1,9 @@
-import { randomUUID } from "node:crypto";
-import { appendFile, mkdir, readFile, readdir, rename, unlink, writeFile } from "node:fs/promises";
+import { createHash, randomUUID } from "node:crypto";
+import { appendFile, mkdir, readFile, readdir, rename, stat, unlink, writeFile, } from "node:fs/promises";
 import path from "node:path";
+import { TASK_POOL_STATE_ERROR_CODES, TaskPoolStateError, } from "./types.js";
 export const TASK_POOL_RELATIVE_ROOT = ".harness/task-pool";
+const SAFE_TASK_POOL_ID = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
 export function getTaskPoolRoot(repoRoot) {
     return path.join(repoRoot, ...TASK_POOL_RELATIVE_ROOT.split("/"));
 }
@@ -11,8 +13,41 @@ export function getRunsJsonlPath(repoRoot) {
 export function getEventsJsonlPath(repoRoot) {
     return path.join(getTaskPoolRoot(repoRoot), "events.jsonl");
 }
-export function getTaskStatePath(repoRoot, taskId) {
-    return path.join(getTaskPoolRoot(repoRoot), "states", `${taskId}.json`);
+export function getStatesRoot(repoRoot) {
+    return path.join(getTaskPoolRoot(repoRoot), "states");
+}
+/**
+ * Fail-closed id check for Task Pool path segments.
+ * Mirrors follow-up runtime id charset without importing that module.
+ */
+export function assertSafeTaskPoolId(value, label) {
+    if (typeof value !== "string" || value.length === 0 || !SAFE_TASK_POOL_ID.test(value)) {
+        throw new TaskPoolStateError(TASK_POOL_STATE_ERROR_CODES.UNSAFE_ID, `${label} contains unsafe path characters: ${JSON.stringify(value)}`);
+    }
+}
+function assertWithinStatesRoot(repoRoot, candidatePath) {
+    const statesRoot = path.resolve(getStatesRoot(repoRoot));
+    const resolved = path.resolve(candidatePath);
+    const relative = path.relative(statesRoot, resolved);
+    if (relative.startsWith("..") || path.isAbsolute(relative)) {
+        throw new TaskPoolStateError(TASK_POOL_STATE_ERROR_CODES.PATH_MISMATCH, `Task Pool state path escapes states root: ${candidatePath}`);
+    }
+}
+export function getTaskStatePath(repoRoot, refOrTaskId) {
+    if (typeof refOrTaskId === "string") {
+        assertSafeTaskPoolId(refOrTaskId, "taskId");
+        const statePath = path.join(getStatesRoot(repoRoot), `${refOrTaskId}.json`);
+        assertWithinStatesRoot(repoRoot, statePath);
+        return statePath;
+    }
+    assertSafeTaskPoolId(refOrTaskId.featureId, "featureId");
+    assertSafeTaskPoolId(refOrTaskId.taskId, "taskId");
+    const statePath = path.join(getStatesRoot(repoRoot), refOrTaskId.featureId, `${refOrTaskId.taskId}.json`);
+    assertWithinStatesRoot(repoRoot, statePath);
+    return statePath;
+}
+export function getLegacyTaskStatePath(repoRoot, taskId) {
+    return getTaskStatePath(repoRoot, taskId);
 }
 export async function recordTaskPoolRun(input) {
     await ensurePoolDirs(input.repoRoot);
@@ -30,10 +65,12 @@ export async function findRunByWorkerRunId(repoRoot, workerRunId) {
 }
 /**
  * Explicitly requeue a failed task without deleting or rewriting prior evidence.
- * The runner consumes `retryOfWorkerRunId` and derives a guaranteed fresh run id.
+ * Prefer explicit featureId. Bare taskId is allowed only when exactly one v2 state matches.
  */
 export async function prepareTaskPoolRetry(input) {
-    const current = await readTaskPoolState(input.repoRoot, input.taskId);
+    const featureId = await resolveRetryFeatureId(input.repoRoot, input.taskId, input.featureId);
+    const ref = { featureId, taskId: input.taskId };
+    const current = await readTaskPoolState(input.repoRoot, ref);
     if (!current) {
         throw new Error(`cannot retry ${input.taskId}: Task Pool state does not exist`);
     }
@@ -46,12 +83,15 @@ export async function prepareTaskPoolRetry(input) {
     const retryRequestedAt = (input.now ?? new Date()).toISOString();
     const result = {
         taskId: input.taskId,
+        featureId,
         status: "Ready",
         previousWorkerRunId: current.workerRunId,
         retryRequestedAt,
         ...(input.reason ? { reason: input.reason } : {}),
     };
     await writeTaskPoolState(input.repoRoot, {
+        schemaVersion: 2,
+        featureId,
         taskId: current.taskId,
         status: "Ready",
         updatedAt: retryRequestedAt,
@@ -65,31 +105,72 @@ export async function prepareTaskPoolRetry(input) {
         at: retryRequestedAt,
         type: "task-retry-requested",
         taskId: input.taskId,
+        featureId,
         previousWorkerRunId: current.workerRunId,
         ...(input.reason ? { reason: input.reason } : {}),
     });
     return result;
 }
-export async function readTaskPoolState(repoRoot, taskId) {
-    const statePath = getTaskStatePath(repoRoot, taskId);
+async function resolveRetryFeatureId(repoRoot, taskId, featureId) {
+    if (featureId) {
+        assertSafeTaskPoolId(featureId, "featureId");
+        return featureId;
+    }
+    const legacyPath = getLegacyTaskStatePath(repoRoot, taskId);
+    if (await pathExists(legacyPath)) {
+        throw new TaskPoolStateError(TASK_POOL_STATE_ERROR_CODES.MIGRATION_REQUIRED, `cannot retry ${taskId}: legacy state requires migration`);
+    }
+    const matches = (await listTaskPoolStates(repoRoot)).filter((state) => state.taskId === taskId);
+    if (matches.length === 1 && matches[0]?.featureId) {
+        return matches[0].featureId;
+    }
+    if (matches.length > 1) {
+        throw new TaskPoolStateError(TASK_POOL_STATE_ERROR_CODES.IDENTITY_AMBIGUOUS, `cannot retry ${taskId}: multiple feature-scoped states exist`);
+    }
+    throw new TaskPoolStateError(TASK_POOL_STATE_ERROR_CODES.FEATURE_REQUIRED, `cannot retry ${taskId}: featureId is required when no unique v2 state exists`);
+}
+export async function readTaskPoolState(repoRoot, refOrTaskId) {
+    if (typeof refOrTaskId === "string") {
+        const statePath = getTaskStatePath(repoRoot, refOrTaskId);
+        try {
+            return JSON.parse(await readFile(statePath, "utf-8"));
+        }
+        catch (error) {
+            if (isNotFound(error))
+                return undefined;
+            throw error;
+        }
+    }
+    const statePath = getTaskStatePath(repoRoot, refOrTaskId);
+    let raw;
     try {
-        return JSON.parse(await readFile(statePath, "utf-8"));
+        raw = await readFile(statePath, "utf-8");
     }
     catch (error) {
         if (isNotFound(error))
             return undefined;
         throw error;
     }
+    const state = JSON.parse(raw);
+    if (state.taskId !== refOrTaskId.taskId ||
+        state.featureId !== refOrTaskId.featureId) {
+        throw new TaskPoolStateError(TASK_POOL_STATE_ERROR_CODES.PATH_MISMATCH, `Task Pool state path/content identity mismatch at ${statePath}: path=${refOrTaskId.featureId}/${refOrTaskId.taskId} content=${state.featureId ?? "<missing>"}/${state.taskId}`);
+    }
+    return state;
 }
+/**
+ * @deprecated Legacy-only flat scan. Does not include feature-scoped v2 states.
+ * Prefer readFeatureTaskPoolStates / listTaskPoolStates. Removal targeted for M2.
+ */
 export async function readAllTaskPoolStates(repoRoot) {
-    const stateDir = path.join(getTaskPoolRoot(repoRoot), "states");
+    const stateDir = getStatesRoot(repoRoot);
     try {
-        const entries = await readdir(stateDir);
+        const entries = await readdir(stateDir, { withFileTypes: true });
         const states = {};
         for (const entry of entries) {
-            if (!entry.endsWith(".json"))
+            if (!entry.isFile() || !entry.name.endsWith(".json"))
                 continue;
-            const raw = await readFile(path.join(stateDir, entry), "utf-8");
+            const raw = await readFile(path.join(stateDir, entry.name), "utf-8");
             const state = JSON.parse(raw);
             states[state.taskId] = state;
         }
@@ -101,12 +182,79 @@ export async function readAllTaskPoolStates(repoRoot) {
         throw error;
     }
 }
+/** Canonical Feature-scoped list (v2 paths only). */
+export async function readFeatureTaskPoolStates(repoRoot, featureId) {
+    assertSafeTaskPoolId(featureId, "featureId");
+    const featureDir = path.join(getStatesRoot(repoRoot), featureId);
+    assertWithinStatesRoot(repoRoot, featureDir);
+    const states = {};
+    try {
+        const entries = await readdir(featureDir);
+        for (const entry of entries) {
+            if (!entry.endsWith(".json"))
+                continue;
+            const taskId = entry.slice(0, -5);
+            const state = await readTaskPoolState(repoRoot, { featureId, taskId });
+            if (state)
+                states[taskId] = state;
+        }
+        return states;
+    }
+    catch (error) {
+        if (isNotFound(error))
+            return {};
+        throw error;
+    }
+}
+/** List all schema v2 feature-scoped states (never a covering Record by bare taskId). */
+export async function listTaskPoolStates(repoRoot) {
+    const stateDir = getStatesRoot(repoRoot);
+    const result = [];
+    try {
+        const entries = await readdir(stateDir, { withFileTypes: true });
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            const featureId = entry.name;
+            if (!SAFE_TASK_POOL_ID.test(featureId))
+                continue;
+            const featureStates = await readFeatureTaskPoolStates(repoRoot, featureId);
+            result.push(...Object.values(featureStates));
+        }
+        return result;
+    }
+    catch (error) {
+        if (isNotFound(error))
+            return [];
+        throw error;
+    }
+}
+/**
+ * Write Task Pool state.
+ * Requires featureId (schema v2). Throws if featureId missing or legacy flat file exists.
+ */
 export async function writeTaskPoolState(repoRoot, state) {
-    const statePath = getTaskStatePath(repoRoot, state.taskId);
+    if (!state.featureId) {
+        throw new TaskPoolStateError(TASK_POOL_STATE_ERROR_CODES.FEATURE_REQUIRED, `writeTaskPoolState requires featureId for task ${state.taskId}`);
+    }
+    assertSafeTaskPoolId(state.featureId, "featureId");
+    assertSafeTaskPoolId(state.taskId, "taskId");
+    const legacyPath = getLegacyTaskStatePath(repoRoot, state.taskId);
+    if (await pathExists(legacyPath)) {
+        throw new TaskPoolStateError(TASK_POOL_STATE_ERROR_CODES.MIGRATION_REQUIRED, `cannot write v2 state for ${state.taskId}: legacy state exists at ${legacyPath}`);
+    }
+    const ref = { featureId: state.featureId, taskId: state.taskId };
+    const statePath = getTaskStatePath(repoRoot, ref);
+    const payload = {
+        ...state,
+        schemaVersion: 2,
+        featureId: state.featureId,
+        taskId: state.taskId,
+    };
     await mkdir(path.dirname(statePath), { recursive: true });
     const tempPath = path.join(path.dirname(statePath), `.${path.basename(statePath)}.${randomUUID()}.tmp`);
     try {
-        await writeFile(tempPath, `${JSON.stringify({ schemaVersion: 1, ...state }, null, 2)}\n`, "utf-8");
+        await writeFile(tempPath, `${JSON.stringify(payload, null, 2)}\n`, "utf-8");
         await rename(tempPath, statePath);
     }
     finally {
@@ -127,6 +275,43 @@ export async function readJsonlFile(filePath) {
         throw error;
     }
 }
+export async function sha256Text(text) {
+    return createHash("sha256").update(text, "utf-8").digest("hex");
+}
+export async function sha256File(filePath) {
+    const raw = await readFile(filePath);
+    return createHash("sha256").update(raw).digest("hex");
+}
+export async function listLegacyStateFiles(repoRoot) {
+    const stateDir = getStatesRoot(repoRoot);
+    try {
+        const entries = await readdir(stateDir, { withFileTypes: true });
+        const result = [];
+        for (const entry of entries) {
+            if (!entry.isFile() || !entry.name.endsWith(".json"))
+                continue;
+            const taskId = entry.name.slice(0, -5);
+            result.push({ taskId, path: path.join(stateDir, entry.name) });
+        }
+        return result;
+    }
+    catch (error) {
+        if (isNotFound(error))
+            return [];
+        throw error;
+    }
+}
+export async function pathExists(filePath) {
+    try {
+        await stat(filePath);
+        return true;
+    }
+    catch (error) {
+        if (isNotFound(error))
+            return false;
+        throw error;
+    }
+}
 async function appendJsonlFile(filePath, value) {
     await mkdir(path.dirname(filePath), { recursive: true });
     try {
@@ -140,10 +325,12 @@ async function appendJsonlFile(filePath, value) {
     }
 }
 async function ensurePoolDirs(repoRoot) {
-    await mkdir(path.join(getTaskPoolRoot(repoRoot), "states"), { recursive: true });
+    await mkdir(getStatesRoot(repoRoot), { recursive: true });
 }
-function stateFromRun(run) {
+export function stateFromRun(run) {
     return {
+        schemaVersion: 2,
+        featureId: run.featureId,
         taskId: run.taskId,
         status: stateStatusFromRun(run),
         updatedAt: run.recordedAt,
@@ -175,6 +362,7 @@ function eventFromRun(run) {
         batchRunId: run.batchRunId,
         workerRunId: run.workerRunId,
         taskId: run.taskId,
+        featureId: run.featureId,
         status: run.status,
     };
 }

package/dist/worker/pool/types.js

@@ -1 +1,17 @@
-export {};
+/** Stable error codes for Task Pool state identity / migration. */
+export const TASK_POOL_STATE_ERROR_CODES = {
+    MIGRATION_REQUIRED: "task-pool-state-migration-required",
+    IDENTITY_AMBIGUOUS: "task-pool-state-identity-ambiguous",
+    PATH_MISMATCH: "task-pool-state-path-mismatch",
+    CONFLICT: "task-pool-state-conflict",
+    FEATURE_REQUIRED: "task-pool-state-feature-required",
+    UNSAFE_ID: "task-pool-state-unsafe-id",
+};
+export class TaskPoolStateError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "TaskPoolStateError";
+        this.code = code;
+    }
+}