@jterrats/open-orchestra 0.4.1 → 0.4.2-beta.1

package/dist/workflow-services.js

@@ -11,7 +11,13 @@ import { analyzePullRequestReview } from "./pr-review.js";
 import { planSkillsForTask } from "./skills.js";
 import { getTelemetryConsent } from "./telemetry.js";
 import { latestDelegationDecision } from "./delegation-decision.js";
+import { listAutonomousRuns } from "./autonomous-workflow.js";
+import { persistRun, readAutonomousRun } from "./autonomous-run-store.js";
+import { AUTONOMOUS_PHASE_SEQUENCE } from "./autonomous-workflow-constants.js";
+import { readEstimate } from "./benchmark.js";
+import { notifyWorkflowLifecycle, } from "./notifications.js";
 import { handoffFlowRequirements, recommendCollaborationFlow, } from "./collaboration-flows.js";
+import { queryMemory, recordMemoryEvent } from "./memory.js";
 import { selectWorkflowTemplates } from "./workflow-templates.js";
 import { SIZING_LABELS } from "./types.js";
 export async function getWorkflowStatus(root = process.cwd()) {
@@ -70,13 +76,129 @@ export async function listTasks(root = process.cwd()) {
     const workspace = await loadWorkspace(root);
     return workspace.tasks;
 }
+export async function deleteTask(taskId, options = {}, root = process.cwd()) {
+    const workspace = await loadWorkspace(root);
+    let deleted;
+    await mutateTasks(workspace.base, (tasks) => {
+        const taskIndex = tasks.findIndex((task) => task.id === taskId);
+        if (taskIndex < 0) {
+            throw new Error(`unknown task: ${taskId}`);
+        }
+        const current = tasks[taskIndex];
+        if (!current) {
+            throw new Error(`unknown task: ${taskId}`);
+        }
+        assertTaskCanBeRemoved(current, tasks, options.force ?? false);
+        deleted = current;
+        return tasks.filter((task) => task.id !== taskId);
+    });
+    if (!deleted) {
+        throw new Error(`unknown task: ${taskId}`);
+    }
+    await appendEvent(root, {
+        type: "TASK_DELETED",
+        taskId,
+        actor: "parent",
+        summary: `Task deleted: ${taskId}`,
+        metadata: {
+            title: deleted.title,
+            status: deleted.status,
+            forced: Boolean(options.force),
+        },
+    });
+    return deleted;
+}
+export async function archiveTask(taskId, options = {}, root = process.cwd()) {
+    const workspace = await loadWorkspace(root);
+    let archived;
+    await mutateTasks(workspace.base, (tasks) => {
+        const taskIndex = tasks.findIndex((task) => task.id === taskId);
+        if (taskIndex < 0) {
+            throw new Error(`unknown task: ${taskId}`);
+        }
+        const current = tasks[taskIndex];
+        if (!current) {
+            throw new Error(`unknown task: ${taskId}`);
+        }
+        assertTaskCanBeRemoved(current, tasks, options.force ?? false);
+        archived = {
+            ...current,
+            status: "archived",
+            updatedAt: new Date().toISOString(),
+        };
+        const nextTasks = [...tasks];
+        nextTasks[taskIndex] = archived;
+        return nextTasks;
+    });
+    if (!archived) {
+        throw new Error(`unknown task: ${taskId}`);
+    }
+    await appendEvent(root, {
+        type: "TASK_ARCHIVED",
+        taskId,
+        actor: "parent",
+        summary: `Task archived: ${taskId}`,
+        metadata: {
+            title: archived.title,
+            forced: Boolean(options.force),
+        },
+    });
+    return archived;
+}
 export async function listRoles(root = process.cwd()) {
     const workspace = await loadWorkspace(root);
     return workspace.roles;
 }
+export async function validatePreRun(taskId, options = {}, root = process.cwd()) {
+    const workspace = await loadWorkspace(root);
+    const task = workspace.tasks.find((candidate) => candidate.id === taskId);
+    const events = await readEvents(root);
+    const estimate = task ? await readEstimate(root, taskId) : undefined;
+    const runs = task ? await listAutonomousRuns(root) : [];
+    const checks = {
+        task: Boolean(task),
+        estimate: Boolean(estimate),
+        workflowRun: runs.some((run) => run.taskId === taskId),
+        evidence: events.some((event) => event.taskId === taskId && event.type === "EVIDENCE_ADDED"),
+        review: events.some((event) => event.taskId === taskId && event.type === "REVIEW_RECORDED"),
+    };
+    const missing = Object.entries(checks)
+        .filter(([, passed]) => !passed)
+        .map(([name]) => name);
+    const isReady = missing.length === 0;
+    let bypassDecisionArtifact;
+    if (!isReady && options.bypass && checks.task) {
+        const owner = options.bypassOwner ?? "architect";
+        const rationale = options.bypassRationale ?? "User accepted pre-run validation bypass.";
+        const decision = await recordDecision({
+            task: taskId,
+            owner,
+            title: "Pre-run validation bypass",
+            context: `Missing checks: ${missing.join(", ")}`,
+            decision: "Proceed despite incomplete proactive workflow checks.",
+            consequences: rationale,
+            status: "accepted",
+        }, root);
+        bypassDecisionArtifact = decision.artifact;
+    }
+    const isBypassed = Boolean(bypassDecisionArtifact);
+    return removeUndefined({
+        taskId,
+        isReady,
+        isBypassed,
+        allowed: isReady || isBypassed,
+        missing,
+        checks,
+        bypassDecisionArtifact,
+    });
+}
 export async function updateTask(input, root = process.cwd()) {
     const workspace = await loadWorkspace(root);
+    if (input.ownerRole && !workspace.roleIds.has(input.ownerRole)) {
+        throw new Error(`unknown owner role: ${input.ownerRole}`);
+    }
     let updated;
+    let changedFields = [];
     await mutateTasks(workspace.base, (tasks) => {
         const taskIndex = tasks.findIndex((task) => task.id === input.id);
         if (taskIndex < 0) {
@@ -86,12 +208,11 @@ export async function updateTask(input, root = process.cwd()) {
         if (!current) {
             throw new Error(`unknown task: ${input.id}`);
         }
-        updated = removeUndefined({
-            ...current,
-            status: input.status,
-            blockedReason: input.blockedReason,
-            updatedAt: new Date().toISOString(),
-        });
+        const next = { ...current };
+        const changes = new Set();
+        applyTaskUpdate(next, current, input, changes);
+        changedFields = [...changes].sort();
+        updated = { ...next, updatedAt: new Date().toISOString() };
         const nextTasks = [...tasks];
         nextTasks[taskIndex] = updated;
         return nextTasks;
@@ -104,10 +225,39 @@ export async function updateTask(input, root = process.cwd()) {
         taskId: input.id,
         actor: "parent",
         summary: `Task updated: ${input.id}`,
-        metadata: { status: updated.status },
+        metadata: { status: updated.status, changedFields },
     });
     return updated;
 }
+function applyTaskUpdate(next, current, input, changedFields) {
+    setTaskField(next, current, "title", input.title, changedFields);
+    setTaskField(next, current, "ownerRole", input.ownerRole, changedFields);
+    setTaskField(next, current, "goal", input.goal, changedFields);
+    setTaskField(next, current, "scope", input.scope, changedFields);
+    setTaskField(next, current, "paths", input.paths, changedFields);
+    setTaskField(next, current, "testStrategy", input.testStrategy, changedFields);
+    setTaskField(next, current, "status", input.status, changedFields);
+    setTaskField(next, current, "blockedReason", input.blockedReason, changedFields);
+    appendTaskField(next, "acceptanceCriteria", input.acceptanceCriteria, changedFields);
+    appendTaskField(next, "assumptions", input.assumptions, changedFields);
+    appendTaskField(next, "risks", input.risks, changedFields);
+}
+function setTaskField(next, current, key, value, changedFields) {
+    if (value === undefined) {
+        return;
+    }
+    if (JSON.stringify(current[key]) !== JSON.stringify(value)) {
+        changedFields.add(String(key));
+    }
+    next[key] = value;
+}
+function appendTaskField(next, key, values, changedFields) {
+    if (!values || values.length === 0) {
+        return;
+    }
+    next[key] = [...(next[key] ?? []), ...values];
+    changedFields.add(key);
+}
 export async function checkTaskDependencies(taskId, root = process.cwd()) {
     const workspace = await loadWorkspace(root);
     const task = workspace.tasks.find((candidate) => candidate.id === taskId);
@@ -184,6 +334,35 @@ export async function executeNextReadyTask(root = process.cwd()) {
     }
     return executePlanWithBudgetPreflight(next.id, root);
 }
+export async function previewTaskGraphRun(mode, root = process.cwd()) {
+    const plan = await generateTaskGraphPlan(root);
+    const selected = mode === "run-next" ? plan.ready.slice(0, 1) : plan.ready;
+    if (selected.length === 0) {
+        throw new Error("no ready tasks to run");
+    }
+    const config = await getWorkflowConfig(root);
+    const hasBudgets = hasConfiguredBudgets(config.budgets);
+    const tasks = [];
+    for (const task of selected) {
+        const routing = config.providers.byRole[task.ownerRole] ?? config.providers.defaults;
+        tasks.push({
+            ...task,
+            provider: routing.provider,
+            model: routing.model,
+            fallbacks: routing.fallbacks,
+            ...(hasBudgets ? { budget: await checkUsageBudget(task.id, root) } : {}),
+        });
+    }
+    return {
+        mode,
+        dryRun: true,
+        wouldMutate: false,
+        selectedTaskIds: tasks.map((task) => task.id),
+        tasks,
+        locked: plan.locked,
+        blocked: plan.blocked,
+    };
+}
 export async function executeReadyTaskBatch(root = process.cwd()) {
     const plan = await generateTaskGraphPlan(root);
     const selectedTaskIds = plan.ready.map((task) => task.id);
@@ -210,6 +389,22 @@ export async function executeReadyTaskBatch(root = process.cwd()) {
     }
     return recordTaskGraphBatchRun({ selectedTaskIds, runs, locked: plan.locked }, root);
 }
+function hasConfiguredBudgets(budgets) {
+    if (!budgets) {
+        return false;
+    }
+    return (hasBudgetLimits(budgets.defaults) ||
+        Object.values(budgets.byRole ?? {}).some(hasBudgetLimits) ||
+        Object.values(budgets.byTask ?? {}).some(hasBudgetLimits));
+}
+function hasBudgetLimits(limit) {
+    return Boolean(limit &&
+        (limit.maxRequests !== undefined ||
+            limit.maxInputTokens !== undefined ||
+            limit.maxOutputTokens !== undefined ||
+            limit.maxTotalTokens !== undefined ||
+            limit.maxEstimatedCostUsd !== undefined));
+}
 export async function listLocks(root = process.cwd()) {
     const workspace = await loadWorkspace(root);
     return workspace.locks;
@@ -322,6 +517,10 @@ export async function createHandoff(input, root = process.cwd()) {
     if (!workspace.roleIds.has(input.from) || !workspace.roleIds.has(input.to)) {
         throw new Error("handoff roles must exist in roles.json");
     }
+    if (input.updateOwner &&
+        !workspace.tasks.some((task) => task.id === input.task)) {
+        throw new Error(`unknown task: ${input.task}`);
+    }
     const fileName = `${input.task}-${input.from}-to-${input.to}.md`;
     const content = [
         `# Handoff ${input.task}: ${input.from} to ${input.to}`,
@@ -346,7 +545,11 @@ export async function createHandoff(input, root = process.cwd()) {
         actor: input.from,
         summary: `Handoff ready for ${input.to}`,
         artifacts: [artifact],
+        metadata: { to: input.to, updateOwner: Boolean(input.updateOwner) },
     });
+    if (input.updateOwner) {
+        await updateTask({ id: input.task, ownerRole: input.to }, root);
+    }
     return { artifact, content };
 }
 export async function recordDecision(input, root = process.cwd()) {
@@ -416,6 +619,12 @@ export async function getTaskContext(taskId, root = process.cwd()) {
     }
     const events = await readEvents(root);
     const taskEvents = events.filter((event) => event.taskId === taskId);
+    const memory = await queryMemory({
+        taskId,
+        hook: "before_implementation",
+        root,
+    });
+    await recordMemoryEvent(root, memory, "MEMORY_QUERIED");
     return removeUndefined({
         task,
         dependencies: await checkTaskDependencies(taskId, root),
@@ -427,6 +636,7 @@ export async function getTaskContext(taskId, root = process.cwd()) {
         gates: taskEvents.filter((event) => event.type === "GATE_PASSED" || event.type === "GATE_BLOCKED"),
         modelProvenance: await listModelProvenance(taskId, root),
         skills: await planSkillsForTask(taskId, root),
+        memory,
         telemetry: await getTelemetryConsent(root),
         risks: task.risks ?? [],
         delegation: latestDelegationDecision(taskEvents),
@@ -575,9 +785,12 @@ export async function executePlanWithFakeProvider(taskId, root = process.cwd(),
         budgetEscalation,
     });
 }
-export async function executePlanWithBudgetPreflight(taskId, root = process.cwd(), decision) {
+export async function executePlanWithBudgetPreflight(taskId, root = process.cwd(), decision, estimate) {
     await enforceLockPreflight(taskId, root);
     await enforceDependencyPreflight(taskId, root);
+    if (estimate?.estimatedCostUsd !== undefined) {
+        await enforceBudgetEstimatePreflight(taskId, root, estimate.estimatedCostUsd, Boolean(estimate.override));
+    }
     const budget = await checkUsageBudget(taskId, root);
     if (budget.passed) {
         return executePlanWithFakeProvider(taskId, root);
@@ -664,6 +877,27 @@ async function executeApprovedBudgetFallback(taskId, root, proposal, approval) {
         }),
     });
 }
+export async function checkBudgetEstimatePreflight(taskId, estimatedCostUsd, root = process.cwd()) {
+    if (!Number.isFinite(estimatedCostUsd) || estimatedCostUsd < 0) {
+        throw new Error("estimated cost must be a non-negative number");
+    }
+    const config = await readJson(resolveWorkflowPath(root, FILES.config), {});
+    const workspace = await loadWorkspace(root);
+    const task = workspace.tasks.find((candidate) => candidate.id === taskId);
+    if (!task) {
+        throw new Error(`unknown task: ${taskId}`);
+    }
+    const usage = await getUsageReport(taskId, root);
+    const projectedUsage = projectUsageCost(usage, task.ownerRole, estimatedCostUsd);
+    const budget = await checkUsageBudgetForUsage(taskId, task.ownerRole, projectedUsage, config.budgets);
+    return {
+        taskId,
+        estimatedCostUsd,
+        passed: budget.passed,
+        warnings: budgetEstimateWarningsForBudgets(taskId, task.ownerRole, budget.usage, config.budgets),
+        budget,
+    };
+}
 async function enforceLockPreflight(taskId, root) {
     const workspace = await loadWorkspace(root);
     const task = workspace.tasks.find((candidate) => candidate.id === taskId);
@@ -728,11 +962,71 @@ export async function listApprovals(taskId, root = process.cwd()) {
         : [];
     const events = await readEvents(root);
     const records = fileNames.map((fileName) => approvalRecordForArtifact(path.join(".agent-workflow", "approvals", fileName), events));
+    records.push(...gateApprovalRecords(events));
     const filtered = taskId
         ? records.filter((record) => record.taskId === taskId)
         : records;
     return filtered.sort((left, right) => left.id.localeCompare(right.id));
 }
+export async function approveWorkflowGate(input, root = process.cwd()) {
+    const run = await readAutonomousRun(root, input.runId);
+    if (!run) {
+        throw new Error(`workflow run not found: ${input.runId}`);
+    }
+    const phaseIndex = run.phases.findLastIndex((phase) => phase.status === "gate_paused");
+    if (phaseIndex < 0) {
+        throw new Error(`workflow run ${input.runId} has no paused gate`);
+    }
+    const phase = run.phases[phaseIndex];
+    const gateId = phase.gateId ?? gateIdForPhase(run, phaseIndex);
+    if (input.gateId !== gateId) {
+        throw new Error(`wrong gate id: ${input.gateId}. Expected gate: ${gateId}`);
+    }
+    if (phase.approvedBy && phase.approvedAt) {
+        return {
+            run,
+            gateId,
+            approver: phase.approvedBy,
+            approvedAt: phase.approvedAt,
+            alreadyApproved: true,
+        };
+    }
+    const approvedAt = new Date().toISOString();
+    const approvedPhase = {
+        ...phase,
+        gateId,
+        approvedBy: input.approver,
+        approvedAt,
+        approvalRationale: input.rationale,
+    };
+    const updatedRun = {
+        ...run,
+        phases: run.phases.map((candidate, index) => index === phaseIndex ? approvedPhase : candidate),
+        updatedAt: approvedAt,
+    };
+    await persistRun(root, updatedRun);
+    await appendEvent(root, removeUndefined({
+        type: "GATE_APPROVED",
+        taskId: run.taskId,
+        actor: "parent",
+        summary: `Gate approved: ${gateId}`,
+        artifacts: phase.reviewArtifact ? [phase.reviewArtifact] : undefined,
+        metadata: {
+            runId: run.id,
+            gateId,
+            approver: input.approver,
+            rationale: input.rationale,
+            approvedAt,
+        },
+    }));
+    return {
+        run: updatedRun,
+        gateId,
+        approver: input.approver,
+        approvedAt,
+        alreadyApproved: false,
+    };
+}
 export async function showApproval(id, root = process.cwd()) {
     const record = await getApprovalRecord(id, root);
     const content = await readFile(path.join(root, record.artifact), "utf8");
@@ -744,7 +1038,7 @@ export async function approveApproval(input, root = process.cwd()) {
 export async function rejectApproval(input, root = process.cwd()) {
     return recordApprovalDecision(input, "rejected", root);
 }
-export async function recordReview(input, root = process.cwd()) {
+export async function recordReview(input, root = process.cwd(), notificationTransports = {}) {
     const workspace = await loadWorkspace(root);
     const reviewInput = removeUndefined({
         ...input,
@@ -770,6 +1064,17 @@ export async function recordReview(input, root = process.cwd()) {
         artifacts: [artifact],
         metadata: { result: reviewInput.result, severity: reviewInput.severity },
     });
+    if (reviewInput.result === "block" && reviewInput.severity === "critical") {
+        await notifyWorkflowLifecycle({
+            root,
+            taskId: reviewInput.task,
+            kind: "critical_blocking_review",
+            actor: reviewInput.role,
+            detail: reviewInput.findings,
+            artifact,
+            idempotencyKey: `critical_blocking_review:${reviewInput.task}:${artifact}`,
+        }, notificationTransports);
+    }
     return { artifact, content };
 }
 function riskReviewSteps(impactAreas) {
@@ -982,6 +1287,7 @@ export async function completeWithProviderFallback(routing, prompt, { failingPro
             const response = await provider.complete({
                 model: routing.model,
                 jsonMode,
+                timeoutMs: routing.timeoutMs,
                 messages: [{ role: "user", content: prompt }],
             });
             if (index > 0) {
@@ -1002,6 +1308,9 @@ export async function completeWithProviderFallback(routing, prompt, { failingPro
             };
         }
         catch (error) {
+            if (isProviderTimeoutError(error)) {
+                throw error;
+            }
             failedProviders.push({
                 provider: providerId,
                 reason: error instanceof Error ? error.message : String(error),
@@ -1012,6 +1321,14 @@ export async function completeWithProviderFallback(routing, prompt, { failingPro
         .map((failure) => failure.provider)
         .join(", ")}`);
 }
+function isProviderTimeoutError(error) {
+    if (!(error instanceof Error)) {
+        return String(error).toLowerCase().includes("timeout");
+    }
+    return (error.name === "TimeoutError" ||
+        error.name === "AbortError" ||
+        error.message.toLowerCase().includes("timeout"));
+}
 export async function setRoleModelProvider(role, routing, root = process.cwd()) {
     const workspace = await loadWorkspace(root);
     if (!workspace.roleIds.has(role)) {
@@ -1076,7 +1393,13 @@ export async function checkUsageBudget(taskId, root = process.cwd()) {
         }
     }
     const usage = await getUsageReport(taskId, root);
-    const budgets = config.budgets;
+    const workspace = taskId ? await loadWorkspace(root) : undefined;
+    const ownerRole = taskId
+        ? workspace?.tasks.find((task) => task.id === taskId)?.ownerRole
+        : undefined;
+    return checkUsageBudgetForUsage(taskId, ownerRole, usage, config.budgets);
+}
+async function checkUsageBudgetForUsage(taskId, ownerRole, usage, budgets) {
     const appliedBudgets = [];
     const violations = [];
     if (budgets?.defaults) {
@@ -1094,6 +1417,12 @@ export async function checkUsageBudget(taskId, root = process.cwd()) {
             violations.push(...budgetViolations(`role:${roleUsage.key}`, roleUsage, roleBudget));
         }
     }
+    if (ownerRole &&
+        budgets?.byRole?.[ownerRole] &&
+        !usage.byRole.some((roleUsage) => roleUsage.key === ownerRole)) {
+        appliedBudgets.push(`role:${ownerRole}`);
+        violations.push(...budgetViolations(`role:${ownerRole}`, emptyUsageBreakdown(ownerRole), budgets.byRole[ownerRole]));
+    }
     return {
         ...(taskId ? { taskId } : {}),
         passed: violations.length === 0,
@@ -1102,6 +1431,39 @@ export async function checkUsageBudget(taskId, root = process.cwd()) {
         violations,
     };
 }
+async function enforceBudgetEstimatePreflight(taskId, root, estimatedCostUsd, override) {
+    const preflight = await checkBudgetEstimatePreflight(taskId, estimatedCostUsd, root);
+    if (preflight.warnings.length > 0) {
+        await appendEvent(root, {
+            type: "BUDGET_PREFLIGHT_WARNING",
+            taskId,
+            actor: "parent",
+            summary: "Estimated cost reached budget warning threshold",
+            metadata: { preflight },
+        });
+    }
+    if (preflight.passed) {
+        return;
+    }
+    if (override) {
+        await appendEvent(root, {
+            type: "BUDGET_PREFLIGHT_OVERRIDDEN",
+            taskId,
+            actor: "parent",
+            summary: "Estimated cost budget block overridden",
+            metadata: { preflight },
+        });
+        return;
+    }
+    await appendEvent(root, {
+        type: "BUDGET_PREFLIGHT_BLOCKED",
+        taskId,
+        actor: "parent",
+        summary: "Estimated cost exceeds configured budget",
+        metadata: { preflight },
+    });
+    throw new Error("budget estimate exceeds configured limit; rerun with --yes to override");
+}
 async function createBudgetFallbackProposal(taskId, budget, root) {
     const workspace = await loadWorkspace(root);
     const task = workspace.tasks.find((candidate) => candidate.id === taskId);
@@ -1186,6 +1548,39 @@ function approvalRecordForArtifact(artifact, events) {
             : undefined,
     });
 }
+function gateApprovalRecords(events) {
+    return events
+        .filter((event) => event.type === "GATE_APPROVED")
+        .map((event) => {
+        const runId = typeof event.metadata.runId === "string" ? event.metadata.runId : "run";
+        const gateId = typeof event.metadata.gateId === "string"
+            ? event.metadata.gateId
+            : "gate";
+        return removeUndefined({
+            id: `gate-${runId}-${gateId}`.replace(/[^a-zA-Z0-9._-]/g, "-"),
+            taskId: event.taskId ?? undefined,
+            artifact: event.artifacts?.[0] ?? "events.jsonl",
+            status: "approved",
+            summary: event.summary,
+            requestedAt: event.timestamp,
+            decidedAt: typeof event.metadata.approvedAt === "string"
+                ? event.metadata.approvedAt
+                : event.timestamp,
+            approver: typeof event.metadata.approver === "string"
+                ? event.metadata.approver
+                : undefined,
+            rationale: typeof event.metadata.rationale === "string"
+                ? event.metadata.rationale
+                : undefined,
+        });
+    });
+}
+function gateIdForPhase(run, phaseIndex) {
+    const phase = run.phases[phaseIndex]?.phase;
+    const sequenceIndex = AUTONOMOUS_PHASE_SEQUENCE.findIndex((candidate) => candidate.phase === phase);
+    const next = AUTONOMOUS_PHASE_SEQUENCE[sequenceIndex + 1]?.phase ?? "end";
+    return `${phase}->${next}`;
+}
 function approvalEventsForArtifact(events, artifact) {
     return events.filter((event) => event.artifacts?.includes(artifact));
 }
@@ -1258,6 +1653,60 @@ function budgetViolation(scope, metric, actual, limit) {
         limit,
     };
 }
+function projectUsageCost(usage, ownerRole, estimatedCostUsd) {
+    const byRole = [...usage.byRole];
+    const roleIndex = byRole.findIndex((entry) => entry.key === ownerRole);
+    if (roleIndex >= 0) {
+        const roleUsage = byRole[roleIndex] ?? emptyUsageBreakdown(ownerRole);
+        byRole[roleIndex] = addEstimatedCost(roleUsage, estimatedCostUsd);
+    }
+    else {
+        byRole.push(addEstimatedCost(emptyUsageBreakdown(ownerRole), estimatedCostUsd));
+    }
+    return {
+        ...usage,
+        totals: addEstimatedCost(usage.totals, estimatedCostUsd),
+        byRole,
+    };
+}
+function addEstimatedCost(usage, estimatedCostUsd) {
+    return {
+        ...usage,
+        estimatedCostUsd: usage.estimatedCostUsd + estimatedCostUsd,
+    };
+}
+function emptyUsageBreakdown(key) {
+    return {
+        key,
+        requests: 0,
+        inputTokens: 0,
+        outputTokens: 0,
+        totalTokens: 0,
+        estimatedCostUsd: 0,
+    };
+}
+function budgetEstimateWarningsForBudgets(taskId, ownerRole, usage, budgets) {
+    const warnings = [];
+    pushCostWarning(warnings, "defaults", usage.totals, budgets?.defaults);
+    pushCostWarning(warnings, `task:${taskId}`, usage.totals, budgets?.byTask?.[taskId]);
+    pushCostWarning(warnings, `role:${ownerRole}`, usage.byRole.find((roleUsage) => roleUsage.key === ownerRole) ??
+        emptyUsageBreakdown(ownerRole), budgets?.byRole?.[ownerRole]);
+    return warnings;
+}
+function pushCostWarning(warnings, scope, usage, budget) {
+    const thresholdPercent = 80;
+    const limit = budget?.maxEstimatedCostUsd;
+    if (limit !== undefined &&
+        usage.estimatedCostUsd >= limit * (thresholdPercent / 100)) {
+        warnings.push({
+            scope,
+            metric: "estimatedCostUsd",
+            actual: usage.estimatedCostUsd,
+            limit,
+            thresholdPercent,
+        });
+    }
+}
 async function writeBudgetEscalationProposal(root, taskId, proposal) {
     const content = [
         `# Budget Escalation Proposal: ${taskId}`,
@@ -1305,6 +1754,21 @@ async function mutateTasks(base, update) {
 async function mutateLocks(base, update) {
     return updateJsonFile(path.join(base, FILES.locks), [], update);
 }
+function assertTaskCanBeRemoved(task, tasks, isForced) {
+    if (!isForced &&
+        (task.status === "in_progress" || task.status === "blocked")) {
+        throw new Error(`task ${task.id} is ${task.status}; use --force to remove it`);
+    }
+    const dependent = tasks.find((candidate) => candidate.id !== task.id &&
+        !isTerminalTaskStatus(candidate.status) &&
+        candidate.dependencies.includes(task.id));
+    if (dependent) {
+        throw new Error(`task ${task.id} is a dependency of active task ${dependent.id}`);
+    }
+}
+function isTerminalTaskStatus(status) {
+    return ["done", "canceled", "rejected", "archived"].includes(status);
+}
 function flowRequirementLines(requirements) {
     return requirements.length > 0
         ? requirements.map((requirement) => `- ${requirement}`)