parallel-codex-tui 0.1.3 → 0.1.5

package/dist/domain/schemas.js

@@ -1,7 +1,48 @@
 import { z } from "zod";
 export const RouteModeSchema = z.enum(["simple", "complex"]);
-export const EngineNameSchema = z.enum(["codex", "claude", "mock"]);
+export const EngineNameSchema = z
+    .string()
+    .min(1)
+    .max(48)
+    .regex(/^[a-z][a-z0-9_]*$/, "Worker id must start with a lowercase letter and contain only lowercase letters, digits or _");
 export const WorkerRoleSchema = z.enum(["main", "judge", "actor", "critic"]);
+export const RouterFailureStageSchema = z.enum([
+    "spawn",
+    "input",
+    "waiting-output",
+    "streaming",
+    "exit",
+    "response"
+]);
+export const RouterFallbackResolutionSchema = z.enum([
+    "main",
+    "parallel",
+    "retry",
+    "auto-retry",
+    "cancelled",
+    "configured"
+]);
+export const RouterFailureKindSchema = z.enum([
+    "timeout",
+    "auth",
+    "rate-limit",
+    "proxy",
+    "network",
+    "unavailable",
+    "invalid-output",
+    "exit",
+    "input",
+    "unknown"
+]);
+export const RouterProxySourceSchema = z.enum(["router-config", "environment"]);
+export const RouterTimeoutKindSchema = z.enum(["first-output", "idle", "total"]);
+export const RouterRecoveryTriggerSchema = z.enum(["retry", "auto-retry"]);
+export const TaskIdSchema = z
+    .string()
+    .min(1)
+    .max(255)
+    .regex(/^task-[A-Za-z0-9][A-Za-z0-9._-]*$/);
+export const TaskSessionIdSchema = z.union([z.literal("main"), TaskIdSchema]);
 export const TaskStateSchema = z.enum([
     "created",
     "routed",
@@ -10,11 +51,21 @@ export const TaskStateSchema = z.enum([
     "actor_running",
     "critic_running",
     "revision_needed",
+    "integrating",
     "verifying",
+    "paused",
     "done",
     "failed",
     "cancelled"
 ]);
+export const TaskStatusTransitionSchema = z.object({
+    id: z.string().min(1),
+    from: TaskStateSchema,
+    to: TaskStateSchema,
+    at: z.string().datetime()
+}).refine((transition) => transition.from !== transition.to, {
+    message: "Task status transition must change state"
+});
 export const WorkerStateSchema = z.enum([
     "idle",
     "starting",
@@ -24,34 +75,104 @@ export const WorkerStateSchema = z.enum([
     "failed",
     "cancelled"
 ]);
+export const FeatureStateSchema = z.enum([
+    "created",
+    "queued",
+    "actor_running",
+    "actor_done",
+    "critic_running",
+    "critic_done",
+    "revision_needed",
+    "integrating",
+    "verifying",
+    "paused",
+    "approved",
+    "failed",
+    "cancelled"
+]);
 export const RouteDecisionSchema = z.object({
     mode: RouteModeSchema,
     reason: z.string().min(1),
+    source: z.enum(["codex", "forced", "fallback"]).optional(),
+    duration_ms: z.number().nonnegative().optional(),
+    router_dispatch_ms: z.number().nonnegative().optional(),
+    router_spawn_ms: z.number().nonnegative().optional(),
+    router_first_output_ms: z.number().nonnegative().optional(),
+    router_first_stdout_ms: z.number().nonnegative().optional(),
+    router_first_stderr_ms: z.number().nonnegative().optional(),
+    router_process_ms: z.number().nonnegative().optional(),
+    router_parse_ms: z.number().nonnegative().optional(),
+    router_stdout_bytes: z.number().int().nonnegative().optional(),
+    router_stderr_bytes: z.number().int().nonnegative().optional(),
+    router_command: z.string().min(1).max(80).optional(),
+    router_failure_stage: RouterFailureStageSchema.optional(),
+    router_failure_kind: RouterFailureKindSchema.optional(),
+    router_attempt: z.number().int().positive().optional(),
+    router_total_duration_ms: z.number().nonnegative().optional(),
+    router_fallback_resolution: RouterFallbackResolutionSchema.optional(),
+    router_timeout_kind: RouterTimeoutKindSchema.optional(),
+    router_recovered_from: RouterFailureKindSchema.optional(),
+    router_recovered_via: RouterRecoveryTriggerSchema.optional(),
+    router_recovered_timeout_kind: RouterTimeoutKindSchema.optional(),
+    router_recovered_failure_stage: RouterFailureStageSchema.optional(),
+    proxy_configured: z.boolean().optional(),
+    proxy_source: RouterProxySourceSchema.optional(),
+    proxy_variable: z.string().regex(/^(?:HTTP|HTTPS|ALL)_PROXY$/i).optional(),
+    proxy_endpoint: z.string().min(1).max(255).optional(),
     suggested_roles: z.array(WorkerRoleSchema).default([]),
     judge_engine: EngineNameSchema.default("codex"),
     actor_engine: EngineNameSchema.default("codex"),
     critic_engine: EngineNameSchema.default("claude")
 });
 export const TaskMetaSchema = z.object({
-    id: z.string().min(1),
-    title: z.string().min(1),
+    id: TaskIdSchema,
+    title: z.string().min(1).max(160),
     created_at: z.string().datetime(),
     cwd: z.string().min(1),
     mode: RouteModeSchema,
-    status: TaskStateSchema
+    status: TaskStateSchema,
+    archived_at: z.string().datetime().optional(),
+    status_transition: TaskStatusTransitionSchema.optional().catch(undefined)
+}).transform((meta) => {
+    if (meta.status_transition && meta.status_transition.to !== meta.status) {
+        const nextMeta = { ...meta };
+        delete nextMeta.status_transition;
+        return nextMeta;
+    }
+    return meta;
 });
 export const WorkerStatusSchema = z.object({
     worker_id: z.string().min(1),
+    feature_id: z.string().min(1).optional(),
+    feature_title: z.string().min(1).optional(),
     role: WorkerRoleSchema,
     engine: EngineNameSchema,
+    model_name: z.string().optional(),
+    model_provider: z.string().optional(),
     state: WorkerStateSchema,
     phase: z.string().min(1),
     last_event_at: z.string().datetime(),
     summary: z.string(),
     native_session_id: z.string().min(1).optional()
 });
+export const FeatureStatusSchema = z.object({
+    feature_id: z.string().min(1),
+    task_id: TaskIdSchema,
+    turn_id: z.string().min(1),
+    title: z.string().min(1).optional(),
+    description: z.string().default(""),
+    depends_on: z.array(z.string().min(1)).default([]),
+    state: FeatureStateSchema,
+    updated_at: z.string().datetime()
+});
+export const FeatureAssignmentSchema = z.object({
+    version: z.literal(1),
+    actor_engine: EngineNameSchema,
+    critic_engine: EngineNameSchema,
+    updated_at: z.string().datetime()
+});
 export const TurnMetaSchema = z.object({
-    task_id: z.string().min(1),
+    task_id: TaskIdSchema,
     turn_id: z.string().regex(/^\d{4}$/),
     created_at: z.string().datetime(),
     request_path: z.string().min(1)
@@ -62,17 +183,31 @@ export const NativeSessionSchema = z.object({
     role: WorkerRoleSchema,
     worker_id: z.string().min(1),
     session_id: z.string().min(1),
-    scope: z.literal("task"),
+    scope: z.enum(["main", "task"]),
     cwd: z.string().min(1),
+    writable_dirs: z.array(z.string().min(1)).optional(),
     created_at: z.string().datetime(),
     last_used_at: z.string().datetime(),
     source: NativeSessionSourceSchema
 });
+export const RetiredNativeSessionSchema = NativeSessionSchema.extend({
+    retired_at: z.string().datetime(),
+    retired_reason: z.string().min(1)
+});
+export const ChatRecordSchema = z.object({
+    time: z.string().datetime(),
+    from: z.enum(["user", "system"]),
+    text: z.string(),
+    task_id: TaskIdSchema.optional()
+});
 export const EventRecordSchema = z.object({
     time: z.string().datetime(),
     type: z.string().min(1),
     message: z.string().optional(),
     worker: z.string().optional(),
     engine: EngineNameSchema.optional(),
-    task_id: z.string().optional()
+    task_id: TaskSessionIdSchema.optional(),
+    transition_id: z.string().min(1).optional(),
+    from_state: TaskStateSchema.optional(),
+    to_state: TaskStateSchema.optional()
 });

package/dist/orchestrator/collaboration-channel.js

@@ -1,11 +1,47 @@
 import { join } from "node:path";
-import { appendJsonLine, ensureDir, writeJson, writeText } from "../core/file-store.js";
+import { z } from "zod";
+import { appendJsonLine, ensureDir, pathExists, readJson, readTextIfExists, writeJson, writeText } from "../core/file-store.js";
+import { FeatureAssignmentSchema, FeatureStatusSchema } from "../domain/schemas.js";
+const CriticFindingRecordSchema = z.object({
+    id: z.string().trim().min(1),
+    severity: z.string().trim().optional(),
+    summary: z.string().trim().min(1).optional(),
+    message: z.string().trim().min(1).optional()
+}).passthrough().superRefine((record, context) => {
+    if (!record.summary && !record.message) {
+        context.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["summary"],
+            message: "summary or legacy message is required"
+        });
+    }
+}).transform((record) => ({
+    ...record,
+    summary: record.summary ?? record.message ?? ""
+}));
+const ActorFindingReplyRecordSchema = z.object({
+    finding_id: z.string().trim().min(1),
+    status: z.string().trim().toLowerCase().pipe(z.enum(["fixed", "not_fixed", "deferred"])).default("fixed"),
+    notes: z.string().trim().optional()
+}).passthrough();
+const ApprovedFindingResolutionSchema = z.object({
+    version: z.literal(1),
+    decision: z.literal("approved"),
+    finding_ids: z.array(z.string().min(1)),
+    fixed_ids: z.array(z.string().min(1)),
+    unresolved_ids: z.array(z.string().min(1)).length(0)
+});
 export async function createFeatureChannel(input) {
-    const id = featureIdForTurn(input.turn, input.request);
+    const id = input.feature
+        ? `${input.turn.turnId}-${input.feature.id}`
+        : featureIdForTurn(input.turn, input.request);
     const dir = join(input.task.dir, "features", id);
     const dialoguePath = join(input.task.dir, "dialogue", "actor-critic.jsonl");
     const channel = {
         id,
+        title: input.feature?.title ?? input.request.trim(),
+        description: input.feature?.description ?? input.request.trim(),
+        dependsOn: input.feature?.depends_on ?? [],
         taskId: input.task.id,
         turnId: input.turn.turnId,
         dir,
@@ -15,38 +51,140 @@ export async function createFeatureChannel(input) {
         actorWorklogPath: join(dir, "actor-worklog.md"),
         actorRepliesPath: join(dir, "actor-replies.jsonl"),
         criticFindingsPath: join(dir, "critic-findings.jsonl"),
-        decisionsPath: join(dir, "decisions.md")
+        findingResolutionPath: join(dir, "finding-resolution.json"),
+        decisionsPath: join(dir, "decisions.md"),
+        assignmentPath: join(dir, "assignment.json")
     };
     await ensureDir(dir);
     await ensureDir(join(input.task.dir, "dialogue"));
+    if (input.resume) {
+        await ensureFeatureChannelFiles(input, channel);
+        const repairedState = await repairFeatureStatus(channel);
+        if (repairedState) {
+            await appendFeatureDialogue(channel, "feature.status_recovered", "actor", `Recovered Feature status as ${repairedState} while preserving collaboration evidence.`);
+        }
+        return channel;
+    }
     await writeText(channel.specPath, buildFeatureSpec(input, channel));
     await writeText(channel.actorWorklogPath, "");
     await writeText(channel.actorRepliesPath, "");
     await writeText(channel.criticFindingsPath, "");
+    if (input.actorEngine && input.criticEngine) {
+        await writeFeatureAssignment(channel, input.actorEngine, input.criticEngine);
+    }
     await updateFeatureStatus(channel, "created");
     await appendFeatureDialogue(channel, "feature.created", "actor", "Feature mailbox created for the current turn.");
     return channel;
 }
+async function ensureFeatureChannelFiles(input, channel) {
+    const files = [
+        [channel.specPath, buildFeatureSpec(input, channel)],
+        [channel.actorWorklogPath, ""],
+        [channel.actorRepliesPath, ""],
+        [channel.criticFindingsPath, ""]
+    ];
+    for (const [path, initialContent] of files) {
+        if (!(await pathExists(path))) {
+            await writeText(path, initialContent);
+        }
+    }
+    if (!(await pathExists(channel.assignmentPath)) && input.actorEngine && input.criticEngine) {
+        await writeFeatureAssignment(channel, input.actorEngine, input.criticEngine);
+    }
+}
+export async function readFeatureAssignment(channel, fallback) {
+    try {
+        return await readJson(channel.assignmentPath, FeatureAssignmentSchema);
+    }
+    catch {
+        return FeatureAssignmentSchema.parse({
+            version: 1,
+            actor_engine: fallback.actor,
+            critic_engine: fallback.critic,
+            updated_at: new Date(0).toISOString()
+        });
+    }
+}
+export async function writeFeatureAssignment(channel, actorEngine, criticEngine) {
+    const assignment = FeatureAssignmentSchema.parse({
+        version: 1,
+        actor_engine: actorEngine,
+        critic_engine: criticEngine,
+        updated_at: new Date().toISOString()
+    });
+    await writeJson(channel.assignmentPath, assignment);
+    return assignment;
+}
 export function featurePromptContext(channel) {
     return {
         featureId: channel.id,
+        featureTitle: channel.title,
+        featureDescription: channel.description,
+        featureSpecPath: channel.specPath,
+        featureDependencies: channel.dependsOn,
         featureDir: channel.dir,
         dialoguePath: channel.dialoguePath,
         actorWorklogPath: channel.actorWorklogPath,
         actorRepliesPath: channel.actorRepliesPath,
         criticFindingsPath: channel.criticFindingsPath,
-        decisionsPath: channel.decisionsPath
+        decisionsPath: channel.decisionsPath,
+        assignmentPath: channel.assignmentPath
     };
 }
 export async function updateFeatureStatus(channel, state) {
+    if (await pathExists(channel.statusPath)) {
+        try {
+            const current = await readJson(channel.statusPath, FeatureStatusSchema);
+            if (current.state === state && featureStatusMatchesChannel(current, channel)) {
+                return;
+            }
+        }
+        catch {
+            // A corrupt status is rebuilt from the authoritative feature channel.
+        }
+    }
     await writeJson(channel.statusPath, {
         feature_id: channel.id,
         task_id: channel.taskId,
         turn_id: channel.turnId,
+        title: channel.title,
+        description: channel.description,
+        depends_on: channel.dependsOn,
         state,
         updated_at: new Date().toISOString()
     });
 }
+async function repairFeatureStatus(channel) {
+    let current = null;
+    if (await pathExists(channel.statusPath)) {
+        try {
+            current = await readJson(channel.statusPath, FeatureStatusSchema);
+        }
+        catch {
+            // Invalid status is rebuilt without replacing the collaboration mailbox.
+        }
+    }
+    if (current && featureStatusMatchesChannel(current, channel)) {
+        return null;
+    }
+    const state = current && featureStatusIdentityMatches(current, channel)
+        ? current.state
+        : "created";
+    await updateFeatureStatus(channel, state);
+    return state;
+}
+function featureStatusMatchesChannel(status, channel) {
+    return featureStatusIdentityMatches(status, channel)
+        && status.title === channel.title
+        && status.description === channel.description
+        && status.depends_on.length === channel.dependsOn.length
+        && status.depends_on.every((dependency, index) => dependency === channel.dependsOn[index]);
+}
+function featureStatusIdentityMatches(status, channel) {
+    return status.feature_id === channel.id
+        && status.task_id === channel.taskId
+        && status.turn_id === channel.turnId;
+}
 export async function appendFeatureDialogue(channel, type, role, message, paths = {}) {
     await appendJsonLine(channel.dialoguePath, {
         time: new Date().toISOString(),
@@ -70,11 +208,155 @@ export async function writeFeatureDecision(channel, summary) {
         ""
     ].join("\n"));
 }
+export async function requireFeatureRevisionFindings(channel) {
+    const findings = await readFeatureCriticFindings(channel);
+    if (findings.length === 0) {
+        throw new Error(`Critic requested revision without valid critic findings for ${channel.id}.`);
+    }
+    const findingIds = findings.map((finding) => finding.id);
+    const replies = await readFeatureActorReplies(channel);
+    await writeFindingResolutionSnapshot(channel, "pending", findingIds, replies);
+    return findingIds;
+}
+export async function requireActorFindingReplies(channel, findingIds) {
+    const replies = await readFeatureActorReplies(channel);
+    const resolution = await writeFindingResolutionSnapshot(channel, "pending", findingIds, replies);
+    const unknown = resolution.unknownReplyIds;
+    if (unknown.length > 0) {
+        throw new Error(`Actor replies reference unknown Critic findings: ${unknown.join(", ")}.`);
+    }
+    const unresolved = resolution.unresolvedIds;
+    if (unresolved.length > 0) {
+        throw new Error(`Actor revision did not mark every Critic finding fixed: ${unresolved.join(", ")}.`);
+    }
+}
+export async function recordApprovedFindingResolution(channel, revisionFindingIds = [], options = {}) {
+    const findings = await readFeatureCriticFindings(channel);
+    const currentIds = [...new Set(findings.map((finding) => finding.id))];
+    const replies = await readFeatureActorReplies(channel);
+    const latestReplies = new Map(replies.map((reply) => [reply.finding_id, reply]));
+    const expectedIds = revisionFindingIds.length > 0
+        ? [...new Set(revisionFindingIds)]
+        : options.allowLegacyResolvedFindings
+            ? currentIds.filter((id) => latestReplies.get(id)?.status === "fixed")
+            : [];
+    const unexpected = currentIds.filter((id) => !expectedIds.includes(id));
+    if (unexpected.length > 0) {
+        await writeFindingResolutionRecord(channel, {
+            decision: "inconsistent",
+            findingIds: currentIds,
+            fixedIds: [],
+            unresolvedIds: currentIds,
+            unknownReplyIds: [...new Set(replies.map((reply) => reply.finding_id))]
+                .filter((id) => !currentIds.includes(id)),
+            replyCount: replies.length
+        });
+        throw new Error(`Critic approved with unresolved blocking findings: ${unexpected.join(", ")}.`);
+    }
+    await requireActorFindingReplies(channel, expectedIds);
+    await writeFindingResolutionRecord(channel, {
+        decision: "approved",
+        findingIds: expectedIds,
+        fixedIds: expectedIds,
+        unresolvedIds: [],
+        unknownReplyIds: [],
+        replyCount: replies.length
+    });
+}
+export async function featureCriticCheckpointIsReusable(channel, decision) {
+    try {
+        if (decision === "revision") {
+            return (await readFeatureCriticFindings(channel)).length > 0;
+        }
+        const resolutionText = await readTextIfExists(channel.findingResolutionPath);
+        if (resolutionText.trim()) {
+            return ApprovedFindingResolutionSchema.safeParse(JSON.parse(resolutionText)).success;
+        }
+        const findings = await readFeatureCriticFindings(channel);
+        const replies = await readFeatureActorReplies(channel);
+        if (findings.length === 0) {
+            return replies.length === 0;
+        }
+        const findingIds = new Set(findings.map((finding) => finding.id));
+        const latestReplies = new Map(replies.map((reply) => [reply.finding_id, reply]));
+        return [...latestReplies.keys()].every((id) => findingIds.has(id))
+            && [...findingIds].every((id) => latestReplies.get(id)?.status === "fixed");
+    }
+    catch {
+        return false;
+    }
+}
+async function readFeatureCriticFindings(channel) {
+    return readMailboxJsonLines(channel.criticFindingsPath, CriticFindingRecordSchema, "Critic finding");
+}
+async function readFeatureActorReplies(channel) {
+    return readMailboxJsonLines(channel.actorRepliesPath, ActorFindingReplyRecordSchema, "Actor finding reply");
+}
+async function writeFindingResolutionSnapshot(channel, decision, findingIds, replies) {
+    const ids = [...new Set(findingIds)];
+    const expected = new Set(ids);
+    const latest = new Map(replies.map((reply) => [reply.finding_id, reply]));
+    const fixedIds = ids.filter((id) => latest.get(id)?.status === "fixed");
+    const unresolvedIds = ids.filter((id) => latest.get(id)?.status !== "fixed");
+    const unknownReplyIds = [...latest.keys()].filter((id) => !expected.has(id));
+    await writeFindingResolutionRecord(channel, {
+        decision,
+        findingIds: ids,
+        fixedIds,
+        unresolvedIds,
+        unknownReplyIds,
+        replyCount: replies.length
+    });
+    return { fixedIds, unresolvedIds, unknownReplyIds };
+}
+async function writeFindingResolutionRecord(channel, input) {
+    await writeJson(channel.findingResolutionPath, {
+        version: 1,
+        decision: input.decision,
+        finding_ids: input.findingIds,
+        fixed_ids: input.fixedIds,
+        unresolved_ids: [
+            ...input.unresolvedIds,
+            ...input.unknownReplyIds.map((id) => `unknown:${id}`)
+        ],
+        unknown_reply_ids: input.unknownReplyIds,
+        reply_count: input.replyCount,
+        updated_at: new Date().toISOString()
+    });
+}
+async function readMailboxJsonLines(path, schema, label) {
+    const records = [];
+    const lines = (await readTextIfExists(path)).split(/\r?\n/);
+    for (let index = 0; index < lines.length; index += 1) {
+        const line = lines[index]?.trim() ?? "";
+        if (!line) {
+            continue;
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            throw new Error(`${label} JSONL is invalid at line ${index + 1}: ${path}.`);
+        }
+        const result = schema.safeParse(parsed);
+        if (!result.success) {
+            const issue = result.error.issues[0];
+            const field = issue?.path.length ? ` field ${issue.path.join(".")}` : "";
+            throw new Error(`${label}${field} is invalid at line ${index + 1}: ${path}.`);
+        }
+        records.push(result.data);
+    }
+    return records;
+}
 function buildFeatureSpec(input, channel) {
     return [
         "# Feature Mailbox",
         "",
         `Feature: ${channel.id}`,
+        `Title: ${channel.title}`,
+        `Description: ${channel.description}`,
+        `Depends on: ${channel.dependsOn.length > 0 ? channel.dependsOn.join(", ") : "(none)"}`,
         `Task: ${input.task.id}`,
         `Turn: ${input.turn.turnId}`,
         `Turn directory: ${input.turn.dir}`,
@@ -85,9 +367,10 @@ function buildFeatureSpec(input, channel) {
         "",
         "Protocol:",
         "- Actor writes implementation notes to actor-worklog.md.",
-        "- Critic writes one JSON object per blocking issue to critic-findings.jsonl.",
-        "- Actor replies to each critic finding in actor-replies.jsonl.",
+        '- Critic writes one JSON object per blocking issue to critic-findings.jsonl: {"id":"C-001","severity":"blocker","summary":"what must change"}.',
+        '- Actor replies to each fixed finding in actor-replies.jsonl: {"finding_id":"C-001","status":"fixed","notes":"what changed"}.',
         "- Supervisor writes the final decision summary to decisions.md.",
+        "- assignment.json records the Actor and Critic engines selected for retries.",
         ""
     ].join("\n");
 }

package/dist/orchestrator/feature-plan.js

@@ -0,0 +1,70 @@
+import { z } from "zod";
+const FeatureIdSchema = z.string()
+    .trim()
+    .regex(/^[a-z0-9][a-z0-9-]{0,31}$/, "Feature ids must use lowercase letters, numbers, and hyphens only");
+const FeatureDefinitionSchema = z.object({
+    id: FeatureIdSchema,
+    title: z.string().trim().min(1),
+    description: z.string().trim().min(1),
+    depends_on: z.array(FeatureIdSchema).default([])
+});
+const FeaturePlanSchema = z.object({
+    version: z.literal(1),
+    features: z.array(FeatureDefinitionSchema).min(1).max(8)
+});
+export function parseFeaturePlan(input) {
+    const plan = FeaturePlanSchema.parse(input);
+    const ids = new Set();
+    for (const feature of plan.features) {
+        if (ids.has(feature.id)) {
+            throw new Error(`Duplicate feature id: ${feature.id}`);
+        }
+        ids.add(feature.id);
+    }
+    for (const feature of plan.features) {
+        const dependencies = new Set();
+        for (const dependency of feature.depends_on) {
+            if (dependency === feature.id) {
+                throw new Error(`Feature ${feature.id} cannot depend on itself`);
+            }
+            if (!ids.has(dependency)) {
+                throw new Error(`Feature ${feature.id} depends on unknown feature: ${dependency}`);
+            }
+            if (dependencies.has(dependency)) {
+                throw new Error(`Feature ${feature.id} has duplicate dependency: ${dependency}`);
+            }
+            dependencies.add(dependency);
+        }
+    }
+    const waves = buildWaves(plan);
+    if (waves.flat().length !== plan.features.length) {
+        const scheduled = new Set(waves.flat().map((feature) => feature.id));
+        const cycle = plan.features
+            .filter((feature) => !scheduled.has(feature.id))
+            .map((feature) => feature.id)
+            .sort();
+        throw new Error(`Feature dependency cycle: ${cycle.join(", ")}`);
+    }
+    return plan;
+}
+export function featureExecutionWaves(plan) {
+    return buildWaves(plan);
+}
+function buildWaves(plan) {
+    const completed = new Set();
+    const remaining = new Set(plan.features.map((feature) => feature.id));
+    const waves = [];
+    while (remaining.size > 0) {
+        const wave = plan.features.filter((feature) => (remaining.has(feature.id)
+            && feature.depends_on.every((dependency) => completed.has(dependency))));
+        if (wave.length === 0) {
+            break;
+        }
+        waves.push(wave);
+        for (const feature of wave) {
+            remaining.delete(feature.id);
+            completed.add(feature.id);
+        }
+    }
+    return waves;
+}