@dv.nghiem/flowdeck 0.3.5 → 0.3.7

package/dist/index.js

@@ -1709,23 +1709,34 @@ import { Database } from "bun:sqlite";
 import { existsSync as existsSync15, mkdirSync as mkdirSync10 } from "fs";
 import { join as join15 } from "path";
 import { homedir } from "os";
-var MEMORY_DIR = join15(homedir(), ".flowdeck-memory");
-var DB_PATH = join15(MEMORY_DIR, "memory.db");
-function ensureDir() {
-  if (!existsSync15(MEMORY_DIR)) {
-    mkdirSync10(MEMORY_DIR, { recursive: true });
-  }
+function resolveMemoryDir() {
+  return process.env.FLOWDECK_MEMORY_DIR ?? join15(homedir(), ".flowdeck-memory");
 }
+var JS_RETRY_COUNT = 3;
+var JS_RETRY_BASE_MS = 50;
 var db = null;
+function debugLog(msg) {
+  if (process.env.FLOWDECK_MEMORY_DEBUG) {
+    console.error(`[FlowDeck Memory] ${msg}`);
+  }
+}
 function getDb() {
   if (!db) {
-    ensureDir();
-    db = new Database(DB_PATH);
+    const dir = resolveMemoryDir();
+    if (!existsSync15(dir))
+      mkdirSync10(dir, { recursive: true });
+    const dbPath = join15(dir, "memory.db");
+    db = new Database(dbPath);
+    debugLog(`DB opened: ${dbPath}`);
     initializeSchema(db);
   }
   return db;
 }
 function initializeSchema(database) {
+  database.run("PRAGMA journal_mode = WAL");
+  database.run("PRAGMA busy_timeout = 5000");
+  database.run("PRAGMA synchronous = NORMAL");
+  database.run("PRAGMA wal_autocheckpoint = 1000");
   const schema = `
     CREATE TABLE IF NOT EXISTS sessions (
       id INTEGER PRIMARY KEY AUTOINCREMENT,
@@ -1753,6 +1764,7 @@ function initializeSchema(database) {
       id INTEGER PRIMARY KEY AUTOINCREMENT,
       session_id INTEGER NOT NULL UNIQUE,
       content TEXT NOT NULL,
+      metadata TEXT,
       created_at TEXT NOT NULL DEFAULT (datetime('now')),
       FOREIGN KEY (session_id) REFERENCES sessions(id)
     );
@@ -1764,6 +1776,49 @@ function initializeSchema(database) {
     CREATE INDEX IF NOT EXISTS idx_sessions_directory ON sessions(directory);
   `;
   database.run(schema);
+  const summaryColumns = database.prepare("PRAGMA table_info(summaries)").all().map((c) => c.name);
+  if (!summaryColumns.includes("metadata")) {
+    database.run("ALTER TABLE summaries ADD COLUMN metadata TEXT");
+    debugLog("Migrated summaries table: added metadata column");
+  }
+}
+function isBusyError(err) {
+  if (!err || typeof err !== "object")
+    return false;
+  const e = err;
+  return e.code === "SQLITE_BUSY" || (e.message?.includes("database is locked") ?? false);
+}
+function sleepSync(ms) {
+  try {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+  } catch {
+    const end = Date.now() + ms;
+    while (Date.now() < end) {}
+  }
+}
+function executeWrite(fn, context) {
+  for (let attempt = 0;attempt <= JS_RETRY_COUNT; attempt++) {
+    const start = Date.now();
+    try {
+      const result = fn();
+      const duration = Date.now() - start;
+      if (attempt > 0) {
+        debugLog(`${context}: succeeded after ${attempt} JS retr${attempt === 1 ? "y" : "ies"} (${duration}ms)`);
+      } else {
+        debugLog(`${context}: completed in ${duration}ms`);
+      }
+      return result;
+    } catch (err) {
+      if (isBusyError(err) && attempt < JS_RETRY_COUNT) {
+        const delay = JS_RETRY_BASE_MS * (attempt + 1);
+        debugLog(`${context}: SQLITE_BUSY — JS retry ${attempt + 1}/${JS_RETRY_COUNT} after ${delay}ms`);
+        sleepSync(delay);
+        continue;
+      }
+      throw err;
+    }
+  }
+  throw new Error(`${context}: exhausted all retries`);
 }
 function serializeToolInput(input) {
   if (!input)
@@ -1791,7 +1846,7 @@ function initSession(contentSessionId, project, directory) {
     database.prepare("UPDATE sessions SET last_active_at = ?, prompt_count = prompt_count + 1 WHERE id = ?").run(now, existing.id);
     return { ...existing, last_active_at: now, prompt_count: (existing.prompt_count || 0) + 1 };
   }
-  const result = database.prepare("INSERT INTO sessions (content_session_id, project, directory, created_at, last_active_at) VALUES (?, ?, ?, ?, ?)").run(contentSessionId, project, directory, now, now);
+  const result = database.prepare("INSERT INTO sessions (content_session_id, project, directory, created_at, last_active_at, prompt_count) VALUES (?, ?, ?, ?, ?, ?)").run(contentSessionId, project, directory, now, now, 1);
   return {
     id: result.lastInsertRowid,
     content_session_id: contentSessionId,
@@ -1805,27 +1860,38 @@ function initSession(contentSessionId, project, directory) {
 function storeObservation(sessionId, toolName, toolInput, toolResponse, directory) {
   const database = getDb();
   const now = new Date().toISOString();
-  const result = database.prepare("INSERT INTO observations (session_id, tool_name, tool_input, tool_response, directory, created_at) VALUES (?, ?, ?, ?, ?, ?)").run(sessionId, toolName, serializeToolInput(toolInput), toolResponse ? toolResponse.slice(0, 1e4) : null, directory, now);
-  database.prepare("UPDATE sessions SET last_active_at = ? WHERE id = ?").run(now, sessionId);
+  const serializedInput = serializeToolInput(toolInput);
+  const truncatedResponse = toolResponse ? toolResponse.slice(0, 1e4) : null;
+  const result = executeWrite(database.transaction(() => {
+    const r = database.prepare("INSERT INTO observations (session_id, tool_name, tool_input, tool_response, directory, created_at) VALUES (?, ?, ?, ?, ?, ?)").run(sessionId, toolName, serializedInput, truncatedResponse, directory, now);
+    database.prepare("UPDATE sessions SET last_active_at = ? WHERE id = ?").run(now, sessionId);
+    return r;
+  }), `storeObservation(${toolName})`);
   return {
     id: result.lastInsertRowid,
     session_id: sessionId,
     tool_name: toolName,
-    tool_input: parseToolInput(serializeToolInput(toolInput)),
-    tool_response: toolResponse ? toolResponse.slice(0, 1e4) : null,
+    tool_input: parseToolInput(serializedInput),
+    tool_response: truncatedResponse,
     directory,
     created_at: now
   };
 }
-function storeSummary(sessionId, content) {
+function storeSummary(sessionId, content, metadata) {
   const database = getDb();
   const now = new Date().toISOString();
-  database.prepare("INSERT OR REPLACE INTO summaries (session_id, content, created_at) VALUES (?, ?, ?)").run(sessionId, content, now);
-  database.prepare("UPDATE sessions SET summary = ? WHERE id = ?").run(content, sessionId);
+  const serializedMetadata = metadata ? JSON.stringify(metadata) : null;
+  const id = executeWrite(database.transaction(() => {
+    database.prepare("INSERT OR REPLACE INTO summaries (session_id, content, metadata, created_at) VALUES (?, ?, ?, ?)").run(sessionId, content, serializedMetadata, now);
+    database.prepare("UPDATE sessions SET summary = ? WHERE id = ?").run(content.slice(0, 2000), sessionId);
+    return database.prepare("SELECT last_insert_rowid() as id").get().id;
+  }), `storeSummary(session=${sessionId})`);
+  debugLog(`storeSummary: wrote ${content.length} chars${metadata ? ` + ${JSON.stringify(metadata).length}B metadata` : ""} for session ${sessionId}`);
   return {
-    id: database.prepare("SELECT last_insert_rowid() as id").get().id,
+    id,
     session_id: sessionId,
     content,
+    metadata: metadata ?? null,
     created_at: now
   };
 }
@@ -1844,6 +1910,20 @@ function getObservationsForSession(sessionId) {
     tool_input: parseToolInput(obs.tool_input)
   }));
 }
+function getSessionSummary(sessionId) {
+  const database = getDb();
+  const row = database.prepare("SELECT * FROM summaries WHERE session_id = ?").get(sessionId);
+  if (!row)
+    return null;
+  return {
+    ...row,
+    metadata: row.metadata ? JSON.parse(row.metadata) : null
+  };
+}
+function getSessionByContentSessionId(contentSessionId) {
+  const database = getDb();
+  return database.prepare("SELECT * FROM sessions WHERE content_session_id = ?").get(contentSessionId) || null;
+}
 function getRecentObservations(directory, limit = 50) {
   const database = getDb();
   const rows = database.prepare(`SELECT o.*, s.project, s.content_session_id, s.created_at as session_created
@@ -1905,11 +1985,15 @@ function getContextForDirectory(directory, maxObservations = 20) {
       lines.push(`Output: ${preview}${observation.tool_response.length > 300 ? "..." : ""}`);
     }
   }
-  const summaries = getDb().prepare(`SELECT su.* FROM summaries su
+  const summaryRows = getDb().prepare(`SELECT su.* FROM summaries su
        JOIN sessions s ON su.session_id = s.id
        WHERE s.directory = ?
        ORDER BY su.created_at DESC
        LIMIT 3`).all(directory);
+  const summaries = summaryRows.map((r) => ({
+    ...r,
+    metadata: r.metadata ? JSON.parse(r.metadata) : null
+  }));
   if (summaries.length > 0) {
     lines.push(`
 ## Session Summaries`);
@@ -1917,12 +2001,20 @@ function getContextForDirectory(directory, maxObservations = 20) {
       const date = sum.created_at ? new Date(sum.created_at).toLocaleDateString() : "unknown";
       lines.push(`
 ### [${date}]`);
-      lines.push(sum.content.slice(0, 500));
+      lines.push(sum.content.slice(0, 2000));
     }
   }
   return lines.join(`
 `);
 }
+function getDbSettings() {
+  const database = getDb();
+  const journalMode = database.prepare("PRAGMA journal_mode").get().journal_mode;
+  const busyTimeout = database.prepare("PRAGMA busy_timeout").get().timeout;
+  const synchronous = database.prepare("PRAGMA synchronous").get().synchronous;
+  const walAutocheckpoint = database.prepare("PRAGMA wal_autocheckpoint").get().wal_autocheckpoint;
+  return { journal_mode: journalMode, busy_timeout: busyTimeout, synchronous, wal_autocheckpoint: walAutocheckpoint };
+}
 
 // src/tools/memory-search.ts
 var memorySearchTool = tool16({
@@ -1942,8 +2034,14 @@ var memorySearchTool = tool16({
         return JSON.stringify({ error: "Session not found", session_id: args.session_id });
       }
       const observations = getObservationsForSession(targetSession.id);
+      const summary = getSessionSummary(targetSession.id);
       return JSON.stringify({
         session: targetSession,
+        summary: summary ? {
+          content: summary.content,
+          metadata: summary.metadata,
+          created_at: summary.created_at
+        } : null,
         observations: observations.map((o) => ({
           tool_name: o.tool_name,
           tool_input: o.tool_input,
@@ -1990,69 +2088,57 @@ var memorySearchTool = tool16({
 
 // src/tools/memory-status.ts
 import { tool as tool17 } from "@opencode-ai/plugin";
-import { Database as Database2 } from "bun:sqlite";
 import { existsSync as existsSync16 } from "fs";
 import { join as join16 } from "path";
 import { homedir as homedir2 } from "os";
-var DB_PATH2 = join16(homedir2(), ".flowdeck-memory", "memory.db");
+function resolveDbPath() {
+  return join16(process.env.FLOWDECK_MEMORY_DIR ?? join16(homedir2(), ".flowdeck-memory"), "memory.db");
+}
 var memoryStatusTool = tool17({
   description: "Check FlowDeck memory database status, statistics, and recent sessions",
   args: {},
-  async execute(_args, _context) {
+  async execute(_args, context) {
+    const directory = context?.directory ?? process.cwd();
+    const dbPath = resolveDbPath();
     try {
-      const exists = existsSync16(DB_PATH2);
-      const result = {
-        database_exists: exists,
-        path: DB_PATH2,
-        status: exists ? "ACTIVE" : "NOT_INITIALIZED",
-        statistics: null
-      };
-      if (exists) {
-        try {
-          const db2 = new Database2(DB_PATH2);
-          const sessions = db2.prepare("SELECT COUNT(*) as count FROM sessions").get();
-          const observations = db2.prepare("SELECT COUNT(*) as count FROM observations").get();
-          const summaries = db2.prepare("SELECT COUNT(*) as count FROM summaries").get();
-          const recentSessions = db2.prepare(`
-            SELECT 
-              id,
-              content_session_id,
-              project,
-              directory,
-              created_at,
-              last_active_at,
-              prompt_count
-            FROM sessions
-            ORDER BY last_active_at DESC
-            LIMIT 5
-          `).all();
-          result.statistics = {
-            sessions: sessions.count,
-            observations: observations.count,
-            summaries: summaries.count,
-            recent_sessions: recentSessions.map((s) => {
-              const obsCount = db2.prepare("SELECT COUNT(*) as count FROM observations WHERE session_id = ?").get(s.id);
-              return {
-                project: s.project,
-                directory: s.directory,
-                observations_in_session: obsCount.count,
-                last_active: s.last_active_at,
-                prompt_count: s.prompt_count
-              };
-            })
-          };
-          db2.close();
-        } catch (err) {
-          result.status = "ERROR";
-          result.statistics = { error: String(err) };
-        }
+      const exists = existsSync16(dbPath);
+      if (!exists) {
+        return JSON.stringify({
+          database_exists: false,
+          path: dbPath,
+          status: "NOT_INITIALIZED"
+        }, null, 2);
       }
-      return JSON.stringify(result, null, 2);
+      const settings = getDbSettings();
+      const recentSessions = getRecentSessions(directory, 5);
+      const sessionStats = recentSessions.map((s) => {
+        const observations = getObservationsForSession(s.id);
+        const summary = getSessionSummary(s.id);
+        return {
+          project: s.project,
+          directory: s.directory,
+          content_session_id: s.content_session_id,
+          observations_in_session: observations.length,
+          last_active: s.last_active_at,
+          prompt_count: s.prompt_count,
+          has_summary: !!summary,
+          summary_length: summary?.content.length ?? 0,
+          summary_preview: summary?.content.slice(0, 200) ?? null,
+          handoff_metadata: summary?.metadata ?? null
+        };
+      });
+      return JSON.stringify({
+        database_exists: true,
+        path: dbPath,
+        status: "ACTIVE",
+        pragma_settings: settings,
+        recent_sessions_in_directory: sessionStats
+      }, null, 2);
     } catch (err) {
       return JSON.stringify({
         status: "ERROR",
         error: String(err),
-        path: DB_PATH2
+        path: dbPath
       }, null, 2);
     }
   }
@@ -2060,7 +2146,7 @@ var memoryStatusTool = tool17({
 
 // src/hooks/memory-hook.ts
 var MAX_TOOL_RESPONSE = 1e4;
-var MAX_PROMPT_LENGTH = 2000;
+var MAX_SUMMARY_STORAGE = 50000;
 var activeSessions = new Map;
 function extractProjectFromDirectory(directory) {
   const parts = directory.split("/");
@@ -2071,6 +2157,59 @@ function truncate(str, max) {
     return str || "";
   return str.slice(0, max);
 }
+function buildHandoffMetadata(sessionId, directory, summaryText, observations) {
+  const fileTools = new Set(["edit", "create", "view", "read", "hash-edit", "str-replace-editor"]);
+  const importantFilesSet = new Set;
+  for (const obs of observations) {
+    if (fileTools.has(obs.tool_name) && obs.tool_input) {
+      const path = obs.tool_input.path;
+      if (path)
+        importantFilesSet.add(path);
+    }
+  }
+  const toolNamesUsed = [...new Set(observations.map((o) => o.tool_name).filter((t) => t !== "assistant_message"))];
+  function extractBullets(text) {
+    return text.split(`
+`).filter((l) => /^\s*[-*]/.test(l)).map((l) => l.replace(/^\s*[-*]\s+/, "").trim()).filter(Boolean);
+  }
+  const sections = {};
+  let currentSection = "";
+  const currentLines = [];
+  for (const line of summaryText.split(`
+`)) {
+    const header = line.match(/^##\s+\d+\.\s+(.+)/);
+    if (header) {
+      if (currentSection)
+        sections[currentSection] = currentLines.join(`
+`).trim();
+      currentSection = header[1].trim();
+      currentLines.length = 0;
+    } else {
+      currentLines.push(line);
+    }
+  }
+  if (currentSection)
+    sections[currentSection] = currentLines.join(`
+`).trim();
+  const completed = extractBullets(sections["Work Completed"] ?? "");
+  const pending = extractBullets(sections["Remaining Tasks"] ?? "");
+  return {
+    workflow_name: extractProjectFromDirectory(directory),
+    current_status: "compacted",
+    current_stage: null,
+    completed_stages: completed,
+    pending_stages: pending,
+    key_decisions: [],
+    blockers: [],
+    important_files: [...importantFilesSet].slice(0, 30),
+    approvals: [],
+    open_questions: [],
+    next_steps: pending.slice(0, 5),
+    tool_names_used: toolNamesUsed.slice(0, 20),
+    observation_count: observations.length,
+    updated_at: new Date().toISOString()
+  };
+}
 function onSessionCreated(directory, contentSessionId, prompt) {
   const project = extractProjectFromDirectory(directory);
   const session = initSession(contentSessionId, project, directory);
@@ -2095,7 +2234,11 @@ function onToolExecuted(contentSessionId, toolName, toolInput, toolResponse, dir
     };
     activeSessions.set(contentSessionId, ctx);
   }
-  storeObservation(ctx.sessionId, truncate(toolName, 200), toolInput, toolResponse ? truncate(toolResponse, MAX_TOOL_RESPONSE) : null, directory);
+  try {
+    storeObservation(ctx.sessionId, truncate(toolName, 200), toolInput, toolResponse ? truncate(toolResponse, MAX_TOOL_RESPONSE) : null, directory);
+  } catch (err) {
+    console.warn(`[FlowDeck Memory] Failed to store observation for tool "${toolName}":`, err);
+  }
 }
 function onMessageUpdated(contentSessionId, role, content, directory) {
   if (role !== "assistant")
@@ -2114,33 +2257,64 @@ function onMessageUpdated(contentSessionId, role, content, directory) {
     };
     activeSessions.set(contentSessionId, ctx);
   }
-  storeObservation(ctx.sessionId, "assistant_message", { role }, truncate(content, MAX_TOOL_RESPONSE), directory);
+  try {
+    storeObservation(ctx.sessionId, "assistant_message", { role }, truncate(content, MAX_TOOL_RESPONSE), directory);
+  } catch (err) {
+    console.warn("[FlowDeck Memory] Failed to store assistant message observation:", err);
+  }
 }
 function onSessionCompact(contentSessionId, summary) {
-  const ctx = activeSessions.get(contentSessionId);
-  if (!ctx)
-    return;
-  storeSummary(ctx.sessionId, truncate(summary, MAX_PROMPT_LENGTH));
+  let ctx = activeSessions.get(contentSessionId);
+  if (!ctx) {
+    const dbSession = getSessionByContentSessionId(contentSessionId);
+    if (!dbSession) {
+      console.warn(`[FlowDeck Memory] onSessionCompact: no session found for contentSessionId=${contentSessionId} — summary discarded`);
+      return;
+    }
+    ctx = {
+      sessionId: dbSession.id,
+      contentSessionId,
+      project: dbSession.project,
+      directory: dbSession.directory
+    };
+    activeSessions.set(contentSessionId, ctx);
+  }
+  const storedContent = truncate(summary, MAX_SUMMARY_STORAGE);
+  try {
+    const observations = getObservationsForSession(ctx.sessionId);
+    const metadata = buildHandoffMetadata(ctx.sessionId, ctx.directory, summary, observations);
+    storeSummary(ctx.sessionId, storedContent, metadata);
+  } catch (err) {
+    console.warn(`[FlowDeck Memory] Failed to store compaction summary for session ${ctx.sessionId}:`, err);
+  }
 }
 function onSessionEnd(contentSessionId, lastMessage) {
-  const ctx = activeSessions.get(contentSessionId);
-  if (!ctx)
-    return;
-  if (lastMessage && lastMessage.trim()) {
-    storeSummary(ctx.sessionId, truncate(lastMessage, MAX_PROMPT_LENGTH));
+  let ctx = activeSessions.get(contentSessionId);
+  if (!ctx) {
+    const dbSession = getSessionByContentSessionId(contentSessionId);
+    if (dbSession) {
+      ctx = {
+        sessionId: dbSession.id,
+        contentSessionId,
+        project: dbSession.project,
+        directory: dbSession.directory
+      };
+    }
+  }
+  if (ctx && lastMessage && lastMessage.trim()) {
+    try {
+      const observations = getObservationsForSession(ctx.sessionId);
+      const metadata = buildHandoffMetadata(ctx.sessionId, ctx.directory, lastMessage, observations);
+      storeSummary(ctx.sessionId, truncate(lastMessage, MAX_SUMMARY_STORAGE), metadata);
+    } catch (err) {
+      console.warn(`[FlowDeck Memory] Failed to store end-of-session summary for session ${ctx?.sessionId}:`, err);
+    }
   }
   activeSessions.delete(contentSessionId);
 }
 function getSessionContext(directory, contentSessionId) {
   const context = getContextForDirectory(directory, 30);
   const previousSessions = getRecentSessions(directory, 5);
-  if (previousSessions.length > 0 && activeSessions.has(contentSessionId)) {
-    const ctx = activeSessions.get(contentSessionId);
-    for (const prev of previousSessions) {
-      if (prev.content_session_id === contentSessionId)
-        continue;
-    }
-  }
   return { context, previousSessions };
 }
 function clearSession(contentSessionId) {
@@ -6104,6 +6278,133 @@ var createDesignAgent = (model, customPrompt, customAppendPrompt) => {
   };
 };
 
+// src/agents/supervisor.ts
+var SUPERVISOR_PROMPT = `You are the FlowDeck Supervisor Agent — a governance layer that reviews existing commands and agents before or after execution.
+
+## Role and Hard Constraints
+
+**You review. You do not execute.**
+
+You sit above the orchestrator's execution path. Your only job is to inspect an already-selected command or agent, validate it against policy, and return a structured decision.
+
+### You MUST NEVER:
+- Invent a new command name
+- Invent a new workflow definition
+- Suggest creating a new agent
+- Replace or duplicate the orchestrator
+- Execute implementation tasks
+- Become a second dispatcher
+- Modify the intent of an existing command
+
+### You MAY:
+- Inspect an existing registered command or agent
+- Validate that required stages are present
+- Detect policy violations in the selected target
+- Flag risk before execution
+- Decide: approve / revise / block / escalate
+- Request that the orchestrator obtain missing prerequisites
+
+## Registered Commands (source of truth — do not add to this list)
+
+fd-ask, fd-checkpoint, fd-deploy-check, fd-design, fd-discuss, fd-doctor,
+fd-execute, fd-fix-bug, fd-map-codebase, fd-multi-repo, fd-new-feature,
+fd-new-project, fd-plan, fd-quick, fd-reflect, fd-resume, fd-status,
+fd-suggest, fd-translate-intent, fd-verify, fd-write-docs
+
+## Registered Agents (source of truth — do not add to this list)
+
+orchestrator, planner, backend-coder, frontend-coder, devops, plan-checker,
+tester, reviewer, researcher, writer, security-auditor, doc-updater, mapper,
+code-explorer, debug-specialist, build-error-resolver, task-splitter, discusser,
+architect, risk-analyst, policy-enforcer, performance-optimizer, refactor-guide,
+auto-learner, design, supervisor
+
+## Policy Checks
+
+When reviewing a command or agent, evaluate ONLY the following against what already exists:
+
+### Design-first policy
+- If the task is UI-heavy (dashboard, landing page, web app, UI, UX, admin panel) and the current phase is "execute", the design stage MUST have completed with approval.
+- If design approval is absent: decision = revise | required change = complete design stage first.
+
+### Bugfix regression policy
+- If the command is fd-fix-bug, a regression test MUST exist before implementation.
+- If no regression test: decision = revise | required change = write failing regression test first.
+
+### Phase ordering policy
+- fd-execute must only run in the "execute" phase.
+- If invoked in a different phase: decision = revise.
+
+### Missing inputs policy
+- If a registered agent has required inputs listed in its contract and they are absent: decision = revise.
+
+### Approval gate policy
+- If an operation requires explicit human approval and none was granted: decision = escalate.
+
+### Unregistered target policy
+- If the requested command or agent is NOT in the registered lists above: decision = block.
+- Do NOT suggest or create a replacement. Report that the target is unavailable.
+
+## Decision Output Format
+
+Always respond with a valid JSON object matching this schema exactly:
+
+\`\`\`json
+{
+  "decision": "approve" | "revise" | "block" | "escalate",
+  "targetType": "command" | "agent" | "workflow",
+  "targetName": "<exact registered name>",
+  "exists": true | false,
+  "reasons": ["<human-readable reason>"],
+  "missingRequirements": ["<what is absent>"],
+  "riskFlags": ["<risk description>"],
+  "requiredChanges": ["<what must change before proceeding>"],
+  "approvalStatus": "approved" | "pending" | "denied" | "escalated",
+  "confidenceScore": 0.0–1.0,
+  "reviewPhase": "preflight" | "post-stage",
+  "timestamp": "<ISO 8601>"
+}
+\`\`\`
+
+### Decision rules:
+- **approve**: target exists, all policy checks pass, confidence ≥ threshold
+- **revise**: target exists, fixable issues found — list requiredChanges so caller can resolve
+- **block**: target does not exist OR critical unfixable policy violation
+- **escalate**: human approval required OR confidence below threshold
+
+### On unregistered targets:
+If a requested command or workflow is not in the registered lists, set:
+- decision: "block"
+- exists: false
+- reasons: explain the target is not registered
+- requiredChanges: list valid registered alternatives
+- Do NOT invent a new command or workflow to substitute
+
+## Diagnostics
+
+Before issuing a decision, log:
+1. Which existing command/agent was reviewed
+2. Whether it exists in the registry
+3. Which policy checks ran
+4. Why the decision was reached
+5. Whether review is preflight or post-stage
+6. Whether human escalation is recommended`;
+function createSupervisorAgent(model, customPrompt, customAppendPrompt) {
+  const prompt = resolvePrompt(SUPERVISOR_PROMPT, customPrompt, customAppendPrompt);
+  const definition = {
+    name: "supervisor",
+    description: "Governance supervisor that reviews existing commands and agents before execution. Approves, revises, blocks, or escalates — never creates new commands or 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",
@@ -6130,7 +6431,8 @@ var AGENT_NAMES = [
   "performance-optimizer",
   "refactor-guide",
   "auto-learner",
-  "design"
+  "design",
+  "supervisor"
 ];
 var PRIMARY_AGENTS = new Set(["orchestrator"]);
 var ALL_MODES_AGENTS = new Set;
@@ -6196,6 +6498,8 @@ function createAgent(name, model, customPrompt, customAppendPrompt) {
       return createAutoLearnerAgent(model);
     case "design":
       return createDesignAgent(model, customPrompt, customAppendPrompt);
+    case "supervisor":
+      return createSupervisorAgent(model, customPrompt, customAppendPrompt);
     default:
       console.warn(`[flowdeck] Unknown agent: ${name}`);
       return;
@@ -6233,6 +6537,632 @@ function getAgentConfigs(agentModels) {
   return configs;
 }
 
+// src/services/agent-contract-registry.ts
+var CONTRACTS = [
+  {
+    agent: "orchestrator",
+    role: "Coordinate multi-agent execution. Delegates all work — never implements directly.",
+    allowedTaskTypes: ["orchestration", "coordination", "delegation", "phase-management"],
+    requiredInputs: ["STATE.md", "PLAN.md"],
+    expectedOutputFields: ["delegated_steps", "completed_steps", "current_phase"],
+    allowedTools: [
+      "delegate",
+      "run-pipeline",
+      "council",
+      "planning-state",
+      "codebase-state",
+      "workspace-state",
+      "repo-memory",
+      "decision-trace",
+      "policy-engine",
+      "context-generator",
+      "create-skill",
+      "reflect"
+    ],
+    forbiddenActions: [
+      "write_file",
+      "edit_file",
+      "create_file",
+      "bash",
+      "patch",
+      "apply_patch",
+      "read source files directly"
+    ],
+    escalationConditions: [
+      "delegated agent fails twice",
+      "delegation budget exhausted",
+      "deadlock detected",
+      "all agents blocked on the same step"
+    ],
+    stopConditions: [
+      "all PLAN.md steps completed",
+      "user requests stop",
+      "budget exceeded with no fallback"
+    ],
+    successCriteria: [
+      "all plan steps delegated and completed",
+      "STATE.md phase updated to review",
+      "no implementation performed directly by orchestrator"
+    ]
+  },
+  {
+    agent: "planner",
+    role: "Create detailed implementation plans. Output PLAN.md with numbered steps.",
+    allowedTaskTypes: ["planning", "task-breakdown", "step-decomposition"],
+    requiredInputs: ["task description or STATE.md"],
+    expectedOutputFields: ["steps", "phase"],
+    allowedTools: ["read", "glob", "grep", "planning-state", "workspace-state"],
+    forbiddenActions: [
+      "write source files",
+      "run bash commands",
+      "edit application code",
+      "implement features"
+    ],
+    escalationConditions: [
+      "requirements are ambiguous",
+      "dependencies between steps unclear",
+      "conflicting constraints"
+    ],
+    stopConditions: ["PLAN.md written and reviewed by plan-checker", "user confirms plan"],
+    successCriteria: [
+      "PLAN.md contains numbered steps with assigned agents",
+      "each step has clear success criteria",
+      "no implementation performed"
+    ]
+  },
+  {
+    agent: "plan-checker",
+    role: "Review PLAN.md quality before execution. Read-only.",
+    allowedTaskTypes: ["plan-review", "quality-check"],
+    requiredInputs: ["PLAN.md"],
+    expectedOutputFields: ["verdict", "issues", "recommendations"],
+    allowedTools: ["read", "glob", "grep"],
+    forbiddenActions: ["write or edit any files", "modify PLAN.md"],
+    escalationConditions: ["plan is fundamentally flawed", "critical gaps found"],
+    stopConditions: ["review complete", "verdict issued"],
+    successCriteria: ["structured review output", "no file modifications"]
+  },
+  {
+    agent: "design",
+    role: "Design UX, wireframes, and visual systems for UI-heavy tasks.",
+    allowedTaskTypes: ["ux-design", "wireframe", "visual-system", "design-handoff", "frontend-handoff"],
+    requiredInputs: ["task description", "requirements"],
+    expectedOutputFields: ["design_stage", "wireframes", "component_structure", "design_tokens"],
+    allowedTools: ["read", "write", "glob", "grep", "planning-state"],
+    forbiddenActions: [
+      "run bash commands",
+      "write application logic",
+      "implement backend code",
+      "implement React components"
+    ],
+    escalationConditions: [
+      "design requirements unclear",
+      "conflicting UX requirements",
+      "brand guidelines missing"
+    ],
+    stopConditions: ["design_stage=handoff_complete", "design_approved=true"],
+    successCriteria: [
+      "design document written",
+      "design_stage set to handoff_complete",
+      "design_approved set to true",
+      "no application code written"
+    ]
+  },
+  {
+    agent: "backend-coder",
+    role: "Implement backend features: API, services, data layer, business logic.",
+    allowedTaskTypes: ["implementation", "backend", "api", "database", "service", "bugfix"],
+    requiredInputs: ["PLAN.md step description", "relevant context files"],
+    expectedOutputFields: ["files_modified", "summary"],
+    allowedTools: ["read", "write", "edit", "bash", "glob", "grep"],
+    forbiddenActions: [
+      "modify frontend UI component files",
+      "change CI/CD config without devops involvement"
+    ],
+    escalationConditions: [
+      "architecture decision needed",
+      "security-sensitive change without audit",
+      "database migration required"
+    ],
+    stopConditions: ["step implementation complete", "tests pass", "reviewer approves"],
+    successCriteria: [
+      "code written per plan step",
+      "no regressions introduced",
+      "tests exist or updated"
+    ]
+  },
+  {
+    agent: "frontend-coder",
+    role: "Implement frontend features: UI components, client state, rendering.",
+    allowedTaskTypes: ["implementation", "frontend", "ui", "component", "styling", "bugfix"],
+    requiredInputs: ["PLAN.md step description", "design handoff for UI-heavy tasks"],
+    expectedOutputFields: ["files_modified", "summary"],
+    allowedTools: ["read", "write", "edit", "bash", "glob", "grep"],
+    forbiddenActions: [
+      "modify backend API files",
+      "change server configuration",
+      "implement without approved design for UI-heavy tasks"
+    ],
+    escalationConditions: [
+      "design handoff missing for UI-heavy task",
+      "component library or design system unclear"
+    ],
+    stopConditions: ["step implementation complete", "tests pass", "reviewer approves"],
+    successCriteria: [
+      "components implemented per approved design",
+      "no regressions introduced",
+      "tests exist or updated"
+    ]
+  },
+  {
+    agent: "devops",
+    role: "Implement DevOps and infrastructure changes: CI/CD, deployment, infra scripts.",
+    allowedTaskTypes: ["implementation", "ci-cd", "deployment", "infrastructure", "operations"],
+    requiredInputs: ["PLAN.md step description"],
+    expectedOutputFields: ["files_modified", "summary"],
+    allowedTools: ["read", "write", "edit", "bash", "glob", "grep"],
+    forbiddenActions: [
+      "modify application source code",
+      "deploy to production without approval"
+    ],
+    escalationConditions: [
+      "production deployment requires approval",
+      "destructive infra change"
+    ],
+    stopConditions: ["pipeline or infra change complete", "reviewer approves"],
+    successCriteria: ["infrastructure code written per plan", "no prod deployment without approval"]
+  },
+  {
+    agent: "tester",
+    role: "Write and run tests following TDD principles. Tests before implementation.",
+    allowedTaskTypes: ["testing", "tdd", "regression", "integration-test", "unit-test"],
+    requiredInputs: ["feature or step description", "relevant source files"],
+    expectedOutputFields: ["test_files_written", "tests_passing", "coverage_summary"],
+    allowedTools: ["read", "write", "edit", "bash", "glob", "grep"],
+    forbiddenActions: [
+      "delete failing tests to make suite pass",
+      "implement application features",
+      "skip TDD cycle (red → green → refactor)"
+    ],
+    escalationConditions: [
+      "test infrastructure broken",
+      "flaky tests blocking all progress"
+    ],
+    stopConditions: ["all tests pass", "coverage meets threshold"],
+    successCriteria: [
+      "tests written before implementation",
+      "all new tests pass",
+      "no test deletions to fix failures"
+    ]
+  },
+  {
+    agent: "reviewer",
+    role: "Review code quality, security, and convention adherence. Read-only.",
+    allowedTaskTypes: ["review", "code-review", "quality-check"],
+    requiredInputs: ["files to review", "context of changes"],
+    expectedOutputFields: ["verdict", "issues", "recommendations"],
+    allowedTools: ["read", "glob", "grep"],
+    forbiddenActions: [
+      "write or edit any files",
+      "make code changes",
+      "approve security-sensitive changes without security audit"
+    ],
+    escalationConditions: [
+      "security issues found",
+      "critical bugs found",
+      "architectural violations"
+    ],
+    stopConditions: ["review complete", "verdict issued"],
+    successCriteria: [
+      "structured review output with severity levels",
+      "issues categorized",
+      "no file modifications"
+    ]
+  },
+  {
+    agent: "security-auditor",
+    role: "Security audit: OWASP Top 10, injection, auth vulnerabilities. Read-only.",
+    allowedTaskTypes: ["security-audit", "vulnerability-scan", "auth-review"],
+    requiredInputs: ["files to audit", "change context"],
+    expectedOutputFields: ["findings", "severity_breakdown", "recommendations"],
+    allowedTools: ["read", "glob", "grep"],
+    forbiddenActions: [
+      "write or edit files",
+      "make changes to fix vulnerabilities directly"
+    ],
+    escalationConditions: [
+      "CRITICAL vulnerability found",
+      "auth bypass detected",
+      "data exposure found"
+    ],
+    stopConditions: ["audit complete", "all findings documented"],
+    successCriteria: [
+      "OWASP checklist evaluated",
+      "findings documented with severity levels",
+      "no file modifications"
+    ]
+  },
+  {
+    agent: "researcher",
+    role: "Research documentation, APIs, best practices. Read-only analysis.",
+    allowedTaskTypes: ["research", "api-lookup", "documentation", "best-practices"],
+    requiredInputs: ["research topic or question"],
+    expectedOutputFields: ["findings", "references", "recommendations"],
+    allowedTools: ["read", "glob", "grep", "web-search"],
+    forbiddenActions: ["write or edit files", "implement solutions"],
+    escalationConditions: [
+      "critical information unavailable",
+      "conflicting official documentation"
+    ],
+    stopConditions: ["research question answered", "findings documented"],
+    successCriteria: [
+      "findings clearly summarized",
+      "sources cited",
+      "no file modifications"
+    ]
+  },
+  {
+    agent: "architect",
+    role: "Design system architecture, create ADRs, define API contracts.",
+    allowedTaskTypes: ["architecture", "adr", "api-design", "system-design"],
+    requiredInputs: ["feature or system description", "existing codebase context"],
+    expectedOutputFields: ["architecture_document", "adr", "api_contracts"],
+    allowedTools: ["read", "write", "glob", "grep", "planning-state"],
+    forbiddenActions: ["write application code", "run bash commands"],
+    escalationConditions: [
+      "major architectural conflict with existing system",
+      "breaking API change required"
+    ],
+    stopConditions: ["ADR written", "architecture reviewed"],
+    successCriteria: [
+      "architecture documented with tradeoffs",
+      "no application code written"
+    ]
+  },
+  {
+    agent: "writer",
+    role: "Draft project documentation: README, API docs, user guides.",
+    allowedTaskTypes: ["documentation", "readme", "api-docs", "user-guide"],
+    requiredInputs: ["feature description or codebase context"],
+    expectedOutputFields: ["documentation_files"],
+    allowedTools: ["read", "write", "edit", "glob", "grep"],
+    forbiddenActions: ["modify application code", "run bash commands"],
+    escalationConditions: ["documentation scope unclear"],
+    stopConditions: ["docs written", "user confirms completeness"],
+    successCriteria: [
+      "documentation written and accurate",
+      "no application code changed"
+    ]
+  },
+  {
+    agent: "doc-updater",
+    role: "Update existing documentation after code changes.",
+    allowedTaskTypes: ["documentation-update", "doc-sync"],
+    requiredInputs: ["changed files", "change summary"],
+    expectedOutputFields: ["updated_docs"],
+    allowedTools: ["read", "write", "edit", "glob", "grep"],
+    forbiddenActions: [
+      "modify application code",
+      "delete documentation without replacement"
+    ],
+    escalationConditions: ["documentation conflicts with implementation"],
+    stopConditions: ["docs updated and synced"],
+    successCriteria: ["docs reflect current code", "no application code changed"]
+  },
+  {
+    agent: "supervisor",
+    role: "Governance review layer. Inspects existing commands/agents, validates policy, returns structured approve/revise/block/escalate decision. Never creates new commands or workflows.",
+    allowedTaskTypes: ["governance-review", "policy-check", "pre-execution-review", "post-stage-review"],
+    requiredInputs: ["target name (command or agent)", "task context"],
+    expectedOutputFields: ["decision", "targetType", "targetName", "exists", "reasons", "missingRequirements", "riskFlags", "requiredChanges", "approvalStatus", "confidenceScore"],
+    allowedTools: ["read", "glob", "grep", "planning-state", "policy-engine"],
+    forbiddenActions: [
+      "create new commands",
+      "create new workflows",
+      "invent new agent names",
+      "modify command intent",
+      "replace orchestrator",
+      "become second dispatcher",
+      "execute implementation tasks",
+      "write or edit source files",
+      "run bash commands",
+      "modify PLAN.md or STATE.md"
+    ],
+    escalationConditions: [
+      "human approval required and not granted",
+      "confidence below threshold",
+      "critical policy violation with no safe path forward"
+    ],
+    stopConditions: ["structured decision issued", "review complete"],
+    successCriteria: [
+      "structured SupervisorDecision returned",
+      "no new commands or workflows created",
+      "existing registry not modified",
+      "decision is one of: approve, revise, block, escalate"
+    ]
+  }
+];
+var REGISTRY = new Map(CONTRACTS.map((c) => [c.agent, c]));
+function getContract(agent) {
+  return REGISTRY.get(agent) ?? null;
+}
+
+// src/services/supervisor-binding.ts
+var REGISTERED_COMMANDS = [
+  "fd-ask",
+  "fd-checkpoint",
+  "fd-deploy-check",
+  "fd-design",
+  "fd-discuss",
+  "fd-doctor",
+  "fd-execute",
+  "fd-fix-bug",
+  "fd-map-codebase",
+  "fd-multi-repo",
+  "fd-new-feature",
+  "fd-new-project",
+  "fd-plan",
+  "fd-quick",
+  "fd-reflect",
+  "fd-resume",
+  "fd-status",
+  "fd-suggest",
+  "fd-translate-intent",
+  "fd-verify",
+  "fd-write-docs"
+];
+function resolveSupervisorConfig(directory) {
+  try {
+    const config = loadFlowDeckConfig(directory);
+    const sup = config?.governance?.supervisor ?? {};
+    return {
+      enabled: sup.enabled ?? false,
+      mode: sup.mode ?? "advisory",
+      reviewedTargets: sup.reviewedTargets ?? [],
+      canBlock: sup.canBlock ?? true,
+      confidenceThreshold: sup.confidenceThreshold ?? 0.7,
+      postExecutionReview: sup.postExecutionReview ?? false
+    };
+  } catch {
+    return {
+      enabled: false,
+      mode: "advisory",
+      reviewedTargets: [],
+      canBlock: true,
+      confidenceThreshold: 0.7,
+      postExecutionReview: false
+    };
+  }
+}
+function isRegisteredCommand(name) {
+  return REGISTERED_COMMANDS.includes(name);
+}
+function isRegisteredAgent(name) {
+  return AGENT_NAMES.includes(name);
+}
+function isRegisteredTarget(name) {
+  if (isRegisteredCommand(name))
+    return { exists: true, type: "command" };
+  if (isRegisteredAgent(name))
+    return { exists: true, type: "agent" };
+  return { exists: false, type: "agent" };
+}
+function checkCommandPolicy(commandName, ctx) {
+  const reasons = [];
+  const riskFlags = [];
+  const missingRequirements = [];
+  const requiredChanges = [];
+  if (commandName === "fd-new-feature" || commandName === "fd-execute") {
+    const taskLower = (ctx.taskDescription ?? "").toLowerCase();
+    const isUiHeavy = /landing page|dashboard|admin panel|website|web app|ui|ux|interface|frontend|component/.test(taskLower);
+    if (isUiHeavy && ctx.currentPhase === "execute" && ctx.designApprovalPresent === false) {
+      missingRequirements.push("design approval (design stage must complete before execute for UI-heavy tasks)");
+      riskFlags.push("UI-heavy task entering execute phase without design approval");
+      requiredChanges.push("Run /fd-design first and obtain design approval before proceeding to execute");
+    }
+  }
+  if (commandName === "fd-fix-bug") {
+    if (ctx.regressionTestPresent === false) {
+      missingRequirements.push("regression test (required before bugfix implementation)");
+      riskFlags.push("Bugfix command invoked without a regression test");
+      requiredChanges.push("Write a failing regression test before implementing the fix");
+    }
+  }
+  if (commandName === "fd-deploy-check") {
+    if (ctx.prerequisitesMet === false && ctx.missingInputs && ctx.missingInputs.length > 0) {
+      missingRequirements.push(...ctx.missingInputs);
+      riskFlags.push("Deploy check attempted with unmet prerequisites");
+    }
+  }
+  if (commandName === "fd-execute" && ctx.currentPhase && ctx.currentPhase !== "execute") {
+    riskFlags.push(`fd-execute invoked in phase "${ctx.currentPhase}" instead of "execute"`);
+    requiredChanges.push(`Ensure project phase is "execute" before running fd-execute (currently: ${ctx.currentPhase})`);
+  }
+  if (ctx.approvalRequired && !ctx.approvalGranted) {
+    missingRequirements.push("human approval (required for this command)");
+    riskFlags.push("Approval gate not satisfied");
+    requiredChanges.push("Obtain explicit human approval before proceeding");
+  }
+  const passed = missingRequirements.length === 0 && riskFlags.length === 0 && requiredChanges.length === 0;
+  if (passed) {
+    reasons.push(`Command "${commandName}" passed all policy checks`);
+  }
+  return { passed, reasons, riskFlags, missingRequirements, requiredChanges };
+}
+function checkAgentPolicy(agentName, ctx) {
+  const reasons = [];
+  const riskFlags = [];
+  const missingRequirements = [];
+  const requiredChanges = [];
+  const contract = getContract(agentName);
+  if (!contract) {
+    riskFlags.push(`Agent "${agentName}" has no registered capability contract`);
+    return { passed: false, reasons, riskFlags, missingRequirements, requiredChanges };
+  }
+  if (ctx.missingInputs && ctx.missingInputs.length > 0) {
+    for (const missing of ctx.missingInputs) {
+      const isRequired = contract.requiredInputs.some((r) => r.toLowerCase().includes(missing.toLowerCase()) || missing.toLowerCase().includes(r.toLowerCase()));
+      if (isRequired) {
+        missingRequirements.push(missing);
+        requiredChanges.push(`Provide "${missing}" before delegating to ${agentName}`);
+      }
+    }
+  }
+  if (ctx.approvalRequired && !ctx.approvalGranted) {
+    const needsApproval = contract.escalationConditions.some((c) => c.toLowerCase().includes("approval") || c.toLowerCase().includes("approve"));
+    if (needsApproval) {
+      missingRequirements.push("human approval");
+      riskFlags.push(`Agent "${agentName}" requires approval via escalation condition`);
+      requiredChanges.push("Obtain explicit human approval before proceeding");
+    }
+  }
+  if (agentName === "design" || agentName === "frontend-coder") {
+    const taskLower = (ctx.taskDescription ?? "").toLowerCase();
+    const isUiHeavy = /landing page|dashboard|admin panel|website|web app|ui|ux|interface|frontend|component/.test(taskLower);
+    if (agentName === "frontend-coder" && isUiHeavy && ctx.designApprovalPresent === false) {
+      missingRequirements.push("design handoff approval");
+      riskFlags.push("frontend-coder invoked for UI-heavy task without approved design handoff");
+      requiredChanges.push("Complete design stage and obtain design approval before delegating to frontend-coder");
+    }
+  }
+  const passed = missingRequirements.length === 0 && riskFlags.length === 0;
+  if (passed) {
+    reasons.push(`Agent "${agentName}" passed all policy checks`);
+  }
+  return { passed, reasons, riskFlags, missingRequirements, requiredChanges };
+}
+function computeConfidence(exists, policyResult, ctx) {
+  if (!exists)
+    return 0;
+  if (policyResult.riskFlags.length >= 3)
+    return 0.2;
+  if (policyResult.riskFlags.length === 2)
+    return 0.4;
+  if (policyResult.riskFlags.length === 1)
+    return 0.6;
+  if (policyResult.missingRequirements.length > 0)
+    return 0.5;
+  if (ctx.prerequisitesMet === false)
+    return 0.45;
+  return 0.95;
+}
+function resolveDecision(exists, policyResult, confidenceScore, threshold, ctx) {
+  if (!exists) {
+    return { decision: "block", approvalStatus: "denied" };
+  }
+  if (ctx.approvalRequired && !ctx.approvalGranted) {
+    return { decision: "escalate", approvalStatus: "escalated" };
+  }
+  if (!policyResult.passed) {
+    if (policyResult.requiredChanges.length > 0) {
+      return { decision: "revise", approvalStatus: "pending" };
+    }
+    return { decision: "block", approvalStatus: "denied" };
+  }
+  if (confidenceScore < threshold) {
+    return { decision: "escalate", approvalStatus: "escalated" };
+  }
+  return { decision: "approve", approvalStatus: "approved" };
+}
+function runSupervisorReview(directory, targetName, ctx = {}) {
+  const config = resolveSupervisorConfig(directory);
+  const reviewPhase = ctx.reviewPhase ?? "preflight";
+  const timestamp2 = new Date().toISOString();
+  if (config.reviewedTargets.length > 0 && !config.reviewedTargets.includes(targetName)) {
+    return {
+      decision: "approve",
+      targetType: "agent",
+      targetName,
+      exists: true,
+      reasons: [`Target "${targetName}" is not in the reviewed targets list — auto-approved`],
+      missingRequirements: [],
+      riskFlags: [],
+      requiredChanges: [],
+      approvalStatus: "approved",
+      confidenceScore: 1,
+      reviewPhase,
+      timestamp: timestamp2
+    };
+  }
+  const { exists, type: targetType } = isRegisteredTarget(targetName);
+  if (!exists) {
+    const decision2 = {
+      decision: "block",
+      targetType,
+      targetName,
+      exists: false,
+      reasons: [
+        `Target "${targetName}" is not registered in the FlowDeck command or agent registry.`,
+        "The supervisor does not create new commands or workflows.",
+        "Only registered targets can be executed."
+      ],
+      missingRequirements: [],
+      riskFlags: [`Unregistered target: "${targetName}"`],
+      requiredChanges: [
+        `Use one of the registered commands: ${REGISTERED_COMMANDS.join(", ")}`,
+        `Or use one of the registered agents: ${AGENT_NAMES.join(", ")}`
+      ],
+      approvalStatus: "denied",
+      confidenceScore: 0,
+      reviewPhase,
+      timestamp: timestamp2
+    };
+    _emitTelemetry(directory, decision2, ctx);
+    return decision2;
+  }
+  const policyResult = targetType === "command" ? checkCommandPolicy(targetName, ctx) : checkAgentPolicy(targetName, ctx);
+  const confidenceScore = computeConfidence(exists, policyResult, ctx);
+  const { decision, approvalStatus } = resolveDecision(exists, policyResult, confidenceScore, config.confidenceThreshold, ctx);
+  const reasons = policyResult.reasons.length > 0 ? policyResult.reasons : decision === "approve" ? [`Target "${targetName}" reviewed and approved for execution`] : [`Target "${targetName}" reviewed — decision: ${decision}`];
+  const supervisorDecision = {
+    decision,
+    targetType,
+    targetName,
+    exists,
+    reasons,
+    missingRequirements: policyResult.missingRequirements,
+    riskFlags: policyResult.riskFlags,
+    requiredChanges: policyResult.requiredChanges,
+    approvalStatus,
+    confidenceScore,
+    reviewPhase,
+    timestamp: timestamp2
+  };
+  _emitTelemetry(directory, supervisorDecision, ctx);
+  return supervisorDecision;
+}
+function shouldProceed(decision, mode, canBlock) {
+  if (!decision.exists)
+    return false;
+  if (!canBlock)
+    return true;
+  if (mode === "strict") {
+    return decision.decision === "approve" || decision.decision === "revise";
+  }
+  return decision.decision !== "block" || decision.confidenceScore > 0.3;
+}
+function _emitTelemetry(directory, decision, ctx) {
+  try {
+    appendEvent(directory, {
+      session_id: ctx.session_id ?? "session-0",
+      run_id: ctx.run_id ?? "unknown",
+      event: "supervisor.review",
+      agent: "supervisor",
+      status: decision.decision === "approve" ? "ok" : decision.decision === "block" ? "blocked" : decision.decision === "escalate" ? "approved" : "ok",
+      meta: {
+        targetName: decision.targetName,
+        targetType: decision.targetType,
+        exists: decision.exists,
+        decision: decision.decision,
+        confidenceScore: decision.confidenceScore,
+        riskFlags: decision.riskFlags,
+        missingRequirements: decision.missingRequirements,
+        reviewPhase: decision.reviewPhase
+      }
+    });
+  } catch {}
+}
+
 // src/index.ts
 function loadRulePaths() {
   const __dir = dirname4(fileURLToPath2(import.meta.url));
@@ -6423,7 +7353,7 @@ var plugin = async (input, _options) => {
           const delEvent = event?.event ?? event;
           const sessionId = delEvent?.sessionID ?? delEvent?.sessionId ?? "";
           if (sessionId) {
-            memoryHook.clearSession(sessionId);
+            memoryHook.onSessionEnd(sessionId);
           }
         }
       } catch (err) {
@@ -6452,6 +7382,33 @@ var plugin = async (input, _options) => {
         }
       }
       orchestratorGuard.check(toolInput.sessionID ?? "", toolInput.tool ?? toolInput.name ?? "");
+      const toolName = toolInput.tool ?? toolInput.name ?? "";
+      if (toolName === "delegate" || toolName === "run-pipeline") {
+        const supConfig = resolveSupervisorConfig(directory);
+        if (supConfig.enabled) {
+          const args = toolOutput?.args ?? toolInput?.args ?? {};
+          const agentTarget = typeof args.agent === "string" ? args.agent.replace(/^@/, "") : Array.isArray(args.steps) && args.steps[0]?.agent ? String(args.steps[0].agent).replace(/^@/, "") : "";
+          if (agentTarget) {
+            const decision = runSupervisorReview(directory, agentTarget, {
+              taskDescription: typeof args.prompt === "string" ? args.prompt : undefined,
+              reviewPhase: "preflight",
+              session_id: toolInput.sessionID ?? toolInput.sessionId ?? ""
+            });
+            const proceed = shouldProceed(decision, supConfig.mode, supConfig.canBlock);
+            appLog(`[Supervisor] ${decision.reviewPhase} review of "${decision.targetName}": ` + `decision=${decision.decision} exists=${decision.exists} confidence=${decision.confidenceScore.toFixed(2)} ` + `${decision.riskFlags.length > 0 ? `risks=[${decision.riskFlags.join("; ")}]` : ""}`);
+            if (!proceed) {
+              const summary = [
+                `[Supervisor] Execution blocked for target "${decision.targetName}".`,
+                ...decision.reasons,
+                ...decision.missingRequirements.length > 0 ? [`Missing: ${decision.missingRequirements.join(", ")}`] : [],
+                ...decision.requiredChanges.length > 0 ? [`Required changes: ${decision.requiredChanges.join("; ")}`] : []
+              ].join(`
+`);
+              throw new Error(summary);
+            }
+          }
+        }
+      }
       await telemetryHook({ directory }, toolInput, toolOutput);
       await approvalHook({ directory }, toolInput, toolOutput);
       await guardRailsHook({ directory }, toolInput, toolOutput);
@@ -6469,6 +7426,30 @@ var plugin = async (input, _options) => {
       } catch (err) {
         console.error("[FlowDeck Memory] Tool execution error:", err);
       }
+      const afterToolName = toolInput.tool ?? toolInput.name ?? "";
+      if (afterToolName === "delegate" || afterToolName === "run-pipeline") {
+        try {
+          const supConfig = resolveSupervisorConfig(directory);
+          if (supConfig.enabled && supConfig.postExecutionReview) {
+            const args = toolOutput?.args ?? toolInput?.args ?? {};
+            const agentTarget = typeof args.agent === "string" ? args.agent.replace(/^@/, "") : Array.isArray(args.steps) && args.steps[0]?.agent ? String(args.steps[0].agent).replace(/^@/, "") : "";
+            if (agentTarget) {
+              const executionErrored = toolOutput?.error != null || toolOutput?.status === "error" || typeof toolOutput?.output === "string" && toolOutput.output.startsWith("Error:");
+              const decision = runSupervisorReview(directory, agentTarget, {
+                taskDescription: typeof args.prompt === "string" ? args.prompt : undefined,
+                reviewPhase: "post-stage",
+                session_id: toolInput.sessionID ?? toolInput.sessionId ?? "",
+                prerequisitesMet: !executionErrored
+              });
+              const logLevel = decision.decision === "block" || decision.decision === "escalate" ? "[Supervisor][WARN]" : "[Supervisor]";
+              appLog(`${logLevel} post-stage review of "${decision.targetName}": ` + `decision=${decision.decision} exists=${decision.exists} confidence=${decision.confidenceScore.toFixed(2)} ` + `executionErrored=${executionErrored} ` + `${decision.riskFlags.length > 0 ? `risks=[${decision.riskFlags.join("; ")}]` : ""}`);
+              if (supConfig.mode === "strict" && !shouldProceed(decision, "strict", supConfig.canBlock)) {
+                appLog(`[Supervisor][STRICT] Post-execution governance violation detected for "${decision.targetName}". ` + `Review the scorecard and telemetry for this run. ` + `Reasons: ${decision.reasons.join("; ")}`);
+              }
+            }
+          }
+        } catch {}
+      }
       await contextMonitor["tool.execute.after"](toolInput, toolOutput);
     }
   };