@dv.nghiem/flowdeck 0.4.8 → 0.4.10

package/dist/index.js

@@ -1,6 +1,6 @@
 // src/index.ts
-import { readFileSync as readFileSync24, readdirSync as readdirSync3, existsSync as existsSync25 } from "fs";
-import { join as join24, basename as basename2 } from "path";
+import { readFileSync as readFileSync25, readdirSync as readdirSync3, existsSync as existsSync27 } from "fs";
+import { join as join26, basename as basename2 } from "path";
 import { dirname as dirname3 } from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 
@@ -1994,9 +1994,484 @@ var rtkSetupTool = tool12({
   }
 });
 
-// src/hooks/guard-rails.ts
-import { existsSync as existsSync16, readFileSync as readFileSync16 } from "fs";
+// src/tools/merge-assist.ts
+import { tool as tool13 } from "@opencode-ai/plugin";
+import { readFileSync as readFileSync15, writeFileSync as writeFileSync11, existsSync as existsSync16, mkdirSync as mkdirSync10 } from "fs";
 import { join as join16 } from "path";
+import { spawnSync as spawnSync3 } from "child_process";
+
+// src/lib/logger.ts
+import { appendFileSync as appendFileSync3, existsSync as existsSync15, mkdirSync as mkdirSync9 } from "fs";
+import { join as join15 } from "path";
+var LOG_DIR = ".opencode";
+var LOG_FILE = "flowdeck.log";
+function ensureLogDir(logDir) {
+  if (!existsSync15(logDir)) {
+    mkdirSync9(logDir, { recursive: true });
+  }
+}
+function logWrite(directory, level, source, message) {
+  const logDir = join15(directory, LOG_DIR);
+  const logFile = join15(logDir, LOG_FILE);
+  try {
+    ensureLogDir(logDir);
+    const entry = {
+      timestamp: new Date().toISOString(),
+      level,
+      source,
+      message
+    };
+    appendFileSync3(logFile, JSON.stringify(entry) + `
+`, "utf-8");
+  } catch {}
+}
+
+// src/tools/merge-assist.ts
+var MERGE_ASSIST_FILE = "MERGE_ASSIST.json";
+function statePath2(directory) {
+  return join16(codebaseDir(directory), MERGE_ASSIST_FILE);
+}
+function emptyState() {
+  return { version: "1.0", lastUpdated: new Date().toISOString(), sessions: {} };
+}
+function readState(directory) {
+  const p = statePath2(directory);
+  if (!existsSync16(p))
+    return emptyState();
+  try {
+    return JSON.parse(readFileSync15(p, "utf-8"));
+  } catch {
+    return emptyState();
+  }
+}
+function writeState(directory, state) {
+  try {
+    const base = codebaseDir(directory);
+    if (!existsSync16(base))
+      mkdirSync10(base, { recursive: true });
+    const newState = { ...state, lastUpdated: new Date().toISOString() };
+    writeFileSync11(statePath2(directory), JSON.stringify(newState, null, 2), "utf-8");
+    return { success: true };
+  } catch (error) {
+    return { error: error instanceof Error ? error.message : String(error) };
+  }
+}
+function timestamp2() {
+  return new Date().toISOString();
+}
+function generateId() {
+  return `ma-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+}
+function safeGit(cwd, args) {
+  const result = spawnSync3("git", args, { cwd, encoding: "utf-8" });
+  return {
+    stdout: result.stdout?.trim() ?? "",
+    stderr: result.stderr?.trim() ?? "",
+    status: result.status ?? null
+  };
+}
+function isGitRepo(cwd) {
+  return existsSync16(join16(cwd, ".git")) && safeGit(cwd, ["rev-parse", "--git-dir"]).status === 0;
+}
+function branchExists(cwd, branch) {
+  return safeGit(cwd, ["show-ref", "--verify", "--quiet", `refs/heads/${branch}`]).status === 0;
+}
+function getMergeBase(cwd, target, source) {
+  const result = safeGit(cwd, ["merge-base", target, source]);
+  if (result.status !== 0)
+    return null;
+  return result.stdout.trim();
+}
+function getFeatureCommits(cwd, mergeBase, source) {
+  const result = safeGit(cwd, ["log", "--oneline", "--ancestry-path", `${mergeBase}..${source}`]);
+  if (result.status !== 0)
+    return [];
+  return result.stdout.split(`
+`).map((line) => line.trim()).filter(Boolean).map((line) => line.split(" ")[0]).filter(Boolean);
+}
+function getCommitMetadata(cwd, sha) {
+  const result = safeGit(cwd, ["log", "-1", "--format=%H%x00%s%x00%an%x00%ad", "--date=iso", sha]);
+  if (result.status !== 0)
+    return null;
+  const parts = result.stdout.split("\x00");
+  if (parts.length < 4)
+    return null;
+  return { sha: parts[0], subject: parts[1], author: parts[2], date: parts[3] };
+}
+function getCommitFiles(cwd, sha) {
+  const result = safeGit(cwd, ["diff", "--name-only", `${sha}^..${sha}`]);
+  if (result.status !== 0)
+    return [];
+  return result.stdout.split(`
+`).map((f) => f.trim()).filter(Boolean);
+}
+function isLikelyFeatureCommit(subject, files) {
+  const lower = subject.toLowerCase();
+  const featKeywords = ["feat", "feature", "add", "implement", "introduce", "support", "enable"];
+  const depKeywords = ["refactor", "prep", "prepare", "fix", "setup", "wip", "draft", "revert"];
+  const testOnly = files.length > 0 && files.every((f) => f.includes("test") || f.includes("spec"));
+  if (featKeywords.some((k) => lower.includes(k)) && !testOnly) {
+    return { isLikelyFeature: true, confidence: "high" };
+  }
+  if (depKeywords.some((k) => lower.includes(k))) {
+    return { isLikelyFeature: false, confidence: "medium" };
+  }
+  if (testOnly) {
+    return { isLikelyFeature: false, confidence: "medium" };
+  }
+  return { isLikelyFeature: true, confidence: "low" };
+}
+function findCandidateCommits(cwd, sourceBranch, targetBranch) {
+  const mergeBase = getMergeBase(cwd, targetBranch, sourceBranch);
+  if (!mergeBase)
+    return [];
+  const shas = getFeatureCommits(cwd, mergeBase, sourceBranch);
+  const candidates = [];
+  for (const sha of shas) {
+    const meta = getCommitMetadata(cwd, sha);
+    if (!meta)
+      continue;
+    const files = getCommitFiles(cwd, sha);
+    const { isLikelyFeature, confidence } = isLikelyFeatureCommit(meta.subject, files);
+    candidates.push({
+      sha: meta.sha,
+      subject: meta.subject,
+      author: meta.author,
+      date: meta.date,
+      files,
+      isLikelyFeature,
+      confidence
+    });
+  }
+  return candidates;
+}
+function detectDependencies(candidateCommits) {
+  const dependentShas = new Set;
+  const fileToCommits = {};
+  for (const commit of candidateCommits) {
+    for (const file of commit.files) {
+      if (!fileToCommits[file])
+        fileToCommits[file] = [];
+      fileToCommits[file].push(commit.sha);
+    }
+  }
+  for (const [, shas] of Object.entries(fileToCommits)) {
+    if (shas.length > 1) {
+      for (const sha of shas)
+        dependentShas.add(sha);
+    }
+  }
+  const depKeywords = ["refactor", "prep", "prepare", "fix", "setup", "wip", "depends on", "prerequisite"];
+  for (const commit of candidateCommits) {
+    const lower = commit.subject.toLowerCase();
+    if (depKeywords.some((k) => lower.includes(k))) {
+      dependentShas.add(commit.sha);
+    }
+  }
+  return Array.from(dependentShas);
+}
+function recommendMethod(candidateCommits, selectedCommits) {
+  if (selectedCommits.length === 0)
+    return "abort";
+  const ordered = candidateCommits.filter((c) => selectedCommits.includes(c.sha));
+  if (ordered.length === 0)
+    return "abort";
+  const idxs = ordered.map((c) => candidateCommits.findIndex((x) => x.sha === c.sha));
+  let contiguous = true;
+  for (let i = 1;i < idxs.length; i++) {
+    if (idxs[i] !== idxs[i - 1] + 1) {
+      contiguous = false;
+      break;
+    }
+  }
+  if (selectedCommits.length === 1)
+    return "cherry-pick";
+  if (contiguous)
+    return "cherry-pick-range";
+  return "manual-port";
+}
+function generateRecommendedCommands(plan) {
+  const localCmds = [];
+  const remoteCmds = [];
+  localCmds.push(`git checkout -b ${plan.integrationBranch} ${plan.targetBranch}`);
+  if (plan.method === "cherry-pick") {
+    for (const sha of plan.selectedCommits) {
+      localCmds.push(`git cherry-pick ${sha}`);
+    }
+  } else if (plan.method === "cherry-pick-range") {
+    const first = plan.selectedCommits[0];
+    const last = plan.selectedCommits[plan.selectedCommits.length - 1];
+    localCmds.push(`git cherry-pick ${first}^..${last}`);
+  } else if (plan.method === "manual-port") {
+    localCmds.push(`# Manual port required — review each commit and apply changes manually`);
+    for (const sha of plan.selectedCommits) {
+      localCmds.push(`# Review: git show ${sha}`);
+    }
+  } else if (plan.method === "abort") {
+    localCmds.push(`# No commits selected — aborting merge-assist workflow`);
+    return localCmds;
+  }
+  remoteCmds.push(`git push -u origin ${plan.integrationBranch}`);
+  remoteCmds.push(`gh pr create --base ${plan.targetBranch} --head ${plan.integrationBranch} --title "Merge-assist: ${plan.sourceBranch} → ${plan.targetBranch}"`);
+  return [
+    "# --- Local commands (no auth required) ---",
+    ...localCmds,
+    "",
+    "# --- Remote commands (GitHub auth required) ---",
+    ...remoteCmds,
+    "",
+    "# NOTE: The agent will NEVER ask for your GitHub token, password, or SSH key.",
+    "# If you need to push or create a PR, run the remote commands manually or defer this step."
+  ];
+}
+function buildRisks(candidateCommits, selectedCommits, dependentCommits) {
+  const risks = [];
+  const selectedSet = new Set(selectedCommits);
+  const missingDeps = dependentCommits.filter((d) => !selectedSet.has(d));
+  if (missingDeps.length > 0) {
+    risks.push(`Potentially missing dependent commits: ${missingDeps.join(", ")}`);
+  }
+  if (selectedCommits.length > 10) {
+    risks.push("Large number of commits — high chance of conflicts");
+  }
+  if (candidateCommits.some((c) => selectedSet.has(c.sha) && c.files.some((f) => f.includes("package-lock") || f.includes("yarn.lock") || f.includes("bun.lockb")))) {
+    risks.push("Lockfile changes detected — verify dependency compatibility");
+  }
+  if (candidateCommits.some((c) => selectedSet.has(c.sha) && c.files.some((f) => f.includes("migration") || f.includes("schema") || f.includes(".sql")))) {
+    risks.push("Database/schema changes detected — verify migration order");
+  }
+  return risks;
+}
+function makeConfirmation(step, prompt) {
+  return { step, prompt, status: "pending", requestedAt: timestamp2() };
+}
+function updateConfirmation(session, step, approved) {
+  return {
+    ...session,
+    confirmations: session.confirmations.map((c) => c.step === step ? { ...c, status: approved ? "approved" : "rejected", resolvedAt: timestamp2() } : c)
+  };
+}
+function isStepApproved(session, step) {
+  return session.confirmations.some((c) => c.step === step && c.status === "approved");
+}
+var mergeAssistTool = tool13({
+  description: "Human-in-the-loop selective branch integration. Provides structured analysis and confirmation state management for cherry-pick or manual port workflows. Never executes state-changing git commands.",
+  args: {
+    action: tool13.schema.enum(["start", "inspect", "plan", "confirm", "abort", "status", "list"]),
+    targetBranch: tool13.schema.string().optional(),
+    sourceBranch: tool13.schema.string().optional(),
+    featureDescription: tool13.schema.string().optional(),
+    sessionId: tool13.schema.string().optional(),
+    selectedCommits: tool13.schema.array(tool13.schema.string()).optional(),
+    step: tool13.schema.string().optional(),
+    approved: tool13.schema.boolean().optional(),
+    integrationBranch: tool13.schema.string().optional()
+  },
+  async execute(args, context) {
+    const dir = context.directory ?? process.cwd();
+    const state = readState(dir);
+    if (!isGitRepo(dir)) {
+      return JSON.stringify({ error: "Not a git repository" });
+    }
+    const log = (msg) => logWrite(dir, "info", "merge-assist", msg);
+    switch (args.action) {
+      case "start": {
+        if (!args.targetBranch || !args.sourceBranch || !args.featureDescription) {
+          return JSON.stringify({ error: "targetBranch, sourceBranch, and featureDescription are required for start" });
+        }
+        if (!branchExists(dir, args.targetBranch)) {
+          return JSON.stringify({ error: `Target branch '${args.targetBranch}' does not exist` });
+        }
+        if (!branchExists(dir, args.sourceBranch)) {
+          return JSON.stringify({ error: `Source branch '${args.sourceBranch}' does not exist` });
+        }
+        const id = generateId();
+        const now = timestamp2();
+        const session = {
+          id,
+          targetBranch: args.targetBranch,
+          sourceBranch: args.sourceBranch,
+          featureDescription: args.featureDescription,
+          status: "clarifying",
+          candidateCommits: [],
+          selectedCommits: [],
+          dependentCommits: [],
+          confirmations: [
+            makeConfirmation("branch_selection", `Confirm integrating from '${args.sourceBranch}' into '${args.targetBranch}' for: ${args.featureDescription}`)
+          ],
+          createdAt: now,
+          updatedAt: now
+        };
+        const newState = { ...state, sessions: { ...state.sessions, [id]: session } };
+        const writeResult = writeState(dir, newState);
+        if ("error" in writeResult)
+          return JSON.stringify({ error: writeResult.error });
+        log(`Session ${id} started: ${args.sourceBranch} → ${args.targetBranch}`);
+        return JSON.stringify({ success: true, session });
+      }
+      case "inspect": {
+        if (!args.sessionId)
+          return JSON.stringify({ error: "sessionId is required for inspect" });
+        const session = state.sessions[args.sessionId];
+        if (!session)
+          return JSON.stringify({ error: `Session not found: ${args.sessionId}` });
+        const candidates = findCandidateCommits(dir, session.sourceBranch, session.targetBranch);
+        const hasCommitSelection = session.confirmations.some((c) => c.step === "commit_selection");
+        const newSession = {
+          ...session,
+          candidateCommits: candidates,
+          dependentCommits: detectDependencies(candidates),
+          status: "inspecting",
+          confirmations: hasCommitSelection ? session.confirmations : [...session.confirmations, makeConfirmation("commit_selection", `Select commits that represent the feature '${session.featureDescription}' from ${candidates.length} candidate(s)`)],
+          updatedAt: timestamp2()
+        };
+        const newState = { ...state, sessions: { ...state.sessions, [args.sessionId]: newSession } };
+        const writeResult = writeState(dir, newState);
+        if ("error" in writeResult)
+          return JSON.stringify({ error: writeResult.error });
+        log(`Session ${session.id}: inspected ${candidates.length} candidate commits`);
+        return JSON.stringify({ success: true, session: newSession, candidates, dependentCommits: newSession.dependentCommits });
+      }
+      case "plan": {
+        if (!args.sessionId)
+          return JSON.stringify({ error: "sessionId is required for plan" });
+        const session = state.sessions[args.sessionId];
+        if (!session)
+          return JSON.stringify({ error: `Session not found: ${args.sessionId}` });
+        const selected = args.selectedCommits ?? session.selectedCommits;
+        if (!selected || selected.length === 0) {
+          return JSON.stringify({ error: "selectedCommits required for plan" });
+        }
+        const integrationBranch = args.integrationBranch ?? `merge-assist/${session.sourceBranch}-to-${session.targetBranch}`;
+        const method = recommendMethod(session.candidateCommits, selected);
+        const risks = buildRisks(session.candidateCommits, selected, session.dependentCommits);
+        const plan = {
+          targetBranch: session.targetBranch,
+          sourceBranch: session.sourceBranch,
+          integrationBranch,
+          selectedCommits: selected,
+          method,
+          risks,
+          recommendedCommands: [],
+          dryRun: true
+        };
+        const planWithCommands = { ...plan, recommendedCommands: generateRecommendedCommands(plan) };
+        let newConfirmations = session.confirmations;
+        const planSteps = ["integration_branch", "method_selection", "dependency_inclusion"];
+        for (const step of planSteps) {
+          if (!newConfirmations.find((c) => c.step === step)) {
+            let prompt = "";
+            if (step === "integration_branch")
+              prompt = `Use integration branch '${integrationBranch}'?`;
+            if (step === "method_selection")
+              prompt = `Use merge method '${method}'?`;
+            if (step === "dependency_inclusion")
+              prompt = `Include dependent commits ${session.dependentCommits.length > 0 ? `(${session.dependentCommits.join(", ")})` : "(none detected)"}?`;
+            newConfirmations = [...newConfirmations, makeConfirmation(step, prompt)];
+          }
+        }
+        let newStatus = "planning";
+        if (planSteps.every((s) => isStepApproved({ ...session, confirmations: newConfirmations }, s))) {
+          newStatus = "awaiting_confirmation";
+          if (!newConfirmations.find((c) => c.step === "execute_plan")) {
+            newConfirmations = [...newConfirmations, makeConfirmation("execute_plan", "Execute the recommended commands?")];
+          }
+        }
+        const newSession = {
+          ...session,
+          selectedCommits: selected,
+          integrationBranch,
+          mergePlan: planWithCommands,
+          status: newStatus,
+          confirmations: newConfirmations,
+          updatedAt: timestamp2()
+        };
+        const newState = { ...state, sessions: { ...state.sessions, [args.sessionId]: newSession } };
+        const writeResult = writeState(dir, newState);
+        if ("error" in writeResult)
+          return JSON.stringify({ error: writeResult.error });
+        log(`Session ${session.id}: plan created with method ${method}, ${selected.length} commit(s)`);
+        return JSON.stringify({ success: true, session: newSession, plan: planWithCommands });
+      }
+      case "confirm": {
+        if (!args.sessionId)
+          return JSON.stringify({ error: "sessionId is required for confirm" });
+        if (!args.step)
+          return JSON.stringify({ error: "step is required for confirm" });
+        if (args.approved === undefined)
+          return JSON.stringify({ error: "approved boolean is required for confirm" });
+        let session = state.sessions[args.sessionId];
+        if (!session)
+          return JSON.stringify({ error: `Session not found: ${args.sessionId}` });
+        session = updateConfirmation(session, args.step, args.approved);
+        log(`Session ${session.id}: step '${args.step}' ${args.approved ? "approved" : "rejected"}`);
+        let newStatus = session.status;
+        let newConfirmations = session.confirmations;
+        if (args.approved) {
+          if (args.step === "branch_selection" && session.status === "clarifying") {
+            newStatus = "inspecting";
+          } else if (args.step === "commit_selection" && session.status === "inspecting") {
+            newStatus = "planning";
+          } else if (["integration_branch", "method_selection", "dependency_inclusion"].includes(args.step) && session.status === "planning") {
+            const planSteps = ["integration_branch", "method_selection", "dependency_inclusion"];
+            if (planSteps.every((s) => isStepApproved(session, s))) {
+              newStatus = "awaiting_confirmation";
+              if (!newConfirmations.find((c) => c.step === "execute_plan")) {
+                newConfirmations = [...newConfirmations, makeConfirmation("execute_plan", "Execute the recommended commands?")];
+              }
+            }
+          } else if (args.step === "execute_plan" && session.status === "awaiting_confirmation") {
+            newStatus = "executing";
+            if (!newConfirmations.find((c) => c.step === "push_pr")) {
+              newConfirmations = [...newConfirmations, makeConfirmation("push_pr", "Push the integration branch and open a PR?")];
+            }
+          } else if (args.step === "push_pr" && session.status === "executing") {
+            newStatus = "completed";
+          }
+        }
+        const newSession = { ...session, status: newStatus, confirmations: newConfirmations, updatedAt: timestamp2() };
+        const newState = { ...state, sessions: { ...state.sessions, [args.sessionId]: newSession } };
+        const writeResult = writeState(dir, newState);
+        if ("error" in writeResult)
+          return JSON.stringify({ error: writeResult.error });
+        return JSON.stringify({ success: true, session: newSession, step: args.step, approved: args.approved });
+      }
+      case "abort": {
+        if (!args.sessionId)
+          return JSON.stringify({ error: "sessionId is required for abort" });
+        const session = state.sessions[args.sessionId];
+        if (!session)
+          return JSON.stringify({ error: `Session not found: ${args.sessionId}` });
+        const newSession = { ...session, status: "aborted", updatedAt: timestamp2() };
+        const newState = { ...state, sessions: { ...state.sessions, [args.sessionId]: newSession } };
+        const writeResult = writeState(dir, newState);
+        if ("error" in writeResult)
+          return JSON.stringify({ error: writeResult.error });
+        log(`Session ${session.id}: aborted`);
+        return JSON.stringify({ success: true, session: newSession, message: "Session aborted" });
+      }
+      case "status": {
+        if (!args.sessionId)
+          return JSON.stringify({ error: "sessionId is required for status" });
+        const session = state.sessions[args.sessionId];
+        if (!session)
+          return JSON.stringify({ error: `Session not found: ${args.sessionId}` });
+        return JSON.stringify({ success: true, session });
+      }
+      case "list": {
+        const sessions = Object.values(state.sessions);
+        return JSON.stringify({ success: true, count: sessions.length, sessions });
+      }
+      default: {
+        return JSON.stringify({ error: `Unknown action: ${args.action}` });
+      }
+    }
+  }
+});
+
+// src/hooks/guard-rails.ts
+import { existsSync as existsSync18, readFileSync as readFileSync17 } from "fs";
+import { join as join18 } from "path";
 
 // src/lib/task-routing.ts
 var UI_HEAVY_KEYWORDS = [
@@ -2042,23 +2517,23 @@ function isUiHeavyTask(input) {
 }
 
 // src/config/loader.ts
-import { existsSync as existsSync15, readFileSync as readFileSync15 } from "fs";
-import { join as join15 } from "path";
+import { existsSync as existsSync17, readFileSync as readFileSync16 } from "fs";
+import { join as join17 } from "path";
 import { homedir as homedir2 } from "os";
 var CONFIG_FILENAME = "flowdeck.json";
 function getGlobalConfigDir() {
-  return process.env.OPENCODE_CONFIG_DIR || (process.env.XDG_CONFIG_HOME ? join15(process.env.XDG_CONFIG_HOME, "opencode") : join15(homedir2(), ".config", "opencode"));
+  return process.env.OPENCODE_CONFIG_DIR || (process.env.XDG_CONFIG_HOME ? join17(process.env.XDG_CONFIG_HOME, "opencode") : join17(homedir2(), ".config", "opencode"));
 }
 function loadFlowDeckConfig(directory) {
   const candidates = [];
   if (directory) {
-    candidates.push(join15(directory, ".opencode", CONFIG_FILENAME));
+    candidates.push(join17(directory, ".opencode", CONFIG_FILENAME));
   }
-  candidates.push(join15(getGlobalConfigDir(), CONFIG_FILENAME));
+  candidates.push(join17(getGlobalConfigDir(), CONFIG_FILENAME));
   for (const configPath of candidates) {
-    if (existsSync15(configPath)) {
+    if (existsSync17(configPath)) {
       try {
-        const content = readFileSync15(configPath, "utf-8");
+        const content = readFileSync16(configPath, "utf-8");
         return JSON.parse(content);
       } catch {}
     }
@@ -2085,9 +2560,9 @@ var PLANNING_DIR2 = ".planning";
 var CONFIG_FILE = "config.json";
 var STATE_FILE2 = "STATE.md";
 function resolveExecutionMode(configPath, trustScore, volatility) {
-  if (existsSync16(configPath)) {
+  if (existsSync18(configPath)) {
     try {
-      const config = JSON.parse(readFileSync16(configPath, "utf-8"));
+      const config = JSON.parse(readFileSync17(configPath, "utf-8"));
       if (config.execution_mode === "review-only")
         return "review-only";
       if (config.execution_mode === "guarded")
@@ -2141,22 +2616,22 @@ async function guardRailsHook(ctx, input, _output) {
   if (!ENABLED)
     return;
   const dir = ctx.directory;
-  const planningDirPath = join16(dir, PLANNING_DIR2);
+  const planningDirPath = join18(dir, PLANNING_DIR2);
   const codebaseDirectory = codebaseDir(dir);
-  const configPath = join16(planningDirPath, CONFIG_FILE);
-  const statePath2 = join16(planningDirPath, STATE_FILE2);
+  const configPath = join18(planningDirPath, CONFIG_FILE);
+  const statePath3 = join18(planningDirPath, STATE_FILE2);
   const workspaceRoot = findWorkspaceRoot(dir);
   if (workspaceRoot && dir !== workspaceRoot) {
     const config = getWorkspaceConfig(dir);
-    if (config && config.workspace_mode === "shared" && !existsSync16(planningDirPath)) {
+    if (config && config.workspace_mode === "shared" && !existsSync18(planningDirPath)) {
       const msg = `No .planning/ in this sub-repo. Switch to workspace root: cd ${workspaceRoot}`;
       throw new Error(`[flowdeck] BLOCK: ${msg}`);
     }
   }
   if (input.tool === "write" || input.tool === "edit") {
-    if (!existsSync16(planningDirPath))
+    if (!existsSync18(planningDirPath))
       return;
-    if (!existsSync16(codebaseDirectory)) {
+    if (!existsSync18(codebaseDirectory)) {
       throw new Error(`[flowdeck] WARNING: .codebase/ not found. Run /fd-map-codebase to map the codebase.`);
     }
     const execMode = resolveExecutionMode(configPath, null);
@@ -2170,7 +2645,7 @@ async function guardRailsHook(ctx, input, _output) {
     if (designGateMessage) {
       throw new Error(designGateMessage);
     }
-    const effectiveSeverity = getEffectiveSeverity(configPath, statePath2);
+    const effectiveSeverity = getEffectiveSeverity(configPath, statePath3);
     if (effectiveSeverity === null)
       return;
     if (effectiveSeverity === "warn") {
@@ -2184,7 +2659,7 @@ async function guardRailsHook(ctx, input, _output) {
     const cmd = _output?.args?.command || "";
     for (const pattern of BUILD_DEPLOY_PATTERNS) {
       if (cmd.includes(pattern)) {
-        if (!getPlanConfirmed(statePath2)) {
+        if (!getPlanConfirmed(statePath3)) {
           throw new Error(`[flowdeck] WARNING: Build/deploy command detected but plan is not confirmed. Run /fd-plan first.`);
         }
         break;
@@ -2212,15 +2687,15 @@ function getDesignGateMessage(dir) {
 }
 function planSuggestsUiHeavy(dir, phase) {
   const planPath = phasePlanPath(dir, phase);
-  if (!existsSync16(planPath))
+  if (!existsSync18(planPath))
     return false;
-  const planContent = readFileSync16(planPath, "utf-8");
+  const planContent = readFileSync17(planPath, "utf-8");
   return isUiHeavyTask(planContent);
 }
-function effectiveSeverity(configPath, statePath2) {
-  if (existsSync16(configPath)) {
+function effectiveSeverity(configPath, statePath3) {
+  if (existsSync18(configPath)) {
     try {
-      const configContent = readFileSync16(configPath, "utf-8");
+      const configContent = readFileSync17(configPath, "utf-8");
       const config = JSON.parse(configContent);
       if (config.guard_enforcement === "warn")
         return "warn";
@@ -2230,16 +2705,16 @@ function effectiveSeverity(configPath, statePath2) {
         return null;
     } catch {}
   }
-  return getPlanConfirmed(statePath2) ? "block" : "warn";
+  return getPlanConfirmed(statePath3) ? "block" : "warn";
 }
-function getEffectiveSeverity(configPath, statePath2) {
-  return effectiveSeverity(configPath, statePath2);
+function getEffectiveSeverity(configPath, statePath3) {
+  return effectiveSeverity(configPath, statePath3);
 }
-function getPlanConfirmed(statePath2) {
-  if (!existsSync16(statePath2))
+function getPlanConfirmed(statePath3) {
+  if (!existsSync18(statePath3))
     return false;
   try {
-    const content = readFileSync16(statePath2, "utf-8");
+    const content = readFileSync17(statePath3, "utf-8");
     const match = content.match(/plan_confirmed:\s*(true|false)/i);
     return match ? match[1].toLowerCase() === "true" : false;
   } catch {
@@ -2247,32 +2722,32 @@ function getPlanConfirmed(statePath2) {
   }
 }
 function getWarningMessage(planningDir2) {
-  if (!existsSync16(join16(planningDir2, STATE_FILE2))) {
+  if (!existsSync18(join18(planningDir2, STATE_FILE2))) {
     return "No STATE.md found. Run /fd-map-codebase then /fd-new-feature to start a feature.";
   }
   return "Plan not confirmed. Run /fd-plan and confirm to enable execution.";
 }
 function getBlockMessage(planningDir2) {
-  if (!existsSync16(join16(planningDir2, STATE_FILE2))) {
+  if (!existsSync18(join18(planningDir2, STATE_FILE2))) {
     return "No STATE.md found. Run /fd-map-codebase then /fd-new-feature to start a feature.";
   }
   return "Plan not confirmed. Run /fd-plan and confirm to enable execution.";
 }
 
 // src/hooks/tool-guard.ts
-import { existsSync as existsSync17, readFileSync as readFileSync17 } from "fs";
-import { join as join17 } from "path";
+import { existsSync as existsSync19, readFileSync as readFileSync18 } from "fs";
+import { join as join19 } from "path";
 var IS_ENABLED = () => process.env.FLOWDECK_TOOL_GUARD_ENABLED === "on";
 var BLOCKED_PATTERNS = {
   read: [".env", ".pem", ".key", ".secret"],
   write: ["node_modules"],
   bash: ["rm -rf"]
 };
-function isBlocked(tool13, args) {
-  const patterns = BLOCKED_PATTERNS[tool13];
+function isBlocked(tool14, args) {
+  const patterns = BLOCKED_PATTERNS[tool14];
   if (!patterns)
     return null;
-  if (tool13 === "bash") {
+  if (tool14 === "bash") {
     const cmd = args.command;
     if (!cmd)
       return null;
@@ -2283,7 +2758,7 @@ function isBlocked(tool13, args) {
     }
     return null;
   }
-  if (tool13 === "read") {
+  if (tool14 === "read") {
     const filePath = args.filePath;
     if (!filePath)
       return null;
@@ -2294,7 +2769,7 @@ function isBlocked(tool13, args) {
     }
     return null;
   }
-  if (tool13 === "write") {
+  if (tool14 === "write") {
     const filePath = args.filePath;
     if (!filePath)
       return null;
@@ -2308,11 +2783,11 @@ function isBlocked(tool13, args) {
   return null;
 }
 function checkArchConstraint(directory, filePath) {
-  const constraintsPath = join17(codebaseDir(directory), "CONSTRAINTS.md");
-  if (!existsSync17(constraintsPath))
+  const constraintsPath = join19(codebaseDir(directory), "CONSTRAINTS.md");
+  if (!existsSync19(constraintsPath))
     return null;
   try {
-    const content = readFileSync17(constraintsPath, "utf-8");
+    const content = readFileSync18(constraintsPath, "utf-8");
     const match = content.match(/## Forbidden Paths\n([\s\S]*?)(?:\n##|$)/);
     if (!match)
       return null;
@@ -2353,9 +2828,9 @@ function isUiDesignApprovalRequired(directory) {
     return !(state.design_stage === "handoff_complete" && state.design_approved);
   }
   const planPath = phasePlanPath(directory, state.phase || 1);
-  if (!existsSync17(planPath))
+  if (!existsSync19(planPath))
     return false;
-  const planContent = readFileSync17(planPath, "utf-8");
+  const planContent = readFileSync18(planPath, "utf-8");
   if (!isUiHeavyTask(planContent))
     return false;
   return !(state.design_stage === "handoff_complete" && state.design_approved);
@@ -2384,18 +2859,18 @@ async function toolGuardHook(ctx, input, output) {
 }
 
 // src/hooks/session-start.ts
-import { existsSync as existsSync18, readFileSync as readFileSync18 } from "fs";
+import { existsSync as existsSync20, readFileSync as readFileSync19 } from "fs";
 async function sessionStartHook(ctx) {
   const planningDir2 = ctx.directory + "/.planning";
   const codebaseDirectory = codebaseDir(ctx.directory);
   const workspaceRoot = findWorkspaceRoot(ctx.directory);
   const config = workspaceRoot ? getWorkspaceConfig(ctx.directory) : null;
-  if (!existsSync18(planningDir2)) {
+  if (!existsSync20(planningDir2)) {
     return {
       flowdeck_phase: null,
       flowdeck_status: "no_plan",
       flowdeck_warning: "Run /fd-map-codebase to index the codebase, then /fd-new-feature to start a feature.",
-      flowdeck_has_codebase: existsSync18(codebaseDirectory),
+      flowdeck_has_codebase: existsSync20(codebaseDirectory),
       ...workspaceRoot && config?.sub_repos ? {
         flowdeck_workspace_root: workspaceRoot,
         flowdeck_sub_repos: config.sub_repos,
@@ -2406,7 +2881,7 @@ async function sessionStartHook(ctx) {
   }
   try {
     const stateFilePath = statePath(ctx.directory);
-    const content = readFileSync18(stateFilePath, "utf-8");
+    const content = readFileSync19(stateFilePath, "utf-8");
     const state = parseState(content);
     const currentPhase = state["current_phase"] || {};
     const result = {
@@ -2414,7 +2889,7 @@ async function sessionStartHook(ctx) {
       flowdeck_status: currentPhase["status"] ?? null,
       flowdeck_steps_pending: currentPhase["steps_pending"] ?? null,
       flowdeck_last_action: currentPhase["last_action"] ?? null,
-      flowdeck_has_codebase: existsSync18(codebaseDirectory)
+      flowdeck_has_codebase: existsSync20(codebaseDirectory)
     };
     if (workspaceRoot && config?.sub_repos && config.sub_repos.length > 0) {
       result.flowdeck_workspace_root = workspaceRoot;
@@ -2428,7 +2903,7 @@ async function sessionStartHook(ctx) {
       flowdeck_phase: null,
       flowdeck_status: "error",
       flowdeck_warning: "State file unreadable. Continuing without flowdeck context.",
-      flowdeck_has_codebase: existsSync18(codebaseDirectory)
+      flowdeck_has_codebase: existsSync20(codebaseDirectory)
     };
     if (workspaceRoot && config?.sub_repos && config.sub_repos.length > 0) {
       result.flowdeck_workspace_root = workspaceRoot;
@@ -2560,13 +3035,13 @@ class NotificationController {
     return this.lastNotifiedKey;
   }
 }
-function notifyPermissionNeeded(tool13) {
-  notify("FlowDeck Permission Required", `Agent needs approval to use tool: ${tool13}`, "critical");
+function notifyPermissionNeeded(tool14) {
+  notify("FlowDeck Permission Required", `Agent needs approval to use tool: ${tool14}`, "critical");
 }
 
 // src/hooks/patch-trust.ts
-import { existsSync as existsSync19, readFileSync as readFileSync19 } from "fs";
-import { join as join18 } from "path";
+import { existsSync as existsSync21, readFileSync as readFileSync20 } from "fs";
+import { join as join20 } from "path";
 var HIGH_RISK_KEYWORDS = [
   "password",
   "secret",
@@ -2588,11 +3063,11 @@ var HIGH_RISK_KEYWORDS = [
   "privilege"
 ];
 function loadFailedPaths(directory) {
-  const p = join18(codebaseDir(directory), "FAILURES.json");
-  if (!existsSync19(p))
+  const p = join20(codebaseDir(directory), "FAILURES.json");
+  if (!existsSync21(p))
     return [];
   try {
-    const data = JSON.parse(readFileSync19(p, "utf-8"));
+    const data = JSON.parse(readFileSync20(p, "utf-8"));
     return (data.entries ?? []).flatMap((e) => e.affected_paths ?? []);
   } catch {
     return [];
@@ -2645,8 +3120,8 @@ async function patchTrustHook(ctx, input, output) {
 }
 
 // src/hooks/decision-trace-hook.ts
-import { existsSync as existsSync20, mkdirSync as mkdirSync9, appendFileSync as appendFileSync3 } from "fs";
-import { join as join19 } from "path";
+import { existsSync as existsSync22, mkdirSync as mkdirSync11, appendFileSync as appendFileSync4 } from "fs";
+import { join as join21 } from "path";
 async function decisionTraceHook(ctx, input, output) {
   if (input.tool !== "write" && input.tool !== "edit")
     return;
@@ -2655,8 +3130,8 @@ async function decisionTraceHook(ctx, input, output) {
     return;
   const base = codebaseDir(ctx.directory);
   try {
-    if (!existsSync20(base))
-      mkdirSync9(base, { recursive: true });
+    if (!existsSync22(base))
+      mkdirSync11(base, { recursive: true });
     const entry = {
       timestamp: new Date().toISOString(),
       file_path: filePath,
@@ -2668,14 +3143,14 @@ async function decisionTraceHook(ctx, input, output) {
       risk_level: "unknown",
       auto_recorded: true
     };
-    appendFileSync3(join19(base, "DECISIONS.jsonl"), JSON.stringify(entry) + `
+    appendFileSync4(join21(base, "DECISIONS.jsonl"), JSON.stringify(entry) + `
 `, "utf-8");
   } catch {}
 }
 
 // src/services/approval-manager.ts
-import { existsSync as existsSync21, readFileSync as readFileSync20, writeFileSync as writeFileSync11, mkdirSync as mkdirSync10 } from "fs";
-import { join as join20 } from "path";
+import { existsSync as existsSync23, readFileSync as readFileSync21, writeFileSync as writeFileSync12, mkdirSync as mkdirSync12 } from "fs";
+import { join as join22 } from "path";
 var APPROVAL_TTL_MS = 30 * 60 * 1000;
 var SENSITIVE_PATTERNS = [
   /auth/i,
@@ -2712,14 +3187,14 @@ function isSensitivePath(filePath) {
   return SENSITIVE_PATTERNS.some((p) => p.test(filePath));
 }
 function approvalsPath(dir) {
-  return join20(codebaseDir(dir), "APPROVALS.json");
+  return join22(codebaseDir(dir), "APPROVALS.json");
 }
 function loadStore(dir) {
   const p = approvalsPath(dir);
-  if (!existsSync21(p))
+  if (!existsSync23(p))
     return { requests: [] };
   try {
-    return JSON.parse(readFileSync20(p, "utf-8"));
+    return JSON.parse(readFileSync21(p, "utf-8"));
   } catch {
     return { requests: [] };
   }
@@ -2737,8 +3212,8 @@ async function approvalHook(context, toolInput, output) {
   if (!ENABLED2)
     return;
   const dir = context.directory ?? process.cwd();
-  const tool13 = toolInput.name ?? toolInput.tool ?? "";
-  if (!WRITE_TOOLS.has(tool13))
+  const tool14 = toolInput.name ?? toolInput.tool ?? "";
+  if (!WRITE_TOOLS.has(tool14))
     return;
   const args = output.args ?? {};
   const filePath = String(args.path ?? args.file_path ?? args.filename ?? "");
@@ -2755,8 +3230,8 @@ async function approvalHook(context, toolInput, output) {
 }
 
 // src/services/event-logger.ts
-import { existsSync as existsSync22, mkdirSync as mkdirSync11, appendFileSync as appendFileSync4, readFileSync as readFileSync21, writeFileSync as writeFileSync12, renameSync, unlinkSync, statSync } from "fs";
-import { join as join21, resolve as resolve2, sep } from "path";
+import { existsSync as existsSync24, mkdirSync as mkdirSync13, appendFileSync as appendFileSync5, readFileSync as readFileSync22, writeFileSync as writeFileSync13, renameSync, unlinkSync, statSync } from "fs";
+import { join as join23, resolve as resolve2, sep } from "path";
 var SENSITIVE_KEYS = [
   "password",
   "token",
@@ -2775,6 +3250,8 @@ var SENSITIVE_KEYS = [
   "refresh_token"
 ];
 var currentAgent = null;
+var persistenceFailed = false;
+var lastPersistenceError = null;
 function getCurrentAgent() {
   return currentAgent;
 }
@@ -2818,43 +3295,59 @@ function isValidDirectory(directory) {
 }
 function logEvent(directory, event, log) {
   if (process.env.FLOWDECK_EVENT_LOG === "off")
-    return;
-  if (!isValidDirectory(directory))
-    return;
-  const logDir = join21(directory, ".opencode");
-  const logPath = join21(logDir, "flowdeck-events.jsonl");
+    return true;
+  if (!isValidDirectory(directory)) {
+    persistenceFailed = true;
+    lastPersistenceError = "Invalid directory";
+    return false;
+  }
+  const logDir = join23(directory, ".opencode");
+  const logPath = join23(logDir, "flowdeck-events.jsonl");
   try {
-    if (!existsSync22(logDir)) {
-      mkdirSync11(logDir, { recursive: true });
+    if (!existsSync24(logDir)) {
+      mkdirSync13(logDir, { recursive: true });
     }
-    appendFileSync4(logPath, JSON.stringify(event) + `
+    appendFileSync5(logPath, JSON.stringify(event) + `
 `, "utf-8");
-    rotateLogFile(logPath);
+    rotateLogFile(logPath, log);
     if (log) {
       log(formatEventForStderr(event));
     }
-  } catch {}
+    return true;
+  } catch (error) {
+    persistenceFailed = true;
+    lastPersistenceError = error instanceof Error ? error.message : String(error);
+    if (log) {
+      log(`[event-logger] failed to write event: ${lastPersistenceError}`);
+    }
+    return false;
+  }
 }
-function rotateLogFile(logPath) {
+function rotateLogFile(logPath, log) {
   try {
     const stats = statSync(logPath);
     if (stats.size < 5000)
       return;
-    const content = readFileSync21(logPath, "utf-8");
+    const content = readFileSync22(logPath, "utf-8");
     const lines = content.split(`
 `).filter((l) => l.trim());
     if (lines.length > 1000) {
       const backupPath = logPath + ".backup";
       renameSync(logPath, backupPath);
       const keep = lines.slice(-1000);
-      writeFileSync12(logPath, keep.join(`
+      writeFileSync13(logPath, keep.join(`
 `) + `
 `, "utf-8");
       try {
         unlinkSync(backupPath);
       } catch {}
     }
-  } catch {}
+  } catch (error) {
+    if (log) {
+      const message = error instanceof Error ? error.message : String(error);
+      log(`[event-logger] log rotation failed: ${message}`);
+    }
+  }
 }
 function formatEventForStderr(event) {
   const time = event.timestamp.slice(11, 23);
@@ -2935,7 +3428,7 @@ function cleanupStaleToolStartTimes() {
     }
   }
 }
-function createEventLogHooks(appLog) {
+function createEventLogHooks(appLog, onToolAfter) {
   return {
     async before(ctx, toolInput, toolOutput) {
       const toolName = toolInput.tool ?? toolInput.name ?? "unknown";
@@ -2988,7 +3481,10 @@ function createEventLogHooks(appLog) {
         error,
         session_id: sessionId
       };
-      logEvent(ctx.directory, event, appLog);
+      if (onToolAfter) {
+        onToolAfter(toolName, args, toolOutput, sessionId, status);
+      }
+      return logEvent(ctx.directory, event, appLog);
     },
     async session(ctx, event) {
       const type = event?.type ?? "";
@@ -3039,6 +3535,324 @@ function extractAgentFromEvent(props) {
   return "unknown";
 }
 
+// src/services/loop-detector.ts
+import { resolve as resolve3 } from "path";
+var NON_MUTATING_TOOLS = new Set([
+  "read",
+  "view",
+  "bash",
+  "shell",
+  "grep",
+  "glob",
+  "search"
+]);
+var TRANSIENT_ERROR_KEYWORDS = [
+  "timeout",
+  "econnrefused",
+  "econnreset",
+  "etimedout",
+  "locked",
+  "busy",
+  "temporarily unavailable"
+];
+var DEFAULT_CONFIG = {
+  enabled: true,
+  maxRepeats: 2,
+  similarityThreshold: 0.9,
+  historySize: 20
+};
+function djb2Hash(input) {
+  let hash = 5381;
+  for (let i = 0;i < input.length; i++) {
+    hash = hash * 33 ^ input.charCodeAt(i);
+  }
+  return (hash >>> 0).toString(16);
+}
+function hashOutput(output) {
+  if (typeof output === "string") {
+    const truncated2 = output.length > 10240 ? output.slice(0, 10240) : output;
+    return djb2Hash(truncated2);
+  }
+  let serialized;
+  try {
+    serialized = JSON.stringify(output);
+  } catch {
+    serialized = String(output);
+  }
+  const truncated = serialized.length > 10240 ? serialized.slice(0, 10240) : serialized;
+  return djb2Hash(truncated);
+}
+function lineSimilarity(a, b) {
+  const linesA = new Set(a.split(`
+`));
+  const linesB = new Set(b.split(`
+`));
+  const intersection = new Set([...linesA].filter((x) => linesB.has(x)));
+  const union = new Set([...linesA, ...linesB]);
+  return union.size === 0 ? 1 : intersection.size / union.size;
+}
+function getOutputPreview(output) {
+  if (output === null || output === undefined)
+    return "";
+  if (typeof output === "string")
+    return output.slice(0, 200);
+  try {
+    return JSON.stringify(output).slice(0, 200);
+  } catch {
+    return String(output).slice(0, 200);
+  }
+}
+function stableStringify(obj) {
+  if (obj === null || typeof obj !== "object")
+    return JSON.stringify(obj);
+  if (Array.isArray(obj)) {
+    return `[${obj.map(stableStringify).join(",")}]`;
+  }
+  const record = obj;
+  const keys = Object.keys(record).sort();
+  const pairs = keys.map((k) => `${JSON.stringify(k)}:${stableStringify(record[k])}`);
+  return `{${pairs.join(",")}}`;
+}
+function resolveEnvVars(command) {
+  return command.replace(/\$RTK_BIN\b/gi, "rtk").replace(/\$HOME\b/gi, "~").replace(/\$USER\b/gi, "user");
+}
+function collapseWhitespace(input) {
+  return input.replace(/\s+/g, " ").trim();
+}
+function normalizeAction(toolName, args) {
+  const tool14 = toolName.toLowerCase();
+  if (tool14 === "bash" || tool14 === "shell") {
+    const command = typeof args.command === "string" ? args.command : "";
+    const normalized = collapseWhitespace(resolveEnvVars(command)).toLowerCase();
+    return `shell:${normalized}`;
+  }
+  if (tool14 === "read" || tool14 === "view") {
+    const filePath = typeof args.filePath === "string" ? args.filePath : "";
+    try {
+      return `${tool14}:${resolve3(filePath || "")}`;
+    } catch {
+      return `${tool14}:${filePath}`;
+    }
+  }
+  if (tool14 === "write" || tool14 === "edit") {
+    const filePath = typeof args.filePath === "string" ? args.filePath : "";
+    try {
+      return `${tool14}:${resolve3(filePath || "")}`;
+    } catch {
+      return `${tool14}:${filePath}`;
+    }
+  }
+  if (tool14 === "grep" || tool14 === "glob" || tool14 === "search") {
+    const pattern = typeof args.pattern === "string" ? args.pattern : "";
+    const path = typeof args.path === "string" ? args.path : "";
+    return `${tool14}:${pattern}:${resolve3(path || ".")}`;
+  }
+  const sorted = stableStringify(args);
+  return `${tool14}:${sorted}`;
+}
+function classifyObservation(toolName, previous, output, status, similarityThreshold) {
+  const outputPreview = getOutputPreview(output);
+  const tool14 = toolName.toLowerCase();
+  if (status === "blocked") {
+    return { observation: "same_result", outputHash: hashOutput(output), outputPreview };
+  }
+  if (status === "error") {
+    const errorMessage = output && typeof output === "object" && "error" in output ? String(output.error) : typeof output === "string" ? output : "";
+    const lower = errorMessage.toLowerCase();
+    const isTransient = TRANSIENT_ERROR_KEYWORDS.some((k) => lower.includes(k));
+    return {
+      observation: isTransient ? "transient_failure" : "same_result",
+      outputHash: djb2Hash(errorMessage),
+      outputPreview: errorMessage.slice(0, 200)
+    };
+  }
+  if (tool14 === "write" || tool14 === "edit") {
+    const contentHash = hashOutput(output);
+    return { observation: "new_information", outputHash: contentHash, outputPreview };
+  }
+  const outputHash = hashOutput(output);
+  if (!previous) {
+    return { observation: "new_information", outputHash, outputPreview };
+  }
+  if (outputHash === previous.outputHash) {
+    return { observation: "same_result", outputHash, outputPreview };
+  }
+  if (NON_MUTATING_TOOLS.has(tool14)) {
+    const similarity = lineSimilarity(outputPreview, previous.outputPreview);
+    if (similarity >= similarityThreshold) {
+      return { observation: "no_progress", outputHash, outputPreview };
+    }
+  }
+  return { observation: "new_information", outputHash, outputPreview };
+}
+function redactForDisplay(toolName, normalizedKey) {
+  const tool14 = toolName.toLowerCase();
+  if (tool14 === "bash" || tool14 === "shell") {
+    const idx2 = normalizedKey.indexOf(":");
+    const cmd = idx2 >= 0 ? normalizedKey.slice(idx2 + 1) : normalizedKey;
+    const preview = cmd.slice(0, 30);
+    const hash = djb2Hash(cmd);
+    return `${tool14}:"${preview}" (hash: ${hash})`;
+  }
+  const idx = normalizedKey.indexOf(":");
+  if (idx >= 0) {
+    const body = normalizedKey.slice(idx + 1);
+    if (body.startsWith("/") || body.startsWith(".") || body.includes("/")) {
+      return `${tool14}:"${body}"`;
+    }
+    const preview = body.slice(0, 30);
+    const hash = djb2Hash(body);
+    return `${tool14}:"${preview}" (hash: ${hash})`;
+  }
+  return `${tool14}:"${normalizedKey}"`;
+}
+
+class LoopDetector {
+  config;
+  appLog;
+  history = new Map;
+  persistenceHealthy = true;
+  persistenceWarningLogged = new Set;
+  constructor(config, appLog) {
+    this.config = { ...DEFAULT_CONFIG, ...config };
+    this.appLog = appLog;
+  }
+  setPersistenceHealthy(healthy) {
+    if (this.persistenceHealthy === healthy)
+      return;
+    this.persistenceHealthy = healthy;
+    if (!healthy && this.appLog) {
+      this.appLog("[loop-guard] Event log persistence failed — loop detection running in-memory only. History will be lost on restart.");
+    }
+  }
+  getHistory(sessionId) {
+    const sessionHistory = this.history.get(sessionId);
+    if (!sessionHistory)
+      return [];
+    return Array.from(sessionHistory.values()).sort((a, b) => a.timestamp - b.timestamp);
+  }
+  clearSession(sessionId) {
+    this.history.delete(sessionId);
+  }
+  checkBefore(toolName, args, sessionId) {
+    if (!this.config.enabled) {
+      return { action: "allow" };
+    }
+    if (!this.persistenceHealthy && !this.persistenceWarningLogged.has(sessionId)) {
+      if (this.persistenceWarningLogged.size >= 1000) {
+        this.persistenceWarningLogged.clear();
+      }
+      this.persistenceWarningLogged.add(sessionId);
+      if (this.appLog) {
+        this.appLog("[loop-guard] Event log persistence failed — loop detection running in-memory only. History will be lost on restart.");
+      }
+    }
+    const normalizedKey = normalizeAction(toolName, args);
+    const record = this.getSessionRecord(sessionId, normalizedKey);
+    if (!record) {
+      return { action: "allow" };
+    }
+    const maxRepeats = this.config.maxRepeats;
+    if (record.consecutiveSameResultCount >= maxRepeats) {
+      const reason = "same_result";
+      const escalationMessage = this.buildEscalationMessage(toolName, normalizedKey, record.status, record.consecutiveSameResultCount, reason);
+      if (this.appLog) {
+        this.appLog(`[loop-guard] blocked repeat of "${redactForDisplay(toolName, normalizedKey)}" — already executed ${record.consecutiveSameResultCount} times with same result`);
+      }
+      return { action: "block", reason, escalationMessage };
+    }
+    if (record.callCount >= 2 && this.isNoProgressMarker(record)) {
+      const reason = "no_progress";
+      const escalationMessage = this.buildEscalationMessage(toolName, normalizedKey, record.status, record.callCount, reason);
+      if (this.appLog) {
+        this.appLog(`[loop-guard] blocked repeat of "${redactForDisplay(toolName, normalizedKey)}" — already executed ${record.callCount} times with no progress`);
+      }
+      return { action: "block", reason, escalationMessage };
+    }
+    return { action: "allow" };
+  }
+  recordAfter(toolName, args, output, sessionId, status = "success") {
+    if (!this.config.enabled)
+      return;
+    const normalizedKey = normalizeAction(toolName, args);
+    const previous = this.getSessionRecord(sessionId, normalizedKey);
+    const { observation, outputHash, outputPreview } = classifyObservation(toolName, previous, output, status, this.config.similarityThreshold);
+    let record;
+    if (!previous) {
+      record = {
+        toolName,
+        normalizedKey,
+        args,
+        outputHash,
+        outputPreview,
+        status,
+        timestamp: Date.now(),
+        callCount: 1,
+        consecutiveSameResultCount: observation === "transient_failure" ? 1 : 0
+      };
+    } else {
+      let nextConsecutive = previous.consecutiveSameResultCount;
+      if (observation === "same_result" || observation === "transient_failure" || observation === "no_progress") {
+        nextConsecutive = previous.consecutiveSameResultCount + 1;
+      } else {
+        nextConsecutive = 0;
+      }
+      record = {
+        toolName,
+        normalizedKey,
+        args,
+        outputHash,
+        outputPreview,
+        status,
+        timestamp: Date.now(),
+        callCount: previous.callCount + 1,
+        consecutiveSameResultCount: nextConsecutive
+      };
+    }
+    if (observation === "transient_failure" && this.appLog) {
+      const transientCount = record.consecutiveSameResultCount;
+      if (transientCount <= 3) {
+        this.appLog(`[loop-guard] transient failure detected for "${toolName}" — allowing retry ${transientCount}/3`);
+      }
+    }
+    this.setSessionRecord(sessionId, normalizedKey, record);
+  }
+  getSessionRecord(sessionId, normalizedKey) {
+    return this.history.get(sessionId)?.get(normalizedKey);
+  }
+  setSessionRecord(sessionId, normalizedKey, record) {
+    let sessionHistory = this.history.get(sessionId);
+    if (!sessionHistory) {
+      sessionHistory = new Map;
+      this.history.set(sessionId, sessionHistory);
+    }
+    sessionHistory.set(normalizedKey, record);
+    if (sessionHistory.size > this.config.historySize) {
+      this.evictOldest(sessionHistory);
+    }
+  }
+  evictOldest(sessionHistory) {
+    let oldestKey;
+    let oldestTime = Infinity;
+    for (const [key, value] of sessionHistory.entries()) {
+      if (value.timestamp < oldestTime) {
+        oldestTime = value.timestamp;
+        oldestKey = key;
+      }
+    }
+    if (oldestKey !== undefined) {
+      sessionHistory.delete(oldestKey);
+    }
+  }
+  isNoProgressMarker(record) {
+    return record.consecutiveSameResultCount >= 1 && record.callCount >= 2;
+  }
+  buildEscalationMessage(toolName, normalizedKey, status, count, _reason) {
+    const normalizedPreview = redactForDisplay(toolName, normalizedKey);
+    return `[FlowDeck Loop Guard] You already ran \`${normalizedPreview}\` and got the same result (status: ${status}, repeats: ${count}). Do NOT repeat it. Choose a different approach, inspect the tool behavior, or ask the human for guidance.`;
+  }
+}
+
 // src/hooks/context-window-monitor.ts
 var CONTEXT_WARNING_THRESHOLD = 0.7;
 var DEFAULT_CONTEXT_LIMIT = Number(process.env.FLOWDECK_CONTEXT_LIMIT) || 200000;
@@ -3090,8 +3904,8 @@ function createContextWindowMonitorHook() {
 }
 
 // src/hooks/shell-env-hook.ts
-import { existsSync as existsSync23, readFileSync as readFileSync22 } from "fs";
-import { join as join22 } from "path";
+import { existsSync as existsSync25, readFileSync as readFileSync23 } from "fs";
+import { join as join24 } from "path";
 import { createRequire } from "module";
 var _version;
 function getVersion() {
@@ -3127,7 +3941,7 @@ var MARKER_TO_LANG = {
 };
 function detectPackageManager(root) {
   for (const [lockfile, pm] of Object.entries(LOCKFILE_TO_PM)) {
-    if (existsSync23(join22(root, lockfile)))
+    if (existsSync25(join24(root, lockfile)))
       return pm;
   }
   return;
@@ -3136,7 +3950,7 @@ function detectLanguages(root) {
   const langs = [];
   const seen = new Set;
   for (const [marker, lang] of Object.entries(MARKER_TO_LANG)) {
-    if (!seen.has(lang) && existsSync23(join22(root, marker))) {
+    if (!seen.has(lang) && existsSync25(join24(root, marker))) {
       langs.push(lang);
       seen.add(lang);
     }
@@ -3144,11 +3958,11 @@ function detectLanguages(root) {
   return langs;
 }
 function readCurrentPhase(root) {
-  const statePath2 = join22(root, ".planning", "STATE.md");
-  if (!existsSync23(statePath2))
+  const statePath3 = join24(root, ".planning", "STATE.md");
+  if (!existsSync25(statePath3))
     return;
   try {
-    const content = readFileSync22(statePath2, "utf-8");
+    const content = readFileSync23(statePath3, "utf-8");
     const match = content.match(/phase:\s*(\S+)/i);
     return match?.[1];
   } catch {
@@ -3273,8 +4087,8 @@ function createSessionIdleHook(client, tracker) {
 }
 
 // src/hooks/compaction-hook.ts
-import { existsSync as existsSync24, readFileSync as readFileSync23 } from "fs";
-import { join as join23 } from "path";
+import { existsSync as existsSync26, readFileSync as readFileSync24 } from "fs";
+import { join as join25 } from "path";
 var STRUCTURED_SUMMARY_PROMPT = `
 When summarizing this session, you MUST include the following sections:
 
@@ -3315,10 +4129,10 @@ For each: agent name, status, description, session_id.
 var _lastInjected = new Map;
 function readPlanningState2(directory) {
   const sp = statePath(directory);
-  if (!existsSync24(sp))
+  if (!existsSync26(sp))
     return null;
   try {
-    const content = readFileSync23(sp, "utf-8");
+    const content = readFileSync24(sp, "utf-8");
     const parsed = parseState(content);
     const version = typeof parsed.summaryVersion === "number" ? parsed.summaryVersion : 0;
     return { content: content.slice(0, 1500), version };
@@ -3347,15 +4161,15 @@ function createCompactionHook(ctx, tracker) {
       sections.push(`_State unchanged since last compaction. summaryVersion=${currentStateVersion}_`);
       sections.push("");
     }
-    const indexPath2 = join23(ctx.directory, ".planning", "CODEBASE_INDEX.md");
-    if (indexChanged && existsSync24(indexPath2)) {
+    const indexPath2 = join25(ctx.directory, ".planning", "CODEBASE_INDEX.md");
+    if (indexChanged && existsSync26(indexPath2)) {
       try {
-        const indexContent = readFileSync23(indexPath2, "utf-8");
+        const indexContent = readFileSync24(indexPath2, "utf-8");
         const indexSummary = "\n## Codebase Index\n```\n" + indexContent.slice(0, 800) + "\n```\n";
         sections.push(indexSummary);
         sections.push("");
       } catch {}
-    } else if (existsSync24(indexPath2)) {
+    } else if (existsSync26(indexPath2)) {
       sections.push(`## Codebase Index (unchanged, v${currentIndexVersion})`);
       sections.push(`_Index unchanged since last compaction. summaryVersion=${currentIndexVersion}_`);
       sections.push("");
@@ -3381,7 +4195,7 @@ function createCompactionHook(ctx, tracker) {
 }
 
 // src/hooks/orchestrator-guard-hook.ts
-var DISABLED = process.env.FLOWDECK_ORCHESTRATOR_GUARD !== "on";
+var DISABLED = process.env.FLOWDECK_ORCHESTRATOR_GUARD === "off";
 var BLOCKED_TOOLS = new Set([
   "write_file",
   "write",
@@ -3398,20 +4212,63 @@ var BLOCKED_TOOLS = new Set([
   "execute",
   "run_command",
   "terminal",
-  "shell"
+  "shell",
+  "python",
+  "run_python",
+  "js",
+  "run_js",
+  "npm",
+  "pnpm",
+  "yarn",
+  "bun",
+  "cargo",
+  "go",
+  "make",
+  "cmake",
+  "docker",
+  "kubectl",
+  "terraform",
+  "pulumi"
 ]);
 var ALWAYS_ALLOWED = new Set([
+  "read",
+  "read_file",
+  "view",
+  "search",
+  "grep",
+  "glob",
   "planning-state",
   "codebase-state",
   "repo-memory",
   "decision-trace",
   "policy-engine",
-  "reflect"
+  "reflect",
+  "codegraph",
+  "codegraph-search",
+  "codegraph-node",
+  "codegraph-explore",
+  "load-rules",
+  "list-rules",
+  "council",
+  "rtk-setup",
+  "hash-edit",
+  "failure-replay"
 ]);
+function normalizeToolName(name) {
+  return name.toLowerCase().replace(/[-_]/g, "");
+}
 function isBlocked2(name) {
-  const norm = name.toLowerCase().replace(/[-_]/g, "");
+  const norm = normalizeToolName(name);
   for (const b of BLOCKED_TOOLS) {
-    if (norm === b.replace(/[-_]/g, "") || norm === b.replace(/_/g, ""))
+    if (norm === normalizeToolName(b))
+      return true;
+  }
+  return false;
+}
+function isAlwaysAllowed(name) {
+  const norm = normalizeToolName(name);
+  for (const a of ALWAYS_ALLOWED) {
+    if (norm === normalizeToolName(a))
       return true;
   }
   return false;
@@ -3419,17 +4276,21 @@ function isBlocked2(name) {
 function blockMessage(toolName) {
   return `[Orchestrator Guard] The orchestrator cannot use \`${toolName}\` directly.
 
-` + `Use built-in read/search tools for lightweight inspection, then route execution with OpenCode's native @agent invocation.
+` + `The orchestrator is a coordinator, not an executor.
+
+` + `Routing options:
+` + `  @default-executor  — simple direct tasks (rename, typo fix, quick edit)
+` + `  @backend-coder     — backend code writing and editing
+` + `  @frontend-coder    — frontend code writing and editing
+` + `  @devops            — CI/CD, deploy, and infrastructure changes
+` + `  @mapper            — codebase mapping
+` + `  @researcher        — focused research and file analysis
+` + `  @tester            — tests, builds, and shell-heavy verification
+` + `  @writer            — documentation writing
 
-` + `Recommended handoffs:
-` + `  @backend-coder   — backend code writing and editing
-` + `  @frontend-coder  — frontend code writing and editing
-` + `  @devops          — CI/CD, deploy, and infrastructure changes
-` + `  @mapper          — codebase mapping
-` + `  @researcher      — focused research and file analysis
-` + `  @tester          — tests, builds, and shell-heavy verification
+` + `Allowed tools for orchestrator: read, search, planning-state, codebase-state, repo-memory, decision-trace, policy-engine, reflect, codegraph, load-rules, council, rtk-setup, hash-edit, failure-replay.
 
-` + `To enable this guard: set FLOWDECK_ORCHESTRATOR_GUARD=on`;
+` + `To disable this guard: set FLOWDECK_ORCHESTRATOR_GUARD=off`;
 }
 
 class OrchestratorGuard {
@@ -3461,12 +4322,21 @@ class OrchestratorGuard {
       return;
     if (sessionId !== this.primarySessionId)
       return;
-    if (ALWAYS_ALLOWED.has(toolName))
+    if (isAlwaysAllowed(toolName))
       return;
     if (isBlocked2(toolName)) {
       throw new Error(blockMessage(toolName));
     }
   }
+  _isBlockedForTest(name) {
+    return isBlocked2(name);
+  }
+  _isAllowedForTest(name) {
+    return isAlwaysAllowed(name);
+  }
+  _setPrimarySessionIdForTest(id) {
+    this.primarySessionId = id;
+  }
 }
 function extractSessionId(event) {
   const props = event.properties;
@@ -3533,10 +4403,23 @@ async function runAutoLearner(client, directory, appLog) {
 }
 
 // src/mcp/index.ts
+import { spawnSync as spawnSync4 } from "child_process";
 function getDisabledMcps() {
   const raw = process.env.FLOWDECK_DISABLE_MCP ?? "";
   return new Set(raw.split(",").map((s) => s.trim()).filter(Boolean));
 }
+function isLauncherAvailable(launcher) {
+  try {
+    const result = spawnSync4(launcher, ["--version"], {
+      encoding: "utf-8",
+      timeout: 5000,
+      stdio: "pipe"
+    });
+    return result.status === 0;
+  } catch {
+    return false;
+  }
+}
 function createFlowDeckMcps() {
   const disabled = getDisabledMcps();
   const mcps = {};
@@ -3583,6 +4466,48 @@ function createFlowDeckMcps() {
       enabled: true
     };
   }
+  if (!disabled.has("memory") && isLauncherAvailable("npx")) {
+    mcps.memory = {
+      type: "local",
+      command: ["npx", "-y", "@modelcontextprotocol/server-memory"],
+      enabled: true
+    };
+  }
+  if (!disabled.has("omega-memory") && isLauncherAvailable("uvx")) {
+    mcps.omegaMemory = {
+      type: "local",
+      command: ["uvx", "omega-memory", "serve"],
+      enabled: true
+    };
+  }
+  if (!disabled.has("sequential-thinking") && isLauncherAvailable("npx")) {
+    mcps.sequentialThinking = {
+      type: "local",
+      command: ["npx", "-y", "@modelcontextprotocol/server-sequential-thinking"],
+      enabled: true
+    };
+  }
+  if (!disabled.has("magic") && isLauncherAvailable("npx")) {
+    mcps.magic = {
+      type: "local",
+      command: ["npx", "-y", "@magicuidesign/mcp@latest"],
+      enabled: true
+    };
+  }
+  if (!disabled.has("playwright") && isLauncherAvailable("npx")) {
+    mcps.playwright = {
+      type: "local",
+      command: ["npx", "-y", "@playwright/mcp", "--browser", "chrome"],
+      enabled: true
+    };
+  }
+  if (!disabled.has("token-optimizer") && isLauncherAvailable("npx")) {
+    mcps.tokenOptimizer = {
+      type: "local",
+      command: ["npx", "-y", "token-optimizer-mcp"],
+      enabled: true
+    };
+  }
   return mcps;
 }
 
@@ -3597,14 +4522,143 @@ ${customAppendPrompt}`;
   return base;
 }
 // src/agents/orchestrator.ts
-var ORCHESTRATOR_PROMPT = `You coordinate multi-agent execution. Read planning state, inspect the codebase with built-in tools when needed, and route specialized work to the right agent using OpenCode's native agent invocation.
+var ORCHESTRATOR_PROMPT = `You are the FlowDeck Orchestrator. You coordinate multi-agent execution. You do NOT execute tasks yourself.
+
+## Core Rule: You Are a Router, Not a Worker
+
+**NEVER** perform the following directly:
+- Write or edit files
+- Run shell commands, bash scripts, or terminal operations
+- Run tests or builds
+- Implement code
+- Do full investigations
+- Run the entire coding workflow yourself
+
+Your ONLY job is to:
+1. **Analyze** the request
+2. **Classify** the task type and estimate complexity/risk/ambiguity
+3. **Choose** the appropriate workflow and execution path
+4. **Route** work to the correct agent or execution path
+5. **Supervise** progress
+6. **Collect** results
+7. **Return** the final coordinated outcome
+
+## Routing-First Protocol
+
+For EVERY user request, you MUST follow this exact sequence BEFORE any execution begins:
+
+### Step 1: Analyze
+- Read STATE.md if it exists
+- Identify current phase and workflow class
+- Understand what the user is asking for
+
+### Step 2: Classify
+Estimate:
+- Simplicity: Is this a rename, typo fix, config update, or simple question?
+- Confidence: How well does the request match known patterns?
+- Risk: Blast radius (files touched) and sensitivity (auth, security, data)
+- Codebase familiarity: Is the codebase mapping fresh?
+- Complexity: Cheap (classify, validate, summarize) vs expensive (architect, refactor)
+
+### Step 3: Choose Workflow
+Select ONE of these workflow classes:
+
+| Workflow Class | Execution Path | When to Select |
+|----------------|---------------|----------------|
+| \`quick\` | Route to @default-executor with \`direct-stock-tools\` mode | Simple, low-risk tasks (< 5 files, no ambiguity) |
+| \`standard\` | Plan with @planner → Execute with specialists → Verify with @reviewer | Normal implementation tasks |
+| \`explore\` | Discuss with @discusser → Plan with @planner → Execute with specialists | Ambiguous or unfamiliar tasks |
+| \`ui-heavy\` | Discuss with @discusser → Design with @design → Plan with @planner → Execute with specialists | UI/UX-heavy tasks |
+| \`bugfix\` | Discuss with @discusser → Fix with @debug-specialist / @backend-coder → Verify with @tester | Bug fixes |
+| \`docs-only\` | Route to @default-executor with \`inspect-only\` or \`simple-edit\` mode, or @writer for large docs | Documentation-only changes |
+| \`verify-heavy\` | Plan with @planner (enhanced checks) → Execute with specialists → Verify with @reviewer + @security-auditor | High blast radius or sensitive paths |
+
+### Step 4: Log the Decision
+Before routing, you MUST emit a routing decision in this exact format:
 
-## Operating Model
+\`\`\`
+## Routing Decision
+
+**Request:** <brief summary of user request>
+**Classification:** <task type> | Confidence: <0.0-1.0>
+**Workflow Selected:** <workflow class>
+**Reason:** <why this workflow was chosen>
+**Execution Path:** <which agent(s) will execute>
+**Estimated Blast Radius:** <number of files or "unknown">
+\`\`\`
 
-- Start by reading STATE.md and the active PLAN.md.
-- Use built-in read/search tools directly for lightweight inspection and progress tracking.
-- Use native agent routing for implementation, testing, deep research, reviews, and other specialist work.
-- Do not rely on the removed FlowDeck-specific delegation tools.
+### Step 5: Route and Supervise
+- Invoke the selected agent(s) using OpenCode's native @agent invocation
+- Provide clear, focused context
+- Wait for completion
+- Collect results
+- If escalation is needed, log the escalation and re-route
+
+## What You MAY Do Directly
+
+You may ONLY use these tools directly:
+- **read** — Read files for lightweight inspection
+- **search/grep** — Search codebase for patterns
+- **planning-state** — Read/update planning state
+- **codebase-state** — Read codebase documentation
+- **repo-memory** — Query architecture graph
+- **decision-trace** — Record decisions
+- **policy-engine** — Check policies
+- **reflect** — Gather session artifacts
+
+You may NEVER use:
+- write, write_file, create, create_file
+- edit, edit_file, patch, apply_patch, str_replace_editor, str_replace
+- bash, run_bash, execute, run_command, terminal, shell
+- Any tool that modifies the filesystem or executes commands
+
+## Execution Paths After Routing
+
+### Direct Execution Path (via @default-executor)
+When workflow class is \`quick\` or \`docs-only\` (simple):
+- Route to @default-executor with an explicit mode:
+  - \`direct-stock-tools\` — for simple file changes
+  - \`quick-answer\` — for questions
+  - \`inspect-only\` — for analysis/reporting
+  - \`simple-edit\` — for surgical changes
+- The @default-executor is the worker; you are the coordinator
+
+### Specialist Execution Path
+When workflow class is \`standard\`, \`explore\`, \`ui-heavy\`, \`bugfix\`, or \`verify-heavy\`:
+- Route implementation to role-specific specialists:
+  - @backend-coder — server, API, business logic, database
+  - @frontend-coder — UI components, client state, styling
+  - @devops — CI/CD, deployment, infrastructure
+  - @tester — tests, builds, verification
+  - @researcher — API docs, library research
+  - @reviewer — code quality review
+  - @security-auditor — security review
+  - @debug-specialist — root cause analysis
+
+### Parallel Execution Patterns
+
+Wave 1 (parallel):
+  @researcher       — research the library API
+  @backend-coder    — implement the model and types
+  @tester           — write test cases
+
+Wave 2 (after Wave 1):
+  @backend-coder    — implement service using Wave 1 research
+  @reviewer         — review Wave 1 implementation
+
+## Adaptive Routing and Escalation
+
+If you discover during supervision that the initial workflow class is insufficient:
+1. Log the escalation with reason
+2. Select the richer workflow class
+3. Re-route the remaining work to appropriate agents
+4. You STILL do not execute the work yourself
+
+Escalation paths:
+- quick → standard: when blast radius exceeds 3 files
+- standard → verify-heavy: when sensitive paths are touched
+- standard → ui-heavy: when design requirements emerge
+- explore → standard: when confidence improves after discussion
 
 ## Startup Behavior
 
@@ -3620,18 +4674,14 @@ If STATE.md does not exist, tell the user: No STATE.md found. Run /fd-map-codeba
 Read STATE.md to determine the current phase and workflow class.
 
 The orchestrator may run in any phase, but should respect the workflow class:
-- For \`quick\` workflows: run directly in execute phase, skip discuss/plan.
+- For \`quick\` workflows: route to @default-executor, skip discuss/plan.
 - For \`standard\` workflows: plan → execute → verify.
 - For \`explore\` workflows: discuss → plan → execute → verify.
 - For \`ui-heavy\` workflows: discuss → design → plan → execute → verify.
 - For \`bugfix\` workflows: discuss → fix-bug → verify.
-- For \`docs-only\` workflows: write-docs → verify.
+- For \`docs-only\` workflows: route to @default-executor or @writer.
 - For \`verify-heavy\` workflows: plan → execute → verify (with enhanced checks).
 
-If the project is in a different phase than expected:
-- Suggest the correct next command but allow override for adaptive workflows.
-- Log any phase skips with reasons.
-
 ## State-First Read Strategy
 
 Before invoking an agent that needs codebase context:
@@ -3649,60 +4699,6 @@ For each incomplete step in PLAN.md:
 4. Wait for completion, then update and re-read STATE.md.
 5. Move to the next incomplete step.
 
-## Implementation Routing
-
-When a plan step requires implementation, route to a role-specific agent:
-- Use @backend-coder for server, API, business logic, database, and non-UI application code.
-- Use @frontend-coder for UI components, client state, styling, and interaction behavior.
-- Use @devops for CI/CD workflows, deployment, infrastructure, runtime config, and operations scripts.
-- Split mixed-domain steps into smaller specialist handoffs when that reduces risk.
-
-## Agent Team
-
-- @design: discovery, UX planning, wireframes, visual system, implementation handoff, design fidelity review
-- @backend-coder: backend code implementation
-- @frontend-coder: frontend code implementation
-- @devops: CI/CD and infrastructure implementation
-- @researcher: API docs and library usage
-- @tester: writing and running tests
-- @reviewer: code quality review
-- @writer: documentation
-- @mapper: codebase mapping to .codebase/
-- @architect: system design and ADRs
-- @security-auditor: security review
-- @code-explorer: reading unfamiliar code
-- @debug-specialist: root cause analysis
-- @build-error-resolver: build and compile failures
-- @doc-updater: updating existing docs
-- @task-splitter: decomposing complex tasks
-- @discusser: requirements extraction
-- @plan-checker: plan quality review
-- @planner: feature planning
-- @performance-optimizer: performance analysis
-- @refactor-guide: safe refactoring
-
-## Adaptive Workflow Routing
-
-The orchestrator reads the workflow class from STATE.md and adapts its behavior:
-
-| Workflow Class | Stages | When Used |
-|----------------|--------|-----------|
-| \`quick\` | execute → verify | Simple, low-risk tasks (< 5 files, no ambiguity) |
-| \`standard\` | plan → execute → verify | Normal implementation tasks |
-| \`explore\` | discuss → plan → execute → verify | Ambiguous or unfamiliar tasks |
-| \`ui-heavy\` | discuss → design → plan → execute → verify | UI/UX-heavy tasks |
-| \`bugfix\` | discuss → fix-bug → verify | Bug fixes |
-| \`docs-only\` | write-docs → verify | Documentation-only changes |
-| \`verify-heavy\` | plan → execute → verify | High blast radius or sensitive paths |
-
-- discuss: requirements extraction with @discusser (only for explore/bugfix/ui-heavy)
-- plan: plan creation with @planner, review with @plan-checker (skip for quick/docs-only)
-- design: UX structure with @design (only for ui-heavy)
-- execute: implementation with appropriate specialists
-- verify: review with @reviewer and @security-auditor (always run for edited code)
-
-The workflow class is chosen by scoring task complexity, confidence, risk, and codebase familiarity. Prefer the lightest workflow that is sufficient. Escalate to a richer workflow only when evidence shows the current path is insufficient.
-
 ## Tracking
 
 After each step completes:
@@ -3730,6 +4726,11 @@ When a task required unusual human guidance, a novel solution strategy, or expos
 
 Do NOT create a skill for routine tasks. Only capture genuinely novel or reusable patterns.`;
 var AGENT_DESCRIPTIONS = {
+  "default-executor": `@default-executor
+- Role: Default execution worker for simple, direct tasks
+- Permissions: Read/write files, shell execution
+- Best for: Quick answers, simple edits, inspect-only analysis, direct stock-tool usage
+- Use when: Workflow class is \`quick\` or \`docs-only\`, or a single focused task needs direct execution`,
   design: `@design
 - Role: Runs design-first workflow for user-facing tasks
 - Permissions: Read/write files
@@ -3858,8 +4859,9 @@ ${enabledAgents}
 - Review available agents before acting
 - Reference paths and line numbers instead of pasting full files
 - Provide context summaries, then let specialists inspect what they need
-- Use direct built-in tools yourself for lightweight reading and status tracking
-- Use native agent routing when specialist work or deeper execution is the better fit
+- Use direct built-in tools ONLY for lightweight reading and status tracking
+- NEVER use write/edit/bash tools yourself — always route execution to agents
+- Log every routing decision before handing off work
 
 </Delegation>`;
 }
@@ -3868,7 +4870,7 @@ function createOrchestratorAgent(model, customPrompt, customAppendPrompt, disabl
   const prompt = resolvePrompt(basePrompt, customPrompt, customAppendPrompt);
   const definition = {
     name: "orchestrator",
-    description: "AI coding orchestrator that coordinates specialist agents and built-in tools for execution",
+    description: "AI coding orchestrator that coordinates specialist agents. Routes all work to appropriate agents and workflows. Does not execute tasks directly.",
     config: {
       temperature: 0.1,
       prompt
@@ -4598,6 +5600,19 @@ var RESEARCHER_PROMPT = `You find accurate, cited information. You do not guess.
 
 Never cite StackOverflow as a primary source. Always verify against official docs.
 
+## MCP Tool Guidance
+
+Use the following MCP tools when relevant to the research task:
+
+- **context7** — library documentation lookup (always try first for API/docs questions)
+- **sequential-thinking** — stepwise investigation and planning for complex research tasks
+- **memory / omega-memory** — retrieve prior context from previous research sessions when relevant
+- **magic** — UI/design system research (component libraries, design tokens, theming)
+- **playwright** — verify browser behavior, test interactive examples, or research runtime DOM/API behavior
+- **token-optimizer** — compress or reduce large context before presenting findings
+
+Maintain Context7-first priority. Use other MCPs to supplement, not replace, authoritative docs.
+
 ## Source Citation
 
 Every fact must include its source:
@@ -6553,9 +7568,71 @@ function createSupervisorAgent(model, customPrompt, customAppendPrompt) {
   return definition;
 }
 
+// src/agents/default-executor.ts
+var DEFAULT_EXECUTOR_PROMPT = `You are the Default Execution Agent — the worker that handles simple, direct tasks when the orchestrator has explicitly routed work to you through a chosen direct workflow.
+
+## Your Role
+
+You execute. You do NOT route, plan, or orchestrate.
+You receive a specific task from the orchestrator with a chosen execution mode, and you carry it out using the full set of available tools.
+
+## Execution Modes
+
+The orchestrator selects one of these modes when routing to you:
+
+- **direct-stock-tools** — Use OpenCode's built-in read/search/write/edit/bash tools directly to complete a focused task that fits in < 5 files and has no ambiguity.
+- **quick-answer** — Answer a question or provide information using read/search tools only. No file modifications.
+- **inspect-only** — Read and analyze code to answer questions or produce reports. No modifications.
+- **simple-edit** — Make a small, surgical change (rename, typo fix, constant update, config change). Must be reversible and low-risk.
+
+## Rules
+
+1. **Execute exactly what was routed to you.** Do not expand scope.
+2. **Do not invent new workflows.** If the task is bigger than expected, report back to the orchestrator — do not silently absorb it.
+3. **Use the simplest tool for the job.** Prefer read/search for investigation, write/edit for changes, bash for verification.
+4. **Report completion clearly.** Summarize what was done and any issues encountered.
+5. **Escalate if complexity emerges.** If you discover the task touches > 5 files, requires architectural decisions, or involves security-sensitive paths, stop and report to the orchestrator for re-routing.
+
+## Anti-Patterns
+
+- Do NOT act as an orchestrator yourself.
+- Do NOT route work to other agents.
+- Do NOT silently expand a "simple edit" into a full refactor.
+- Do NOT bypass the orchestrator's routing decision.
+
+## Completion Format
+
+When done, respond with:
+
+\`\`\`
+## Execution Complete
+
+**Mode:** <the mode you were given>
+**Files touched:** <list or "none">
+**Summary:** <what was done>
+**Verification:** <how you confirmed it works>
+**Issues:** <any problems found, or "none">
+\`\`\``;
+function createDefaultExecutorAgent(model, customPrompt, customAppendPrompt) {
+  const prompt = resolvePrompt(DEFAULT_EXECUTOR_PROMPT, customPrompt, customAppendPrompt);
+  const definition = {
+    name: "default-executor",
+    description: "Default execution worker for direct, simple tasks routed by the orchestrator. Handles quick-answer, inspect-only, simple-edit, and direct-stock-tools workflows.",
+    config: {
+      temperature: 0.1,
+      prompt
+    }
+  };
+  if (typeof model === "string" && model) {
+    definition.config.model = model;
+  }
+  return definition;
+}
+
 // src/agents/index.ts
 var AGENT_NAMES = [
   "orchestrator",
+  "default-executor",
   "planner",
   "backend-coder",
   "frontend-coder",
@@ -6598,6 +7675,8 @@ function createAgent(name, model, customPrompt, customAppendPrompt) {
   switch (name) {
     case "orchestrator":
       return createOrchestratorAgent(model, customPrompt, customAppendPrompt);
+    case "default-executor":
+      return createDefaultExecutorAgent(model, customPrompt, customAppendPrompt);
     case "planner":
       return createPlannerAgent(model, customPrompt, customAppendPrompt);
     case "backend-coder":
@@ -6687,8 +7766,8 @@ function getAgentConfigs(agentModels) {
 // src/index.ts
 function lazyLoadRulePaths(projectRoot) {
   const __dir = dirname3(fileURLToPath2(import.meta.url));
-  const rulesDir = join24(__dir, "..", "src", "rules");
-  if (!existsSync25(rulesDir))
+  const rulesDir = join26(__dir, "..", "src", "rules");
+  if (!existsSync27(rulesDir))
     return { paths: [], diagnostics: "[LazyRuleLoader] rules directory not found" };
   const detectedLanguages = detectProjectLanguages(projectRoot);
   const paths = getStartupRulePaths(rulesDir, detectedLanguages);
@@ -6698,8 +7777,8 @@ function lazyLoadRulePaths(projectRoot) {
 }
 function loadCommands() {
   const __dir = dirname3(fileURLToPath2(import.meta.url));
-  const commandsDir = join24(__dir, "..", "src", "commands");
-  if (!existsSync25(commandsDir))
+  const commandsDir = join26(__dir, "..", "src", "commands");
+  if (!existsSync27(commandsDir))
     return {};
   const commands = {};
   try {
@@ -6707,7 +7786,7 @@ function loadCommands() {
       if (!file.endsWith(".md"))
         continue;
       const name = basename2(file, ".md");
-      const raw = readFileSync24(join24(commandsDir, file), "utf-8");
+      const raw = readFileSync25(join26(commandsDir, file), "utf-8");
       let description;
       let template = raw;
       const fmMatch = raw.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/);
@@ -6735,7 +7814,8 @@ var plugin = async (input, _options) => {
   const compactionHook = createCompactionHook({ directory }, fileTracker);
   const orchestratorGuard = new OrchestratorGuard;
   const autoLearnHook = createAutoLearnHook(client, fileTracker, directory, appLog);
-  const eventLog = createEventLogHooks(appLog);
+  let loopDetector;
+  let eventLog;
   const notifCtrl = new NotificationController(undefined, appLog);
   const agentConfigs = getAgentConfigs({});
   const mcps = createFlowDeckMcps();
@@ -6750,6 +7830,16 @@ var plugin = async (input, _options) => {
       }
       const flowdeckConfig = loadFlowDeckConfig(directory);
       const designFirstConfig = resolveDesignFirstConfig(flowdeckConfig);
+      const loopCfg = flowdeckConfig.governance?.loopDetection ?? {};
+      loopDetector = new LoopDetector({
+        enabled: loopCfg.enabled ?? true,
+        maxRepeats: loopCfg.maxRepeats ?? 2,
+        similarityThreshold: loopCfg.similarityThreshold ?? 0.9,
+        historySize: loopCfg.historySize ?? 20
+      }, appLog);
+      eventLog = createEventLogHooks(appLog, (toolName, args, output, sessionId, status) => {
+        loopDetector?.recordAfter(toolName, args, output, sessionId, status);
+      });
       const agentModels = {};
       for (const [name, agentCfg] of Object.entries(flowdeckConfig.agents ?? {})) {
         if (agentCfg.model) {
@@ -6789,8 +7879,8 @@ var plugin = async (input, _options) => {
           }
         }
       }
-      const skillsDir = join24(dirname3(fileURLToPath2(import.meta.url)), "..", "src", "skills");
-      if (existsSync25(skillsDir)) {
+      const skillsDir = join26(dirname3(fileURLToPath2(import.meta.url)), "..", "src", "skills");
+      if (existsSync27(skillsDir)) {
         const cfgAny = cfg;
         if (!cfgAny.skills || typeof cfgAny.skills !== "object") {
           cfgAny.skills = { paths: [] };
@@ -6829,7 +7919,8 @@ var plugin = async (input, _options) => {
       codegraph: codegraphTool,
       "load-rules": loadRulesTool,
       "list-rules": listRulesTool,
-      "rtk-setup": rtkSetupTool
+      "rtk-setup": rtkSetupTool,
+      "merge-assist": mergeAssistTool
     },
     "shell.env": shellEnvHook,
     "todo.updated": todoHook,
@@ -6898,9 +7989,19 @@ var plugin = async (input, _options) => {
       await patchTrustHook({ directory }, toolInput, toolOutput);
       await decisionTraceHook({ directory }, toolInput, toolOutput);
       await eventLog.before({ directory }, toolInput, toolOutput);
+      const loopResult = loopDetector.checkBefore(toolInput.tool ?? toolInput.name ?? "unknown", toolOutput?.args ?? toolInput?.args ?? {}, toolInput.sessionID ?? "");
+      if (loopResult.action === "block") {
+        throw new Error(loopResult.escalationMessage);
+      }
+      if (loopResult.action === "warn") {
+        appLog(loopResult.message);
+      }
     },
     "tool.execute.after": async (toolInput, toolOutput) => {
-      await eventLog.after({ directory }, toolInput, toolOutput);
+      const eventLogHealthy = await eventLog.after({ directory }, toolInput, toolOutput);
+      if (!eventLogHealthy) {
+        loopDetector.setPersistenceHealthy(false);
+      }
       await contextMonitor["tool.execute.after"](toolInput, toolOutput);
     }
   };