@kontextmind/kxm 0.7.115 → 0.7.118

package/packages/core/tui/src/adapters/historyExport.ts

@@ -0,0 +1,35 @@
+/**
+ * History export adapter for local disk persistence.
+ */
+
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import {
+  renderWorkflowHistoryMarkdown,
+  formatWorkflowHistoryJsonl,
+  type HistoryEventItem,
+} from "../tui/history.ts";
+
+export interface ExportedHistoryFiles {
+  readonly mdPath: string;
+  readonly jsonlPath: string;
+}
+
+/**
+ * Export workflow history into both Markdown retrospective and JSONL audit logs on disk.
+ */
+export function exportWorkflowHistory(
+  runId: string,
+  events: readonly HistoryEventItem[],
+  destinationDir: string,
+): ExportedHistoryFiles {
+  mkdirSync(destinationDir, { recursive: true });
+  const sanitizedRunId = runId.replaceAll(/[^a-zA-Z0-9_-]/g, "_");
+  const mdPath = join(destinationDir, `retrospective-${sanitizedRunId}.md`);
+  const jsonlPath = join(destinationDir, `history-${sanitizedRunId}.jsonl`);
+
+  writeFileSync(mdPath, renderWorkflowHistoryMarkdown(runId, events), "utf8");
+  writeFileSync(jsonlPath, formatWorkflowHistoryJsonl(runId, events), "utf8");
+
+  return { mdPath, jsonlPath };
+}

package/packages/core/tui/src/adapters/omp.ts

@@ -0,0 +1,174 @@
+/**
+ * OMP (Oh My Pi) overlay adapter.
+ *
+ * Provides a collapsible, differential-rendered task & plan overlay
+ * designed for OMP's overlay stack and custom TUI components.
+ *
+ * Supports:
+ * - Collapsed status HUD (single-line strip) vs Expanded 3-pane dashboard
+ * - Interactive task reordering (Shift+Up / Shift+Down)
+ * - Auto-dispatch flag toggling ('a' key)
+ * - On-demand plan optimizer ('o' key)
+ * - Full workflow history view ('h' key) with dual markdown + JSONL export ('x' key)
+ */
+
+import { KxmTuiPanelComponent } from "../tui/panelComponent.ts";
+import type { KxmTuiRegistry } from "../services/registry.ts";
+import { createKxmTuiThemeFromPi, type PiThemeLike, type KxmTuiTheme } from "../tui/theme.ts";
+import type { KxmTuiCustomComponent, KxmTuiCustomTui } from "./pi.ts";
+
+export type OverlayMode = "collapsed" | "expanded" | "history" | "optimizer";
+
+export interface KxmTuiOmpOverlayOptions {
+  readonly registry: KxmTuiRegistry;
+  readonly tui: KxmTuiCustomTui;
+  readonly theme: PiThemeLike | KxmTuiTheme;
+  readonly title: string;
+  readonly goal?: string | undefined;
+  readonly initialMode?: OverlayMode | undefined;
+  readonly autoDispatch?: boolean | undefined;
+  readonly onToggleAutoDispatch?: ((auto: boolean) => void) | undefined;
+  readonly onReorderTasks?: ((fromIndex: number, toIndex: number) => void) | undefined;
+  readonly onRunOptimizer?: (() => Promise<{ savingsTokens: number; savingsSeconds: number } | void>) | undefined;
+  readonly onExportHistory?: ((format: "both" | "md" | "jsonl") => Promise<{ mdPath?: string; jsonlPath?: string }>) | undefined;
+  readonly width?: (() => number) | undefined;
+  readonly done?: ((closed: true) => void) | undefined;
+}
+
+export interface KxmTuiOmpOverlayComponent extends KxmTuiCustomComponent {
+  getMode(): OverlayMode;
+  setMode(mode: OverlayMode): void;
+  isAutoDispatch(): boolean;
+  toggleAutoDispatch(): void;
+  dispose(): void;
+}
+
+function resolveKxmTheme(theme: PiThemeLike | KxmTuiTheme): KxmTuiTheme {
+  if ("headerBg" in theme && typeof (theme as KxmTuiTheme).headerBg === "function") {
+    return theme as KxmTuiTheme;
+  }
+  return createKxmTuiThemeFromPi(theme as PiThemeLike);
+}
+
+export function createKxmTuiOmpOverlay(options: KxmTuiOmpOverlayOptions): KxmTuiOmpOverlayComponent {
+  let closed = false;
+  let mode: OverlayMode = options.initialMode ?? "expanded";
+  let autoDispatch = Boolean(options.autoDispatch);
+  const theme: KxmTuiTheme = resolveKxmTheme(options.theme);
+
+  const panel = new KxmTuiPanelComponent({
+    registry: options.registry,
+    theme,
+    title: options.title,
+    ...(options.goal ? { breadcrumb: `Goal: ${options.goal}` } : {}),
+    helpLines: [
+      "[Ctrl+O/F2] Toggle Fold  [h] History  [a] Toggle Auto  [o] Optimize  [Shift+↑/↓] Reorder",
+    ],
+    requestRender: () => options.tui.requestRender(),
+    onQuit: () => {
+      if (closed) return;
+      closed = true;
+      panel.dispose();
+      options.done?.(true);
+    },
+    ...(options.width === undefined ? {} : { getWidth: options.width }),
+  });
+
+  function renderCollapsed(width: number): string[] {
+    const goalText = options.goal ? `Goal: ${options.goal}` : options.title;
+    const modeBadge = autoDispatch ? theme.accent("[AUTO: ON]") : theme.dim("[STEP MODE]");
+    const hint = theme.dim("[Ctrl+O to Expand]");
+    const content = ` [KXM] ${goalText} ── ${modeBadge} ── ${hint}`;
+    const pad = Math.max(0, width - content.length);
+    return [content + " ".repeat(pad)];
+  }
+
+  function handleInput(data: string): void {
+    if (closed) return;
+
+    // Toggle collapse: Ctrl+O (\x0f) or F2 (\x1bOQ or \x1b[12~)
+    if (data === "\x0f" || data === "\x1bOQ" || data === "\x1b[12~") {
+      mode = mode === "collapsed" ? "expanded" : "collapsed";
+      options.tui.requestRender();
+      return;
+    }
+
+    // When collapsed, only toggle/expand is handled
+    if (mode === "collapsed") {
+      if (data === "\r" || data === " " || data === "o" || data === "O") {
+        mode = "expanded";
+        options.tui.requestRender();
+      }
+      return;
+    }
+
+    // Toggle Auto-dispatch flag
+    if (data === "a" || data === "A") {
+      autoDispatch = !autoDispatch;
+      options.onToggleAutoDispatch?.(autoDispatch);
+      options.tui.requestRender();
+      return;
+    }
+
+    // History mode toggle
+    if (data === "h" || data === "H") {
+      mode = mode === "history" ? "expanded" : "history";
+      options.tui.requestRender();
+      return;
+    }
+
+    // Optimizer invocation
+    if (data === "o" || data === "O") {
+      mode = "optimizer";
+      options.onRunOptimizer?.();
+      options.tui.requestRender();
+      return;
+    }
+
+    // Export history in both formats
+    if ((data === "x" || data === "X") && mode === "history") {
+      options.onExportHistory?.("both");
+      options.tui.requestRender();
+      return;
+    }
+
+    // Escape in sub-modes returns to expanded
+    if (data === "\x1b" && mode !== "expanded") {
+      mode = "expanded";
+      options.tui.requestRender();
+      return;
+    }
+
+    // Forward to underlying KXM panel component
+    panel.handleInput(data);
+    options.tui.requestRender();
+  }
+
+  return {
+    getMode: () => mode,
+    setMode: (nextMode: OverlayMode) => {
+      mode = nextMode;
+      options.tui.requestRender();
+    },
+    isAutoDispatch: () => autoDispatch,
+    toggleAutoDispatch: () => {
+      autoDispatch = !autoDispatch;
+      options.onToggleAutoDispatch?.(autoDispatch);
+      options.tui.requestRender();
+    },
+    render: (width: number) => {
+      if (mode === "collapsed") {
+        return renderCollapsed(width);
+      }
+      return panel.render(width);
+    },
+    handleInput,
+    invalidate: () => panel.invalidate(),
+    dispose: () => {
+      if (closed) return;
+      closed = true;
+      panel.dispose();
+      options.done?.(true);
+    },
+  };
+}

package/packages/core/tui/src/adapters/pi.ts

@@ -13,6 +13,11 @@
 import { KxmTuiPanelComponent } from "../tui/panelComponent.ts";
 import type { KxmTuiRegistry } from "../services/registry.ts";
 import { createKxmTuiThemeFromPi, type PiThemeLike } from "../tui/theme.ts";
+import {
+  createKxmTuiOmpOverlay,
+  type KxmTuiOmpOverlayComponent,
+  type KxmTuiOmpOverlayOptions,
+} from "./omp.ts";
 
 /** The renderer handle Pi passes to a custom component. */
 export interface KxmTuiCustomTui {
@@ -38,6 +43,35 @@ export interface KxmTuiPiPanelOptions {
   readonly done?: (closed: true) => void;
 }
 
+export interface KxmTuiPiOverlayOptions extends KxmTuiOmpOverlayOptions {}
+export type KxmTuiPiOverlayComponent = KxmTuiOmpOverlayComponent;
+
+/**
+ * Create a collapsible Task & Plan overlay for Pi.
+ *
+ * Reuses the differential rendering engine and OMP overlay model,
+ * compatible with Pi's `ctx.ui.custom` hook and keybinding stack.
+ */
+export const createKxmTuiPiOverlay = createKxmTuiOmpOverlay;
+
+/**
+ * Format widget lines for Pi's `ctx.ui.setWidget`.
+ */
+export function renderPiWorkflowWidget(options: {
+  readonly goal: string;
+  readonly stage: string;
+  readonly progressPercent: number;
+  readonly activeTask?: string | undefined;
+  readonly autoDispatch?: boolean | undefined;
+}): string[] {
+  const filled = Math.min(10, Math.max(0, Math.round((options.progressPercent / 100) * 10)));
+  const bar = `[${"█".repeat(filled)}${"░".repeat(10 - filled)}] ${options.progressPercent}%`;
+  const mode = options.autoDispatch ? "AUTO" : "STEP";
+  const line1 = `[KXM] Goal: ${options.goal} ── Stage: ${options.stage} (${bar}) [${mode}]`;
+  const line2 = options.activeTask ? `  Active: ${options.activeTask}` : `  Waiting for next dispatch (use /kxm progress)`;
+  return [line1, line2];
+}
+
 /**
  * Build the object to return from `ctx.ui.custom`.
  *

package/packages/core/tui/src/exports/index.ts

@@ -25,6 +25,14 @@ export * from "../tui/theme.ts";
 export * from "../tui/panel.ts";
 export * from "../tui/render.ts";
 export * from "../tui/panelComponent.ts";
+export * from "../tui/optimizer.ts";
+export * from "../tui/history.ts";
+export * from "../tui/queue.ts";
+export * from "../tui/roleBudget.ts";
+export * from "../tui/modelSelector.ts";
 export * from "../services/registry.ts";
 export * from "../adapters/terminal.ts";
 export * from "../adapters/pi.ts";
+export * from "../adapters/omp.ts";
+export * from "../adapters/claude.ts";
+export * from "../adapters/historyExport.ts";

package/packages/core/tui/src/tui/history.ts

@@ -0,0 +1,106 @@
+/**
+ * Workflow History & Journal View Engine.
+ *
+ * Tracks the complete chronological lifecycle of the active run:
+ * - Event classification (Tasks, Gates, Retries, Peers, State)
+ * - Filtering by category and search query
+ * - Dual format generators: clean Markdown retrospective + JSONL audit ledger
+ */
+
+export type HistoryCategory = "all" | "task" | "gate" | "retry" | "peer" | "state";
+
+export interface HistoryEventItem {
+  readonly id: string;
+  readonly timestamp: string;
+  readonly category: Exclude<HistoryCategory, "all">;
+  readonly title: string;
+  readonly stageId?: string | undefined;
+  readonly taskId?: string | undefined;
+  readonly role?: string | undefined;
+  readonly harness?: string | undefined;
+  readonly model?: string | undefined;
+  readonly attempt?: number | undefined;
+  readonly status: "passed" | "failed" | "warning" | "in_flight" | "degraded";
+  readonly durationMs?: number | undefined;
+  readonly tokensIn?: number | undefined;
+  readonly tokensOut?: number | undefined;
+  readonly costUsd?: number | undefined;
+  readonly artifacts?: readonly string[] | undefined;
+  readonly evidenceHashes?: readonly string[] | undefined;
+  readonly journalSummary?: string | undefined;
+}
+
+export interface HistoryFilterOptions {
+  readonly category?: HistoryCategory | undefined;
+  readonly query?: string | undefined;
+}
+
+/**
+ * Filter history items by category and substring query.
+ */
+export function filterHistoryEvents(
+  events: readonly HistoryEventItem[],
+  options: HistoryFilterOptions = {},
+): HistoryEventItem[] {
+  const category = options.category ?? "all";
+  const query = options.query?.trim().toLowerCase();
+
+  return events.filter((ev) => {
+    if (category !== "all" && ev.category !== category) return false;
+    if (!query) return true;
+    const matchTarget = `${ev.id} ${ev.title} ${ev.stageId ?? ""} ${ev.taskId ?? ""} ${ev.role ?? ""} ${ev.model ?? ""} ${ev.journalSummary ?? ""}`.toLowerCase();
+    return matchTarget.includes(query);
+  });
+}
+
+/**
+ * Render retrospective markdown text from workflow events.
+ */
+export function renderWorkflowHistoryMarkdown(
+  runId: string,
+  events: readonly HistoryEventItem[],
+): string {
+  const totalSpend = events.reduce((acc, ev) => acc + (ev.costUsd ?? 0), 0);
+  const passedCount = events.filter((ev) => ev.status === "passed").length;
+  const failedCount = events.filter((ev) => ev.status === "failed").length;
+
+  let mdContent = `# KXM Workflow Retrospective: ${runId}\n\n`;
+  mdContent += `**Total Events:** ${events.length} (Passed: ${passedCount}, Failed: ${failedCount})\n`;
+  mdContent += `**Total Spend:** $${totalSpend.toFixed(4)} USD\n\n`;
+  mdContent += `## Chronological Event Journal\n\n`;
+  mdContent += `| Timestamp | Category | Title | Status | Role / Model | Duration | Spend |\n`;
+  mdContent += `|---|---|---|---|---|---|---|\n`;
+
+  for (const ev of events) {
+    const elapsed = ev.durationMs !== undefined ? `${(ev.durationMs / 1000).toFixed(1)}s` : "-";
+    const spend = ev.costUsd !== undefined ? `$${ev.costUsd.toFixed(4)}` : "-";
+    const roleModel = ev.role ? `${ev.role} (${ev.harness ?? "-"}/${ev.model ?? "-"})` : "-";
+    mdContent += `| ${ev.timestamp} | ${ev.category} | ${ev.title} | ${ev.status} | ${roleModel} | ${elapsed} | ${spend} |\n`;
+  }
+
+  mdContent += `\n## Produced Artifacts & Proofs\n\n`;
+  for (const ev of events) {
+    if (ev.artifacts && ev.artifacts.length > 0) {
+      mdContent += `### ${ev.title} (${ev.id})\n`;
+      for (const art of ev.artifacts) {
+        mdContent += `- \`${art}\`\n`;
+      }
+    }
+  }
+
+  return mdContent;
+}
+
+/**
+ * Format JSONL audit ledger lines from workflow events.
+ */
+export function formatWorkflowHistoryJsonl(
+  runId: string,
+  events: readonly HistoryEventItem[],
+): string {
+  return events.map((ev) => JSON.stringify({
+    schema: "kxm.workflow-history-event.v1",
+    runId,
+    ...ev,
+  })).join("\n") + "\n";
+}

package/packages/core/tui/src/tui/modelSelector.ts

@@ -0,0 +1,43 @@
+/**
+ * Model Selector & Provider Authentication Model.
+ *
+ * Provides fast fuzzy filtering, capability inspection, and
+ * provider readiness status across all supported harnesses.
+ */
+
+export interface ModelOptionItem {
+  readonly id: string;
+  readonly selector: string;
+  readonly name: string;
+  readonly provider: string;
+  readonly harness: string;
+  readonly contextWindow: number;
+  readonly maxTokens?: number | undefined;
+  readonly reasoning: boolean;
+  readonly thinkingLevels?: readonly string[] | undefined;
+  readonly cost: {
+    readonly inputPerMillion: number;
+    readonly outputPerMillion: number;
+    readonly cacheReadPerMillion?: number | undefined;
+  };
+  readonly authStatus: "ready" | "missing_auth" | "unprobed";
+  readonly authHint?: string | undefined;
+}
+
+export function filterModelOptions(
+  models: readonly ModelOptionItem[],
+  query?: string | undefined,
+  providerFilter?: string | undefined,
+): ModelOptionItem[] {
+  const q = query?.trim().toLowerCase();
+  const prov = providerFilter?.trim().toLowerCase();
+
+  return models.filter((m) => {
+    if (prov && m.provider.toLowerCase() !== prov && m.harness.toLowerCase() !== prov) {
+      return false;
+    }
+    if (!q) return true;
+    const matchTarget = `${m.id} ${m.selector} ${m.name} ${m.provider} ${m.harness}`.toLowerCase();
+    return matchTarget.includes(q);
+  });
+}

package/packages/core/tui/src/tui/optimizer.ts

@@ -0,0 +1,154 @@
+/**
+ * Plan Optimizer Engine.
+ *
+ * Analyzes upcoming tasks against dependency graphs, token footprints,
+ * and harness/model capabilities to generate concrete proposals for:
+ * 1. Concurrency (parallel fanout for independent tasks)
+ * 2. Cost (downscaling lightweight tasks to faster/cheaper models)
+ * 3. Reordering (failing fast on syntax/lint before heavier passes)
+ */
+
+export interface OptimizerTaskInput {
+  readonly id: string;
+  readonly title: string;
+  readonly stageId: string;
+  readonly role: string;
+  readonly harness: string;
+  readonly model: string;
+  readonly dependencies: readonly string[];
+  readonly estimatedTokens?: number | undefined;
+  readonly category?: "implementation" | "test" | "docs" | "lint" | "security" | undefined;
+}
+
+export interface OptimizationProposal {
+  readonly id: string;
+  readonly category: "concurrency" | "cost" | "reorder" | "slice";
+  readonly title: string;
+  readonly description: string;
+  readonly targetTaskIds: readonly string[];
+  readonly projectedTimeSavingsSeconds: number;
+  readonly projectedCostSavingsPercent: number;
+  readonly suggestedModel?: string | undefined;
+  readonly suggestedHarness?: string | undefined;
+  readonly selected: boolean;
+}
+
+export interface OptimizerResult {
+  readonly proposals: readonly OptimizationProposal[];
+  readonly totalProjectedTimeSavingsSeconds: number;
+  readonly totalProjectedCostSavingsPercent: number;
+}
+
+/**
+ * Analyze a task queue and generate optimization proposals.
+ */
+export function evaluatePlanOptimizations(tasks: readonly OptimizerTaskInput[]): OptimizerResult {
+  const proposals: OptimizationProposal[] = [];
+
+  // 1. Detect Parallel Fanout Opportunities (tasks with no mutual dependencies in the same stage)
+  const byStage = new Map<string, OptimizerTaskInput[]>();
+  for (const task of tasks) {
+    const list = byStage.get(task.stageId) ?? [];
+    list.push(task);
+    byStage.set(task.stageId, list);
+  }
+
+  for (const [stageId, stageTasks] of byStage) {
+    if (stageTasks.length >= 2) {
+      const independent = stageTasks.filter((t) => t.dependencies.length === 0 || t.dependencies.every((dep) => !stageTasks.some((st) => st.id === dep)));
+      if (independent.length >= 2) {
+        proposals.push({
+          id: `opt_fanout_${stageId}`,
+          category: "concurrency",
+          title: `Parallelize ${independent.length} tasks in stage "${stageId}"`,
+          description: `Tasks [${independent.map((t) => t.id).join(", ")}] have zero mutual dependencies and can execute concurrently via kxm_fanout.`,
+          targetTaskIds: independent.map((t) => t.id),
+          projectedTimeSavingsSeconds: Math.round(independent.length * 15),
+          projectedCostSavingsPercent: 0,
+          selected: true,
+        });
+      }
+    }
+  }
+
+  // 2. Detect Cost/Model Downscaling Opportunities (Docs or Lint on top-tier frontier models)
+  for (const task of tasks) {
+    const isFrontier = /claude-3-5-sonnet|claude-3-opus|gpt-4o|gpt-5/i.test(task.model);
+    if (isFrontier && (task.category === "docs" || /doc|readme|markdown/i.test(task.title))) {
+      proposals.push({
+        id: `opt_cost_${task.id}`,
+        category: "cost",
+        title: `Downscale model for documentation task "${task.title}"`,
+        description: `Task "${task.id}" is documentation-focused. Routing to a high-throughput lightweight model saves significant token budget.`,
+        targetTaskIds: [task.id],
+        projectedTimeSavingsSeconds: 5,
+        projectedCostSavingsPercent: 65,
+        suggestedHarness: "pi",
+        suggestedModel: "qwen/qwen3-coder-plus",
+        selected: true,
+      });
+    } else if (isFrontier && (task.category === "lint" || /lint|format|style/i.test(task.title))) {
+      proposals.push({
+        id: `opt_lint_${task.id}`,
+        category: "cost",
+        title: `Downscale model for formatting/lint task "${task.title}"`,
+        description: `Task "${task.id}" performs deterministic formatting/linting. Use a fast local/tier-1 helper.`,
+        targetTaskIds: [task.id],
+        projectedTimeSavingsSeconds: 8,
+        projectedCostSavingsPercent: 80,
+        suggestedHarness: "pi",
+        suggestedModel: "google/gemini-2.5-flash",
+        selected: true,
+      });
+    }
+  }
+
+  const totalTimeSavings = proposals.reduce((acc, p) => acc + p.projectedTimeSavingsSeconds, 0);
+  const totalCostSavings = proposals.length > 0
+    ? Math.round(proposals.reduce((acc, p) => acc + p.projectedCostSavingsPercent, 0) / proposals.length)
+    : 0;
+
+  return {
+    proposals,
+    totalProjectedTimeSavingsSeconds: totalTimeSavings,
+    totalProjectedCostSavingsPercent: totalCostSavings,
+  };
+}
+
+/**
+ * Apply selected proposals to the task queue.
+ */
+export function applyPlanOptimizations<T extends OptimizerTaskInput>(
+  tasks: readonly T[],
+  proposals: readonly OptimizationProposal[],
+): { tasks: T[]; appliedCount: number } {
+  const selected = proposals.filter((p) => p.selected);
+  if (selected.length === 0) return { tasks: [...tasks], appliedCount: 0 };
+
+  const modelOverrides = new Map<string, { harness?: string; model?: string }>();
+  for (const proposal of selected) {
+    if (proposal.category === "cost" && proposal.suggestedModel) {
+      for (const targetId of proposal.targetTaskIds) {
+        modelOverrides.set(targetId, {
+          ...(proposal.suggestedHarness ? { harness: proposal.suggestedHarness } : {}),
+          model: proposal.suggestedModel,
+        });
+      }
+    }
+  }
+
+  const updated = tasks.map((task) => {
+    const override = modelOverrides.get(task.id);
+    if (!override) return task;
+    return {
+      ...task,
+      ...(override.harness ? { harness: override.harness } : {}),
+      ...(override.model ? { model: override.model } : {}),
+    };
+  });
+
+  return {
+    tasks: updated,
+    appliedCount: selected.length,
+  };
+}

package/packages/core/tui/src/tui/queue.ts

@@ -0,0 +1,90 @@
+/**
+ * Task Queue & Topological Reordering Engine.
+ *
+ * Manages upcoming tasks in the execution queue with safety guards:
+ * - Detects prerequisite violations when moving a task before its dependencies
+ * - Prevents circular dependency cycles
+ * - Shifts tasks safely up or down
+ */
+
+export interface QueuedTaskItem {
+  readonly id: string;
+  readonly title: string;
+  readonly stageId: string;
+  readonly role: string;
+  readonly harness: string;
+  readonly model: string;
+  readonly status: "completed" | "in_flight" | "pending" | "blocked" | "failed";
+  readonly dependencies: readonly string[];
+  readonly attempt: number;
+  readonly maxAttempts: number;
+  readonly estimatedDurationSec?: number | undefined;
+  readonly estimatedCostUsd?: number | undefined;
+}
+
+export interface ReorderResult {
+  readonly success: boolean;
+  readonly tasks: readonly QueuedTaskItem[];
+  readonly warning?: string | undefined;
+}
+
+/**
+ * Reorder a task in the upcoming queue with dependency validation.
+ */
+export function reorderQueuedTasks(
+  tasks: readonly QueuedTaskItem[],
+  fromIndex: number,
+  toIndex: number,
+): ReorderResult {
+  if (
+    fromIndex < 0 ||
+    fromIndex >= tasks.length ||
+    toIndex < 0 ||
+    toIndex >= tasks.length ||
+    fromIndex === toIndex
+  ) {
+    return { success: false, tasks, warning: "invalid_indices" };
+  }
+
+  const target = tasks[fromIndex]!;
+
+  // Cannot reorder in-flight or completed tasks
+  if (target.status === "in_flight" || target.status === "completed") {
+    return {
+      success: false,
+      tasks,
+      warning: `cannot move ${target.status} task "${target.id}"`,
+    };
+  }
+
+  // Create mutable copy and move
+  const draft = [...tasks];
+  const [removed] = draft.splice(fromIndex, 1);
+  draft.splice(toIndex, 0, removed!);
+
+  // Validate dependencies:
+  // For every task at index i, none of its dependencies can appear at index j > i.
+  const idToIndex = new Map<string, number>();
+  for (let i = 0; i < draft.length; i++) {
+    idToIndex.set(draft[i]!.id, i);
+  }
+
+  for (let i = 0; i < draft.length; i++) {
+    const task = draft[i]!;
+    for (const depId of task.dependencies) {
+      const depIndex = idToIndex.get(depId);
+      if (depIndex !== undefined && depIndex > i) {
+        return {
+          success: false,
+          tasks,
+          warning: `Prerequisite violation: "${task.id}" depends on "${depId}", which is scheduled later at position ${depIndex + 1}`,
+        };
+      }
+    }
+  }
+
+  return {
+    success: true,
+    tasks: draft,
+  };
+}