@dv.nghiem/flowdeck 0.3.9 → 0.4.1

package/dist/index.js

@@ -1,6 +1,6 @@
 // src/index.ts
-import { readdirSync as readdirSync3, readFileSync as readFileSync23, existsSync as existsSync27 } from "fs";
-import { join as join26, basename } from "path";
+import { readdirSync as readdirSync3, readFileSync as readFileSync24, existsSync as existsSync26 } from "fs";
+import { join as join25, basename } from "path";
 import { dirname as dirname4 } from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 
@@ -170,7 +170,12 @@ function readPlanningState(dir) {
       last_action: "",
       next_action: "",
       blockers: [],
-      tdd: undefined
+      tdd: undefined,
+      lastUpdatedAt: "",
+      lastUpdatedBy: "",
+      lastUpdatedPhase: 1,
+      summaryVersion: 0,
+      freshnessStatus: "unknown"
     };
   }
   const content = readFileSync2(sp, "utf-8");
@@ -191,7 +196,12 @@ function readPlanningState(dir) {
     last_action: parsed.last_action || "",
     next_action: parsed.next_action || "",
     blockers: parsed.blockers || [],
-    tdd: parseTDDState(parsed)
+    tdd: parseTDDState(parsed),
+    lastUpdatedAt: parsed.lastUpdatedAt || "",
+    lastUpdatedBy: parsed.lastUpdatedBy || "",
+    lastUpdatedPhase: parsed.lastUpdatedPhase || 1,
+    summaryVersion: parsed.summaryVersion || 0,
+    freshnessStatus: parsed.freshnessStatus || "unknown"
   };
 }
 function parseTDDState(parsed) {
@@ -1701,657 +1711,446 @@ var reflectTool = tool15({
   }
 });
 
-// src/tools/memory-search.ts
+// src/tools/codegraph-tool.ts
 import { tool as tool16 } from "@opencode-ai/plugin";
 
-// src/services/memory-store.ts
-import { Database } from "bun:sqlite";
-import { existsSync as existsSync15, mkdirSync as mkdirSync10 } from "fs";
+// src/services/codegraph.ts
+import { spawnSync } from "child_process";
+import { existsSync as existsSync15, readFileSync as readFileSync14, writeFileSync as writeFileSync14, mkdirSync as mkdirSync10 } from "fs";
 import { join as join15 } from "path";
-import { homedir } from "os";
-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) {
-    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,
-      content_session_id TEXT NOT NULL UNIQUE,
-      project TEXT NOT NULL,
-      directory TEXT NOT NULL,
-      created_at TEXT NOT NULL DEFAULT (datetime('now')),
-      last_active_at TEXT NOT NULL DEFAULT (datetime('now')),
-      summary TEXT,
-      prompt_count INTEGER DEFAULT 0
-    );
-
-    CREATE TABLE IF NOT EXISTS observations (
-      id INTEGER PRIMARY KEY AUTOINCREMENT,
-      session_id INTEGER NOT NULL,
-      tool_name TEXT NOT NULL,
-      tool_input TEXT,
-      tool_response TEXT,
-      directory TEXT NOT NULL,
-      created_at TEXT NOT NULL DEFAULT (datetime('now')),
-      FOREIGN KEY (session_id) REFERENCES sessions(id)
-    );
-
-    CREATE TABLE IF NOT EXISTS summaries (
-      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)
-    );
-
-    CREATE INDEX IF NOT EXISTS idx_observations_session ON observations(session_id);
-    CREATE INDEX IF NOT EXISTS idx_observations_directory ON observations(directory);
-    CREATE INDEX IF NOT EXISTS idx_observations_tool ON observations(tool_name);
-    CREATE INDEX IF NOT EXISTS idx_sessions_project ON sessions(project);
-    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);
+var CODEGRAPH_META_FILE = "CODEGRAPH.md";
+var MAX_FRESHNESS_MS = 30 * 60 * 1000;
+function metaPath(dir) {
+  return join15(codebaseDir(dir), CODEGRAPH_META_FILE);
 }
-function sleepSync(ms) {
+function isCodegraphInstalled() {
   try {
-    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+    const result = spawnSync("codegraph", ["--version"], {
+      encoding: "utf-8",
+      timeout: 5000,
+      stdio: "pipe"
+    });
+    return result.status === 0;
   } catch {
-    const end = Date.now() + ms;
-    while (Date.now() < end) {}
+    return false;
   }
 }
-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 isCodegraphIndexed(dir) {
+  return existsSync15(join15(dir, ".codegraph", "codegraph.db"));
 }
-function serializeToolInput(input) {
-  if (!input)
-    return null;
-  try {
-    return JSON.stringify(input);
-  } catch {
-    return String(input);
+function readCodegraphMeta(dir) {
+  const path = metaPath(dir);
+  if (!existsSync15(path)) {
+    return {
+      installed: false,
+      indexed: false,
+      lastIndexedAt: "",
+      lastIndexedRevision: "",
+      lastIndexedBy: "",
+      freshnessStatus: "unknown",
+      installLog: "",
+      indexLog: ""
+    };
   }
-}
-function parseToolInput(input) {
-  if (!input)
-    return null;
   try {
-    return JSON.parse(input);
+    const content = readFileSync14(path, "utf-8");
+    return parseCodegraphMeta(content);
   } catch {
-    return null;
+    return {
+      installed: false,
+      indexed: false,
+      lastIndexedAt: "",
+      lastIndexedRevision: "",
+      lastIndexedBy: "",
+      freshnessStatus: "unknown",
+      installLog: "",
+      indexLog: ""
+    };
   }
 }
-function initSession(contentSessionId, project, directory) {
-  const database = getDb();
-  const now = new Date().toISOString();
-  const existing = database.prepare("SELECT * FROM sessions WHERE content_session_id = ?").get(contentSessionId);
-  if (existing) {
-    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 };
+function parseCodegraphMeta(content) {
+  const result = {};
+  for (const line of content.split(`
+`)) {
+    if (line.startsWith("#") || !line.trim())
+      continue;
+    const stripped = line.replace(/\*\*/g, "");
+    const m = stripped.match(/^([a-zA-Z_][a-zA-Z0-9_]*):\s*(.*)/);
+    if (!m)
+      continue;
+    const key = m[1];
+    const value = m[2].trim().replace(/^["']|["']$/g, "");
+    switch (key) {
+      case "installed":
+        result.installed = value === "true";
+        break;
+      case "indexed":
+        result.indexed = value === "true";
+        break;
+      case "freshnessStatus":
+        result.freshnessStatus = value;
+        break;
+      case "lastIndexedAt":
+        result.lastIndexedAt = value;
+        break;
+      case "lastIndexedRevision":
+        result.lastIndexedRevision = value;
+        break;
+      case "lastIndexedBy":
+        result.lastIndexedBy = value;
+        break;
+      case "installLog":
+        result.installLog = value;
+        break;
+      case "indexLog":
+        result.indexLog = value;
+        break;
+    }
   }
-  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,
-    project,
-    directory,
-    created_at: now,
-    last_active_at: now,
-    prompt_count: 1
-  };
-}
-function storeObservation(sessionId, toolName, toolInput, toolResponse, directory) {
-  const database = getDb();
-  const now = new Date().toISOString();
-  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(serializedInput),
-    tool_response: truncatedResponse,
-    directory,
-    created_at: now
-  };
-}
-function storeSummary(sessionId, content, metadata) {
-  const database = getDb();
-  const now = new Date().toISOString();
-  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,
-    session_id: sessionId,
-    content,
-    metadata: metadata ?? null,
-    created_at: now
-  };
-}
-function getRecentSessions(directory, limit = 5) {
-  const database = getDb();
-  return database.prepare(`SELECT * FROM sessions
-       WHERE directory = ?
-       ORDER BY last_active_at DESC
-       LIMIT ?`).all(directory, limit);
-}
-function getObservationsForSession(sessionId) {
-  const database = getDb();
-  const observations = database.prepare("SELECT * FROM observations WHERE session_id = ? ORDER BY created_at ASC").all(sessionId);
-  return observations.map((obs) => ({
-    ...obs,
-    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
+    installed: result.installed ?? false,
+    indexed: result.indexed ?? false,
+    lastIndexedAt: result.lastIndexedAt ?? "",
+    lastIndexedRevision: result.lastIndexedRevision ?? "",
+    lastIndexedBy: result.lastIndexedBy ?? "",
+    freshnessStatus: result.freshnessStatus ?? "unknown",
+    installLog: result.installLog ?? "",
+    indexLog: result.indexLog ?? ""
   };
 }
-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
-       FROM observations o
-       JOIN sessions s ON o.session_id = s.id
-       WHERE o.directory = ?
-       ORDER BY o.created_at DESC
-       LIMIT ?`).all(directory, limit);
-  return rows.map((row) => ({
-    observation: {
-      ...row,
-      tool_input: parseToolInput(row.tool_input)
-    },
-    session: {
-      content_session_id: row.content_session_id,
-      project: row.project,
-      directory,
-      created_at: row.session_created
-    }
-  }));
-}
-function searchObservations(directory, query, limit = 10) {
-  const database = getDb();
-  const pattern = `%${query}%`;
-  const rows = database.prepare(`SELECT o.*, s.project, s.content_session_id, s.created_at as session_created
-       FROM observations o
-       JOIN sessions s ON o.session_id = s.id
-       WHERE o.directory = ? AND (o.tool_name LIKE ? OR o.tool_input LIKE ? OR o.tool_response LIKE ?)
-       ORDER BY o.created_at DESC
-       LIMIT ?`).all(directory, pattern, pattern, pattern, limit);
-  return rows.map((row) => ({
-    observation: {
-      ...row,
-      tool_input: parseToolInput(row.tool_input)
-    },
-    session: {
-      content_session_id: row.content_session_id,
-      project: row.project,
-      directory,
-      created_at: row.session_created
-    }
-  }));
+function writeCodegraphMeta(dir, meta) {
+  const base = codebaseDir(dir);
+  if (!existsSync15(base))
+    mkdirSync10(base, { recursive: true });
+  const lines = [
+    "# Codegraph Metadata",
+    "",
+    `**installed:** ${meta.installed}`,
+    `**indexed:** ${meta.indexed}`,
+    `**lastIndexedAt:** ${meta.lastIndexedAt}`,
+    `**lastIndexedRevision:** ${meta.lastIndexedRevision}`,
+    `**lastIndexedBy:** ${meta.lastIndexedBy}`,
+    `**freshnessStatus:** ${meta.freshnessStatus}`,
+    `**installLog:** ${meta.installLog}`,
+    `**indexLog:** ${meta.indexLog}`
+  ];
+  writeFileSync14(metaPath(dir), lines.join(`
+`), "utf-8");
+}
+function isCodegraphFresh(dir, maxAgeMs = MAX_FRESHNESS_MS) {
+  const meta = readCodegraphMeta(dir);
+  if (!meta.indexed)
+    return false;
+  if (meta.freshnessStatus === "stale")
+    return false;
+  if (!meta.lastIndexedAt)
+    return false;
+  const age = Date.now() - new Date(meta.lastIndexedAt).getTime();
+  return age < maxAgeMs;
 }
-function getContextForDirectory(directory, maxObservations = 20) {
-  const recentObs = getRecentObservations(directory, maxObservations);
-  if (recentObs.length === 0)
+function getCurrentRevision(dir) {
+  try {
+    const result = spawnSync("git", ["rev-parse", "--short", "HEAD"], {
+      cwd: dir,
+      encoding: "utf-8",
+      timeout: 5000,
+      stdio: "pipe"
+    });
+    return result.status === 0 ? (result.stdout ?? "").trim() : "";
+  } catch {
     return "";
-  const lines = ["## Recent Context"];
-  for (const { observation, session } of recentObs) {
-    const date = observation.created_at ? new Date(observation.created_at).toLocaleDateString() : "unknown";
-    lines.push(`
-### [${date}] ${session.project} - ${observation.tool_name}`);
-    if (observation.tool_input && Object.keys(observation.tool_input).length > 0) {
-      const preview = JSON.stringify(observation.tool_input).slice(0, 200);
-      lines.push(`Input: ${preview}${preview.length >= 200 ? "..." : ""}`);
-    }
-    if (observation.tool_response) {
-      const preview = observation.tool_response.slice(0, 300);
-      lines.push(`Output: ${preview}${observation.tool_response.length > 300 ? "..." : ""}`);
-    }
   }
-  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`);
-    for (const sum of summaries) {
-      const date = sum.created_at ? new Date(sum.created_at).toLocaleDateString() : "unknown";
-      lines.push(`
-### [${date}]`);
-      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({
-  description: "Search FlowDeck memory for past observations, sessions, and context. Use to recall what was worked on previously.",
-  args: {
-    query: tool16.schema.string().optional().describe("Search query for memory (searches tool names, inputs, and outputs)"),
-    session_id: tool16.schema.string().optional().describe("Specific session ID to retrieve observations from"),
-    limit: tool16.schema.number().optional().describe("Maximum number of results (default: 10)")
-  },
-  async execute(args, context) {
-    const directory = context.directory ?? process.cwd();
-    const limit = args.limit ?? 10;
-    if (args.session_id) {
-      const sessions2 = getRecentSessions(directory, 100);
-      const targetSession = sessions2.find((s) => String(s.id) === args.session_id || s.content_session_id === args.session_id);
-      if (!targetSession) {
-        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,
-          tool_response: o.tool_response ? o.tool_response.slice(0, 500) + (o.tool_response.length > 500 ? "..." : "") : null,
-          created_at: o.created_at
-        }))
-      });
-    }
-    if (args.query) {
-      const results = searchObservations(directory, args.query, limit);
-      if (results.length === 0) {
-        return JSON.stringify({ message: `No results found for "${args.query}"`, results: [] });
-      }
-      return JSON.stringify({
-        query: args.query,
-        count: results.length,
-        results: results.map(({ observation, session }) => ({
-          tool_name: observation.tool_name,
-          tool_input: observation.tool_input,
-          tool_response: observation.tool_response ? observation.tool_response.slice(0, 300) + (observation.tool_response.length > 300 ? "..." : "") : null,
-          project: session.project,
-          date: observation.created_at
-        }))
-      });
-    }
-    const sessions = getRecentSessions(directory, limit);
-    if (sessions.length === 0) {
-      return JSON.stringify({ message: "No previous sessions found in this directory", sessions: [] });
-    }
-    return JSON.stringify({
-      message: "Recent sessions",
-      count: sessions.length,
-      sessions: sessions.map((s) => ({
-        id: s.id,
-        content_session_id: s.content_session_id,
-        project: s.project,
-        created_at: s.created_at,
-        last_active_at: s.last_active_at,
-        summary: s.summary
-      }))
+function getChangedFilesSince(dir, revision) {
+  if (!revision)
+    return [];
+  try {
+    const result = spawnSync("git", ["diff", "--name-only", revision, "HEAD"], {
+      cwd: dir,
+      encoding: "utf-8",
+      timeout: 5000,
+      stdio: "pipe"
     });
+    if (result.status !== 0)
+      return [];
+    return (result.stdout ?? "").trim().split(`
+`).filter(Boolean);
+  } catch {
+    return [];
   }
-});
-
-// src/tools/memory-status.ts
-import { tool as tool17 } from "@opencode-ai/plugin";
-import { existsSync as existsSync16 } from "fs";
-import { join as join16 } from "path";
-import { homedir as homedir2 } from "os";
-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) {
-    const directory = context?.directory ?? process.cwd();
-    const dbPath = resolveDbPath();
-    try {
-      const exists = existsSync16(dbPath);
-      if (!exists) {
-        return JSON.stringify({
-          database_exists: false,
-          path: dbPath,
-          status: "NOT_INITIALIZED"
-        }, 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: dbPath
-      }, null, 2);
-    }
-  }
-});
-
-// src/hooks/memory-hook.ts
-var MAX_TOOL_RESPONSE = 1e4;
-var MAX_SUMMARY_STORAGE = 50000;
-var activeSessions = new Map;
-function extractProjectFromDirectory(directory) {
-  const parts = directory.split("/");
-  return parts[parts.length - 1] || "unknown";
-}
-function truncate(str, max) {
-  if (!str || str.length <= 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);
-  activeSessions.set(contentSessionId, {
-    sessionId: session.id,
-    contentSessionId,
-    project,
-    directory
-  });
-  return session;
-}
-function onToolExecuted(contentSessionId, toolName, toolInput, toolResponse, directory) {
-  let ctx = activeSessions.get(contentSessionId);
-  if (!ctx) {
-    const project = extractProjectFromDirectory(directory);
-    const session = initSession(contentSessionId, project, directory);
-    ctx = {
-      sessionId: session.id,
-      contentSessionId,
-      project,
-      directory
+function hasChangedSinceLastIndex(dir) {
+  const meta = readCodegraphMeta(dir);
+  if (!meta.indexed || !meta.lastIndexedRevision)
+    return true;
+  const changed = getChangedFilesSince(dir, meta.lastIndexedRevision);
+  return changed.length > 0;
+}
+function installCodegraph() {
+  if (isCodegraphInstalled()) {
+    return {
+      success: true,
+      alreadyInstalled: true,
+      log: "[codegraph] Already installed — skipping install"
     };
-    activeSessions.set(contentSessionId, ctx);
   }
   try {
-    storeObservation(ctx.sessionId, truncate(toolName, 200), toolInput, toolResponse ? truncate(toolResponse, MAX_TOOL_RESPONSE) : null, directory);
+    const result = spawnSync("npm", ["install", "-g", "@colbymchenry/codegraph"], {
+      encoding: "utf-8",
+      timeout: 120000,
+      stdio: "pipe"
+    });
+    if (result.status === 0) {
+      return {
+        success: true,
+        alreadyInstalled: false,
+        log: `[codegraph] Install succeeded: ${(result.stdout ?? "").trim()}`
+      };
+    }
+    return {
+      success: false,
+      alreadyInstalled: false,
+      log: (result.stdout ?? "").trim(),
+      error: (result.stderr ?? "").trim() || `npm exited with code ${result.status}`
+    };
   } catch (err) {
-    console.warn(`[FlowDeck Memory] Failed to store observation for tool "${toolName}":`, err);
+    return {
+      success: false,
+      alreadyInstalled: false,
+      log: "",
+      error: String(err)
+    };
   }
 }
-function onMessageUpdated(contentSessionId, role, content, directory) {
-  if (role !== "assistant")
-    return;
-  if (!content || !content.trim())
-    return;
-  let ctx = activeSessions.get(contentSessionId);
-  if (!ctx) {
-    const project = extractProjectFromDirectory(directory);
-    const session = initSession(contentSessionId, project, directory);
-    ctx = {
-      sessionId: session.id,
-      contentSessionId,
-      project,
-      directory
+function initCodegraphIndex(dir, agent) {
+  const installResult = installCodegraph();
+  if (!installResult.success) {
+    return {
+      success: false,
+      full: false,
+      log: installResult.log,
+      changedFiles: [],
+      error: `codegraph install failed: ${installResult.error}`
     };
-    activeSessions.set(contentSessionId, ctx);
   }
+  const meta = readCodegraphMeta(dir);
+  const alreadyIndexed = isCodegraphIndexed(dir);
+  const revision = getCurrentRevision(dir);
+  const changedFiles = alreadyIndexed && meta.lastIndexedRevision ? getChangedFilesSince(dir, meta.lastIndexedRevision) : [];
+  const needsFullRebuild = !alreadyIndexed || !meta.indexed;
+  const cmd = needsFullRebuild && !alreadyIndexed ? ["init", "--index"] : ["index", "--force"];
   try {
-    storeObservation(ctx.sessionId, "assistant_message", { role }, truncate(content, MAX_TOOL_RESPONSE), directory);
+    const result = spawnSync("codegraph", cmd, {
+      cwd: dir,
+      encoding: "utf-8",
+      timeout: 300000,
+      stdio: "pipe"
+    });
+    const success = result.status === 0;
+    const log = [
+      `[codegraph] Full index ${success ? "succeeded" : "failed"} (cmd: codegraph ${cmd.join(" ")})`,
+      `[codegraph] Install: ${installResult.alreadyInstalled ? "skipped (already installed)" : "ran successfully"}`,
+      `[codegraph] Revision: ${revision || "(no git)"}`,
+      `[codegraph] Changed files since last index: ${changedFiles.length}`,
+      success ? (result.stdout ?? "").trim() : (result.stderr ?? "").trim()
+    ].filter(Boolean).join(`
+`);
+    const now = new Date().toISOString();
+    writeCodegraphMeta(dir, {
+      installed: true,
+      indexed: success,
+      lastIndexedAt: success ? now : meta.lastIndexedAt,
+      lastIndexedRevision: success ? revision : meta.lastIndexedRevision,
+      lastIndexedBy: agent,
+      freshnessStatus: success ? "fresh" : "stale",
+      installLog: installResult.log,
+      indexLog: log
+    });
+    return { success, full: true, log, changedFiles, error: success ? undefined : (result.stderr ?? "").trim() };
   } catch (err) {
-    console.warn("[FlowDeck Memory] Failed to store assistant message observation:", err);
+    const errMsg = String(err);
+    writeCodegraphMeta(dir, {
+      installed: isCodegraphInstalled(),
+      indexed: false,
+      lastIndexedAt: "",
+      lastIndexedRevision: "",
+      lastIndexedBy: agent,
+      freshnessStatus: "stale",
+      installLog: installResult.log,
+      indexLog: `[codegraph] Index failed: ${errMsg}`
+    });
+    return {
+      success: false,
+      full: true,
+      log: `[codegraph] Index failed: ${errMsg}`,
+      changedFiles,
+      error: errMsg
+    };
   }
 }
-function onSessionCompact(contentSessionId, summary) {
-  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
+function refreshCodegraphIndex(dir, agent) {
+  const installResult = installCodegraph();
+  if (!installResult.success) {
+    return {
+      success: false,
+      full: false,
+      log: installResult.log,
+      changedFiles: [],
+      error: `codegraph install failed: ${installResult.error}`
     };
-    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) {
-  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 (!isCodegraphIndexed(dir)) {
+    return initCodegraphIndex(dir, agent);
   }
-  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);
+  const meta = readCodegraphMeta(dir);
+  const revision = getCurrentRevision(dir);
+  const changedFiles = meta.lastIndexedRevision ? getChangedFilesSince(dir, meta.lastIndexedRevision) : [];
+  try {
+    const result = spawnSync("codegraph", ["sync"], {
+      cwd: dir,
+      encoding: "utf-8",
+      timeout: 120000,
+      stdio: "pipe"
+    });
+    const success = result.status === 0;
+    const log = [
+      `[codegraph] Incremental sync ${success ? "succeeded" : "failed"}`,
+      `[codegraph] Revision: ${revision || "(no git)"}`,
+      `[codegraph] Changed files: ${changedFiles.length}`,
+      success ? (result.stdout ?? "").trim() : (result.stderr ?? "").trim()
+    ].filter(Boolean).join(`
+`);
+    if (!success) {
+      return initCodegraphIndex(dir, agent);
     }
+    const now = new Date().toISOString();
+    writeCodegraphMeta(dir, {
+      installed: true,
+      indexed: true,
+      lastIndexedAt: now,
+      lastIndexedRevision: revision,
+      lastIndexedBy: agent,
+      freshnessStatus: "fresh",
+      installLog: installResult.log,
+      indexLog: log
+    });
+    return { success: true, full: false, log, changedFiles };
+  } catch (err) {
+    return initCodegraphIndex(dir, agent);
   }
-  activeSessions.delete(contentSessionId);
-}
-function getSessionContext(directory, contentSessionId) {
-  const context = getContextForDirectory(directory, 30);
-  const previousSessions = getRecentSessions(directory, 5);
-  return { context, previousSessions };
 }
-function clearSession(contentSessionId) {
-  activeSessions.delete(contentSessionId);
+function markCodegraphStale(dir) {
+  const meta = readCodegraphMeta(dir);
+  writeCodegraphMeta(dir, { ...meta, freshnessStatus: "stale" });
 }
-var memoryHook = {
-  onSessionCreated,
-  onToolExecuted,
-  onMessageUpdated,
-  onSessionCompact,
-  onSessionEnd,
-  getSessionContext,
-  clearSession
-};
+
+// src/tools/codegraph-tool.ts
+var codegraphTool = tool16({
+  description: "Manage codegraph code intelligence layer: detect installation, initialize or refresh the code index, query status. " + "When .codegraph/ exists agents should prefer codegraph MCP tools (codegraph_context, codegraph_explore, codegraph_search, " + "codegraph_callers, codegraph_callees, codegraph_impact, codegraph_trace) over direct file exploration.",
+  args: {
+    action: tool16.schema.enum(["check", "install", "init", "refresh", "status", "mark-stale"]),
+    agent: tool16.schema.string().optional()
+  },
+  async execute(args, context) {
+    const dir = context.directory ?? process.cwd();
+    const agent = args.agent ?? "codegraph-tool";
+    switch (args.action) {
+      case "check": {
+        const installed = isCodegraphInstalled();
+        const indexed = isCodegraphIndexed(dir);
+        const meta = readCodegraphMeta(dir);
+        const fresh = isCodegraphFresh(dir);
+        const changed = hasChangedSinceLastIndex(dir);
+        return JSON.stringify({
+          installed,
+          indexed,
+          fresh,
+          hasChangedSinceLastIndex: changed,
+          lastIndexedAt: meta.lastIndexedAt,
+          lastIndexedRevision: meta.lastIndexedRevision,
+          freshnessStatus: meta.freshnessStatus,
+          recommendation: !installed ? "run action=install then action=init" : !indexed ? "run action=init to build the code index" : !fresh || changed ? "run action=refresh to update the stale index" : "codegraph index is fresh — use codegraph MCP tools directly"
+        });
+      }
+      case "install": {
+        const result = installCodegraph();
+        return JSON.stringify({
+          ...result,
+          note: result.success && !result.alreadyInstalled ? "codegraph installed. Run action=init to build the project index." : result.alreadyInstalled ? "codegraph was already installed." : `Install failed: ${result.error}`
+        });
+      }
+      case "init": {
+        const result = initCodegraphIndex(dir, agent);
+        return JSON.stringify({
+          ...result,
+          note: result.success ? `codegraph index built (${result.full ? "full" : "incremental"}). ` + `codegraph MCP tools are now available for code understanding.` : `codegraph init failed: ${result.error}`
+        });
+      }
+      case "refresh": {
+        const result = refreshCodegraphIndex(dir, agent);
+        return JSON.stringify({
+          ...result,
+          note: result.success ? `codegraph index refreshed. Changed files since last index: ${result.changedFiles.length}` : `codegraph refresh failed: ${result.error}`
+        });
+      }
+      case "status": {
+        const installed = isCodegraphInstalled();
+        const indexed = isCodegraphIndexed(dir);
+        const meta = readCodegraphMeta(dir);
+        const fresh = isCodegraphFresh(dir);
+        return JSON.stringify({
+          installed,
+          indexed,
+          fresh,
+          meta,
+          mcp: {
+            available: installed && indexed,
+            tools: [
+              "codegraph_context",
+              "codegraph_trace",
+              "codegraph_explore",
+              "codegraph_search",
+              "codegraph_callers",
+              "codegraph_callees",
+              "codegraph_impact",
+              "codegraph_node",
+              "codegraph_status",
+              "codegraph_files"
+            ],
+            guidance: installed && indexed ? "Use codegraph MCP tools for code understanding. Prefer over file exploration." : "codegraph not ready. Run action=init first."
+          }
+        });
+      }
+      case "mark-stale": {
+        markCodegraphStale(dir);
+        return JSON.stringify({ success: true, message: "codegraph index marked stale — next init will do a full rebuild" });
+      }
+    }
+  }
+});
 
 // src/hooks/guard-rails.ts
-import { existsSync as existsSync18, readFileSync as readFileSync15 } from "fs";
-import { join as join18 } from "path";
+import { existsSync as existsSync17, readFileSync as readFileSync16 } from "fs";
+import { join as join17 } from "path";
 
 // src/config/loader.ts
-import { existsSync as existsSync17, readFileSync as readFileSync14 } from "fs";
-import { join as join17 } from "path";
-import { homedir as homedir3 } from "os";
+import { existsSync as existsSync16, readFileSync as readFileSync15 } from "fs";
+import { join as join16 } from "path";
+import { homedir } from "os";
 var CONFIG_FILENAME = "flowdeck.json";
 function getGlobalConfigDir() {
-  return process.env.OPENCODE_CONFIG_DIR || (process.env.XDG_CONFIG_HOME ? join17(process.env.XDG_CONFIG_HOME, "opencode") : join17(homedir3(), ".config", "opencode"));
+  return process.env.OPENCODE_CONFIG_DIR || (process.env.XDG_CONFIG_HOME ? join16(process.env.XDG_CONFIG_HOME, "opencode") : join16(homedir(), ".config", "opencode"));
 }
 function loadFlowDeckConfig(directory) {
   const candidates = [];
   if (directory) {
-    candidates.push(join17(directory, ".opencode", CONFIG_FILENAME));
+    candidates.push(join16(directory, ".opencode", CONFIG_FILENAME));
   }
-  candidates.push(join17(getGlobalConfigDir(), CONFIG_FILENAME));
+  candidates.push(join16(getGlobalConfigDir(), CONFIG_FILENAME));
   for (const configPath of candidates) {
-    if (existsSync17(configPath)) {
+    if (existsSync16(configPath)) {
       try {
-        const content = readFileSync14(configPath, "utf-8");
+        const content = readFileSync15(configPath, "utf-8");
         return JSON.parse(content);
       } catch {
         console.warn(`[flowdeck] Failed to load config from ${configPath}`);
@@ -2380,9 +2179,9 @@ var PLANNING_DIR2 = ".planning";
 var CONFIG_FILE = "config.json";
 var STATE_FILE2 = "STATE.md";
 function resolveExecutionMode(configPath, trustScore, volatility) {
-  if (existsSync18(configPath)) {
+  if (existsSync17(configPath)) {
     try {
-      const config = JSON.parse(readFileSync15(configPath, "utf-8"));
+      const config = JSON.parse(readFileSync16(configPath, "utf-8"));
       if (config.execution_mode === "review-only")
         return "review-only";
       if (config.execution_mode === "guarded")
@@ -2436,22 +2235,22 @@ async function guardRailsHook(ctx, input, _output) {
   if (!ENABLED)
     return;
   const dir = ctx.directory;
-  const planningDirPath = join18(dir, PLANNING_DIR2);
+  const planningDirPath = join17(dir, PLANNING_DIR2);
   const codebaseDirectory = codebaseDir(dir);
-  const configPath = join18(planningDirPath, CONFIG_FILE);
-  const statePath2 = join18(planningDirPath, STATE_FILE2);
+  const configPath = join17(planningDirPath, CONFIG_FILE);
+  const statePath2 = join17(planningDirPath, STATE_FILE2);
   const workspaceRoot = findWorkspaceRoot(dir);
   if (workspaceRoot && dir !== workspaceRoot) {
     const config = getWorkspaceConfig(dir);
-    if (config && config.workspace_mode === "shared" && !existsSync18(planningDirPath)) {
+    if (config && config.workspace_mode === "shared" && !existsSync17(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 (!existsSync18(planningDirPath))
+    if (!existsSync17(planningDirPath))
       return;
-    if (!existsSync18(codebaseDirectory)) {
+    if (!existsSync17(codebaseDirectory)) {
       throw new Error(`[flowdeck] WARNING: .codebase/ not found. Run /fd-map-codebase to map the codebase.`);
     }
     const execMode = resolveExecutionMode(configPath, null);
@@ -2507,15 +2306,15 @@ function getDesignGateMessage(dir) {
 }
 function planSuggestsUiHeavy(dir, phase) {
   const planPath = phasePlanPath(dir, phase);
-  if (!existsSync18(planPath))
+  if (!existsSync17(planPath))
     return false;
-  const planContent = readFileSync15(planPath, "utf-8");
+  const planContent = readFileSync16(planPath, "utf-8");
   return isUiHeavyTask(planContent);
 }
 function effectiveSeverity(configPath, statePath2) {
-  if (existsSync18(configPath)) {
+  if (existsSync17(configPath)) {
     try {
-      const configContent = readFileSync15(configPath, "utf-8");
+      const configContent = readFileSync16(configPath, "utf-8");
       const config = JSON.parse(configContent);
       if (config.guard_enforcement === "warn")
         return "warn";
@@ -2531,10 +2330,10 @@ function getEffectiveSeverity(configPath, statePath2) {
   return effectiveSeverity(configPath, statePath2);
 }
 function getPlanConfirmed(statePath2) {
-  if (!existsSync18(statePath2))
+  if (!existsSync17(statePath2))
     return false;
   try {
-    const content = readFileSync15(statePath2, "utf-8");
+    const content = readFileSync16(statePath2, "utf-8");
     const match = content.match(/plan_confirmed:\s*(true|false)/i);
     return match ? match[1].toLowerCase() === "true" : false;
   } catch {
@@ -2542,32 +2341,32 @@ function getPlanConfirmed(statePath2) {
   }
 }
 function getWarningMessage(planningDir2) {
-  if (!existsSync18(join18(planningDir2, STATE_FILE2))) {
-    return "No .planning/ found. Run /fd-new-project first.";
+  if (!existsSync17(join17(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 (!existsSync18(join18(planningDir2, STATE_FILE2))) {
-    return "No .planning/ found. Run /fd-new-project first.";
+  if (!existsSync17(join17(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 existsSync19, readFileSync as readFileSync16 } from "fs";
-import { join as join19 } from "path";
+import { existsSync as existsSync18, readFileSync as readFileSync17 } from "fs";
+import { join as join18 } 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(tool18, args) {
-  const patterns = BLOCKED_PATTERNS[tool18];
+function isBlocked(tool17, args) {
+  const patterns = BLOCKED_PATTERNS[tool17];
   if (!patterns)
     return null;
-  if (tool18 === "bash") {
+  if (tool17 === "bash") {
     const cmd = args.command;
     if (!cmd)
       return null;
@@ -2578,7 +2377,7 @@ function isBlocked(tool18, args) {
     }
     return null;
   }
-  if (tool18 === "read") {
+  if (tool17 === "read") {
     const filePath = args.filePath;
     if (!filePath)
       return null;
@@ -2589,7 +2388,7 @@ function isBlocked(tool18, args) {
     }
     return null;
   }
-  if (tool18 === "write") {
+  if (tool17 === "write") {
     const filePath = args.filePath;
     if (!filePath)
       return null;
@@ -2603,11 +2402,11 @@ function isBlocked(tool18, args) {
   return null;
 }
 function checkArchConstraint(directory, filePath) {
-  const constraintsPath = join19(codebaseDir(directory), "CONSTRAINTS.md");
-  if (!existsSync19(constraintsPath))
+  const constraintsPath = join18(codebaseDir(directory), "CONSTRAINTS.md");
+  if (!existsSync18(constraintsPath))
     return null;
   try {
-    const content = readFileSync16(constraintsPath, "utf-8");
+    const content = readFileSync17(constraintsPath, "utf-8");
     const match = content.match(/## Forbidden Paths\n([\s\S]*?)(?:\n##|$)/);
     if (!match)
       return null;
@@ -2648,9 +2447,9 @@ function isUiDesignApprovalRequired(directory) {
     return !(state.design_stage === "handoff_complete" && state.design_approved);
   }
   const planPath = phasePlanPath(directory, state.phase || 1);
-  if (!existsSync19(planPath))
+  if (!existsSync18(planPath))
     return false;
-  const planContent = readFileSync16(planPath, "utf-8");
+  const planContent = readFileSync17(planPath, "utf-8");
   if (!isUiHeavyTask(planContent))
     return false;
   return !(state.design_stage === "handoff_complete" && state.design_approved);
@@ -2679,19 +2478,18 @@ async function toolGuardHook(ctx, input, output) {
 }
 
 // src/hooks/session-start.ts
-import { existsSync as existsSync20, readFileSync as readFileSync17 } from "fs";
+import { existsSync as existsSync19, readFileSync as readFileSync18 } 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 (!existsSync20(planningDir2)) {
+  if (!existsSync19(planningDir2)) {
     return {
       flowdeck_phase: null,
       flowdeck_status: "no_plan",
-      flowdeck_warning: "Run /fd-new-project or /fd-map-codebase to initialize.",
-      flowdeck_has_codebase: existsSync20(codebaseDirectory),
-      flowdeck_session_context: getContextForDirectory(ctx.directory),
+      flowdeck_warning: "Run /fd-map-codebase to index the codebase, then /fd-new-feature to start a feature.",
+      flowdeck_has_codebase: existsSync19(codebaseDirectory),
       ...workspaceRoot && config?.sub_repos ? {
         flowdeck_workspace_root: workspaceRoot,
         flowdeck_sub_repos: config.sub_repos,
@@ -2702,17 +2500,15 @@ async function sessionStartHook(ctx) {
   }
   try {
     const stateFilePath = statePath(ctx.directory);
-    const content = readFileSync17(stateFilePath, "utf-8");
+    const content = readFileSync18(stateFilePath, "utf-8");
     const state = parseState(content);
     const currentPhase = state["current_phase"] || {};
-    const sessionContext = getContextForDirectory(ctx.directory);
     const result = {
       flowdeck_phase: currentPhase["phase"] ?? null,
       flowdeck_status: currentPhase["status"] ?? null,
       flowdeck_steps_pending: currentPhase["steps_pending"] ?? null,
       flowdeck_last_action: currentPhase["last_action"] ?? null,
-      flowdeck_has_codebase: existsSync20(codebaseDirectory),
-      flowdeck_session_context: sessionContext
+      flowdeck_has_codebase: existsSync19(codebaseDirectory)
     };
     if (workspaceRoot && config?.sub_repos && config.sub_repos.length > 0) {
       result.flowdeck_workspace_root = workspaceRoot;
@@ -2727,8 +2523,7 @@ async function sessionStartHook(ctx) {
       flowdeck_phase: null,
       flowdeck_status: "error",
       flowdeck_warning: "State file unreadable. Continuing without flowdeck context.",
-      flowdeck_has_codebase: existsSync20(codebaseDirectory),
-      flowdeck_session_context: getContextForDirectory(ctx.directory)
+      flowdeck_has_codebase: existsSync19(codebaseDirectory)
     };
     if (workspaceRoot && config?.sub_repos && config.sub_repos.length > 0) {
       result.flowdeck_workspace_root = workspaceRoot;
@@ -2745,16 +2540,22 @@ import { execFile } from "child_process";
 var INTERACTIVE_COMMANDS = new Set([
   "discuss",
   "plan",
-  "review-code",
   "deploy-check",
-  "new-project"
+  "ask",
+  "resume"
 ]);
 var COMPLETION_COMMANDS = new Set([
   "new-feature",
   "fix-bug",
   "write-docs",
-  "checkpoint"
+  "checkpoint",
+  "done",
+  "execute",
+  "verify"
 ]);
+function normalizeCommandName(raw) {
+  return raw.replace(/^\//, "").replace(/^fd-/, "");
+}
 function notify(title, body, level = "info") {
   const platform = process.platform;
   try {
@@ -2786,16 +2587,88 @@ function tryTerminalBell() {
     process.stdout.write("\x07");
   } catch {}
 }
-function notifySessionIdle() {
-  notify("FlowDeck Task Completed", "Agent is idle and waiting for your next instruction", "info");
+
+class NotificationController {
+  pendingCommand = null;
+  lastNotifiedKey = null;
+  notifyFn;
+  log;
+  constructor(notifyFn = notify, log = () => {}) {
+    this.notifyFn = notifyFn;
+    this.log = log;
+  }
+  onCommandExecuted(rawCommand) {
+    const name = normalizeCommandName(rawCommand);
+    if (!INTERACTIVE_COMMANDS.has(name) && !COMPLETION_COMMANDS.has(name)) {
+      this.log(`[notify] command.executed: "${name}" — not a tracked command, skipping`);
+      return;
+    }
+    this.log(`[notify] command.executed: "${name}" recorded as pending`);
+    this.pendingCommand = name;
+    this.lastNotifiedKey = null;
+  }
+  onSessionIdle(hasEdits) {
+    if (this.pendingCommand) {
+      const name = this.pendingCommand;
+      const dedupeKey = `idle:${name}`;
+      if (this.lastNotifiedKey === dedupeKey) {
+        this.log(`[notify] suppressed duplicate: state=session.idle command=${name}`);
+        return;
+      }
+      const reason = INTERACTIVE_COMMANDS.has(name) ? "input_required" : "completed";
+      this.log(`[notify] firing notification: reason=${reason} command=${name} source=session.idle`);
+      if (reason === "input_required") {
+        this.notifyFn(`FlowDeck: /${name}`, "Your input is needed — please check OpenCode", "critical");
+      } else {
+        this.notifyFn(`FlowDeck: /${name} complete`, "Review the output and choose your next step", "info");
+      }
+      this.lastNotifiedKey = dedupeKey;
+      this.pendingCommand = null;
+      return;
+    }
+    if (hasEdits) {
+      const dedupeKey = "idle:generic";
+      if (this.lastNotifiedKey === dedupeKey) {
+        this.log(`[notify] suppressed duplicate: state=session.idle source=generic`);
+        return;
+      }
+      this.log(`[notify] firing notification: reason=completed source=session.idle (generic, has edits)`);
+      this.notifyFn("FlowDeck Task Completed", "Agent is idle and waiting for your next instruction", "info");
+      this.lastNotifiedKey = dedupeKey;
+    } else {
+      this.log(`[notify] session.idle — no pending command, no edits — suppressed`);
+    }
+  }
+  onSessionError(errorMsg) {
+    const snippet = errorMsg.slice(0, 60);
+    const dedupeKey = `error:${snippet}`;
+    if (this.lastNotifiedKey === dedupeKey) {
+      this.log(`[notify] suppressed duplicate: state=session.error`);
+      return;
+    }
+    this.log(`[notify] firing notification: reason=error source=session.error`);
+    this.notifyFn("FlowDeck Error", snippet || "An error occurred", "critical");
+    this.lastNotifiedKey = dedupeKey;
+    this.pendingCommand = null;
+  }
+  reset() {
+    this.pendingCommand = null;
+    this.lastNotifiedKey = null;
+  }
+  getPendingCommand() {
+    return this.pendingCommand;
+  }
+  getLastNotifiedKey() {
+    return this.lastNotifiedKey;
+  }
 }
-function notifyPermissionNeeded(tool18) {
-  notify("FlowDeck Permission Required", `Agent needs approval to use tool: ${tool18}`, "critical");
+function notifyPermissionNeeded(tool17) {
+  notify("FlowDeck Permission Required", `Agent needs approval to use tool: ${tool17}`, "critical");
 }
 
 // src/hooks/patch-trust.ts
-import { existsSync as existsSync21, readFileSync as readFileSync18 } from "fs";
-import { join as join20 } from "path";
+import { existsSync as existsSync20, readFileSync as readFileSync19 } from "fs";
+import { join as join19 } from "path";
 var HIGH_RISK_KEYWORDS = [
   "password",
   "secret",
@@ -2817,11 +2690,11 @@ var HIGH_RISK_KEYWORDS = [
   "privilege"
 ];
 function loadVolatility(directory) {
-  const p = join20(codebaseDir(directory), "VOLATILITY.json");
-  if (!existsSync21(p))
+  const p = join19(codebaseDir(directory), "VOLATILITY.json");
+  if (!existsSync20(p))
     return {};
   try {
-    const data = JSON.parse(readFileSync18(p, "utf-8"));
+    const data = JSON.parse(readFileSync19(p, "utf-8"));
     const map = {};
     for (const entry of data.entries ?? [])
       map[entry.path] = entry.stability;
@@ -2831,11 +2704,11 @@ function loadVolatility(directory) {
   }
 }
 function loadFailedPaths(directory) {
-  const p = join20(codebaseDir(directory), "FAILURES.json");
-  if (!existsSync21(p))
+  const p = join19(codebaseDir(directory), "FAILURES.json");
+  if (!existsSync20(p))
     return [];
   try {
-    const data = JSON.parse(readFileSync18(p, "utf-8"));
+    const data = JSON.parse(readFileSync19(p, "utf-8"));
     return (data.entries ?? []).flatMap((e) => e.affected_paths ?? []);
   } catch {
     return [];
@@ -2900,8 +2773,8 @@ async function patchTrustHook(ctx, input, output) {
 }
 
 // src/hooks/decision-trace-hook.ts
-import { existsSync as existsSync22, mkdirSync as mkdirSync11, appendFileSync as appendFileSync3 } from "fs";
-import { join as join21 } from "path";
+import { existsSync as existsSync21, mkdirSync as mkdirSync11, appendFileSync as appendFileSync3 } from "fs";
+import { join as join20 } from "path";
 async function decisionTraceHook(ctx, input, output) {
   if (input.tool !== "write" && input.tool !== "edit")
     return;
@@ -2910,7 +2783,7 @@ async function decisionTraceHook(ctx, input, output) {
     return;
   const base = codebaseDir(ctx.directory);
   try {
-    if (!existsSync22(base))
+    if (!existsSync21(base))
       mkdirSync11(base, { recursive: true });
     const entry = {
       timestamp: new Date().toISOString(),
@@ -2923,23 +2796,23 @@ async function decisionTraceHook(ctx, input, output) {
       risk_level: "unknown",
       auto_recorded: true
     };
-    appendFileSync3(join21(base, "DECISIONS.jsonl"), JSON.stringify(entry) + `
+    appendFileSync3(join20(base, "DECISIONS.jsonl"), JSON.stringify(entry) + `
 `, "utf-8");
   } catch {}
 }
 
 // src/services/telemetry.ts
-import { existsSync as existsSync23, readFileSync as readFileSync19, appendFileSync as appendFileSync4, mkdirSync as mkdirSync12 } from "fs";
-import { join as join22 } from "path";
+import { existsSync as existsSync22, readFileSync as readFileSync20, appendFileSync as appendFileSync4, mkdirSync as mkdirSync12 } from "fs";
+import { join as join21 } from "path";
 import { randomUUID } from "crypto";
 function telemetryPath(dir) {
-  return join22(codebaseDir(dir), "TELEMETRY.jsonl");
+  return join21(codebaseDir(dir), "TELEMETRY.jsonl");
 }
 function appendEvent(dir, partial) {
   if (process.env.TELEMETRY_ENABLED !== "true")
     return null;
   const cd = codebaseDir(dir);
-  if (!existsSync23(cd))
+  if (!existsSync22(cd))
     mkdirSync12(cd, { recursive: true });
   const event = {
     id: randomUUID(),
@@ -2976,34 +2849,34 @@ function inferStatus(output) {
 }
 async function telemetryHook(context, toolInput, output) {
   const dir = context.directory ?? process.cwd();
-  const tool18 = toolInput.name ?? toolInput.tool ?? "unknown";
+  const tool17 = toolInput.name ?? toolInput.tool ?? "unknown";
   const ids = resolveIds(toolInput);
   appendEvent(dir, {
     session_id: ids.session_id,
     run_id: ids.run_id,
     event: "tool.call",
-    tool: tool18,
+    tool: tool17,
     status: "ok",
     meta: { parameters: output.args ?? {} }
   });
 }
 async function telemetryAfterHook(context, toolInput, output) {
   const dir = context.directory ?? process.cwd();
-  const tool18 = toolInput.name ?? toolInput.tool ?? "unknown";
+  const tool17 = toolInput.name ?? toolInput.tool ?? "unknown";
   const ids = resolveIds(toolInput);
   const status = inferStatus(output);
   appendEvent(dir, {
     session_id: ids.session_id,
     run_id: ids.run_id,
     event: "tool.complete",
-    tool: tool18,
+    tool: tool17,
     status
   });
 }
 
 // src/services/approval-manager.ts
-import { existsSync as existsSync24, readFileSync as readFileSync20, writeFileSync as writeFileSync14, mkdirSync as mkdirSync13 } from "fs";
-import { join as join23 } from "path";
+import { existsSync as existsSync23, readFileSync as readFileSync21, writeFileSync as writeFileSync15, mkdirSync as mkdirSync13 } from "fs";
+import { join as join22 } from "path";
 var APPROVAL_TTL_MS = 30 * 60 * 1000;
 var SENSITIVE_PATTERNS = [
   /auth/i,
@@ -3040,14 +2913,14 @@ function isSensitivePath(filePath) {
   return SENSITIVE_PATTERNS.some((p) => p.test(filePath));
 }
 function approvalsPath(dir) {
-  return join23(codebaseDir(dir), "APPROVALS.json");
+  return join22(codebaseDir(dir), "APPROVALS.json");
 }
 function loadStore2(dir) {
   const p = approvalsPath(dir);
-  if (!existsSync24(p))
+  if (!existsSync23(p))
     return { requests: [] };
   try {
-    return JSON.parse(readFileSync20(p, "utf-8"));
+    return JSON.parse(readFileSync21(p, "utf-8"));
   } catch {
     return { requests: [] };
   }
@@ -3065,8 +2938,8 @@ async function approvalHook(context, toolInput, output) {
   if (!ENABLED2)
     return;
   const dir = context.directory ?? process.cwd();
-  const tool18 = toolInput.name ?? toolInput.tool ?? "";
-  if (!WRITE_TOOLS.has(tool18))
+  const tool17 = toolInput.name ?? toolInput.tool ?? "";
+  if (!WRITE_TOOLS.has(tool17))
     return;
   const args = output.args ?? {};
   const filePath = String(args.path ?? args.file_path ?? args.filename ?? "");
@@ -3081,7 +2954,7 @@ async function approvalHook(context, toolInput, output) {
     session_id: process.env.OPENCODE_SESSION_ID ?? "session-0",
     run_id: process.env.OPENCODE_RUN_ID ?? "run-0",
     event: "approval.request",
-    tool: tool18,
+    tool: tool17,
     status: "blocked",
     files: [filePath],
     meta: { trigger: "sensitive_file", file: filePath }
@@ -3142,8 +3015,8 @@ function createContextWindowMonitorHook() {
 }
 
 // src/hooks/shell-env-hook.ts
-import { existsSync as existsSync25, readFileSync as readFileSync21 } from "fs";
-import { join as join24 } from "path";
+import { existsSync as existsSync24, readFileSync as readFileSync22 } from "fs";
+import { join as join23 } from "path";
 import { createRequire } from "module";
 var _version;
 function getVersion() {
@@ -3179,7 +3052,7 @@ var MARKER_TO_LANG = {
 };
 function detectPackageManager(root) {
   for (const [lockfile, pm] of Object.entries(LOCKFILE_TO_PM)) {
-    if (existsSync25(join24(root, lockfile)))
+    if (existsSync24(join23(root, lockfile)))
       return pm;
   }
   return;
@@ -3188,7 +3061,7 @@ function detectLanguages(root) {
   const langs = [];
   const seen = new Set;
   for (const [marker, lang] of Object.entries(MARKER_TO_LANG)) {
-    if (!seen.has(lang) && existsSync25(join24(root, marker))) {
+    if (!seen.has(lang) && existsSync24(join23(root, marker))) {
       langs.push(lang);
       seen.add(lang);
     }
@@ -3196,11 +3069,11 @@ function detectLanguages(root) {
   return langs;
 }
 function readCurrentPhase(root) {
-  const statePath2 = join24(root, ".planning", "STATE.md");
-  if (!existsSync25(statePath2))
+  const statePath2 = join23(root, ".planning", "STATE.md");
+  if (!existsSync24(statePath2))
     return;
   try {
-    const content = readFileSync21(statePath2, "utf-8");
+    const content = readFileSync22(statePath2, "utf-8");
     const match = content.match(/phase:\s*(\S+)/i);
     return match?.[1];
   } catch {
@@ -3249,8 +3122,15 @@ function createTodoHook(client) {
 // src/hooks/file-tracker.ts
 class SessionFileTracker {
   changes = new Map;
+  onFileChange;
+  setOnFileChange(callback) {
+    this.onFileChange = callback;
+  }
   record(path, type) {
     this.changes.set(path, { path, type });
+    if (this.onFileChange) {
+      this.onFileChange(path, type);
+    }
   }
   getChanges() {
     return [...this.changes.values()];
@@ -3284,7 +3164,6 @@ function createSessionIdleHook(client, tracker) {
       const edited = tracker.getEditedPaths();
       if (edited.length === 0)
         return;
-      notifySessionIdle();
       const summary = `[FlowDeck] Session idle — ${edited.length} file(s) modified this session`;
       await client.app.log({ body: { service: "flowdeck", level: "info", message: summary } }).catch(() => {});
       const preview = edited.slice(0, 10);
@@ -3299,8 +3178,8 @@ function createSessionIdleHook(client, tracker) {
 }
 
 // src/hooks/compaction-hook.ts
-import { existsSync as existsSync26, readFileSync as readFileSync22 } from "fs";
-import { join as join25 } from "path";
+import { existsSync as existsSync25, readFileSync as readFileSync23 } from "fs";
+import { join as join24 } from "path";
 var STRUCTURED_SUMMARY_PROMPT = `
 When summarizing this session, you MUST include the following sections:
 
@@ -3339,11 +3218,11 @@ For each: agent name, status, description, session_id.
 **RESUME, DON'T RESTART.** Use session_id to continue existing sessions.
 `;
 function readPlanningState2(directory) {
-  const statePath2 = join25(directory, ".planning", "STATE.md");
-  if (!existsSync26(statePath2))
+  const statePath2 = join24(directory, ".planning", "STATE.md");
+  if (!existsSync25(statePath2))
     return null;
   try {
-    const content = readFileSync22(statePath2, "utf-8");
+    const content = readFileSync23(statePath2, "utf-8");
     return content.slice(0, 1500);
   } catch {
     return null;
@@ -3360,6 +3239,18 @@ function createCompactionHook(ctx, tracker) {
       sections.push("```");
       sections.push("");
     }
+    const indexPath = join24(ctx.directory, ".planning", "CODEBASE_INDEX.md");
+    let indexSummary = "";
+    if (existsSync25(indexPath)) {
+      try {
+        const indexContent = readFileSync23(indexPath, "utf-8");
+        indexSummary = "\n## Codebase Index\n```\n" + indexContent.slice(0, 800) + "\n```\n";
+      } catch {}
+    }
+    if (indexSummary) {
+      sections.push(indexSummary);
+      sections.push("");
+    }
     const edited = tracker.getEditedPaths();
     if (edited.length > 0) {
       sections.push("## Recently Edited Files");
@@ -3370,12 +3261,6 @@ function createCompactionHook(ctx, tracker) {
         sections.push(`- … and ${edited.length - 20} more`);
       sections.push("");
     }
-    const sessionContext = getContextForDirectory(ctx.directory);
-    if (sessionContext) {
-      sections.push("## Previous Sessions Context");
-      sections.push(sessionContext);
-      sections.push("");
-    }
     output.context.push(sections.join(`
 `));
     output.prompt = STRUCTURED_SUMMARY_PROMPT.trim();
@@ -3587,6 +3472,14 @@ function createFlowDeckMcps() {
       oauth: false
     };
   }
+  if (!disabled.has("codegraph") && isCodegraphInstalled()) {
+    mcps.codegraph = {
+      type: "local",
+      command: "codegraph",
+      args: ["serve", "--mcp"],
+      enabled: true
+    };
+  }
   return mcps;
 }
 
@@ -3624,7 +3517,7 @@ MUST execute at session start:
 3. Check which steps are marked complete
 4. Begin execution from the first incomplete step
 
-If STATE.md does not exist, tell the user: "No STATE.md found. Run \`/fd-new-project\` to initialize."
+If STATE.md does not exist, tell the user: "No STATE.md found. Run \`/fd-map-codebase\` then \`/fd-new-feature\` to start a feature."
 
 ## Phase Gating
 
@@ -3635,6 +3528,30 @@ If the project is in another phase:
 - **plan** phase: "Run \`/fd-plan\` to create the implementation plan first."
 - **review** phase: "Run \`/fd-verify\` to complete the review phase."
 
+## State-First Read Strategy
+
+Before delegating any agent that needs codebase context:
+1. Read \`STATE.md\` — check \`freshnessStatus\` and \`lastUpdatedAt\`
+2. Read \`.planning/CODEBASE_INDEX.md\` — check \`freshnessStatus\`
+3. If \`freshnessStatus === "fresh"\` AND needed files exist in \`fileSnapshots\`:
+   → Use the existing state. Do NOT re-explore the codebase.
+   → Log: "[StateManager] Skipped codebase exploration — state is fresh"
+4. If state is missing, stale, or insufficient:
+   → Delegate to @code-explorer with specific question
+   → After exploration completes, file-tracker auto-publishes to CODEBASE_INDEX.md
+   → Log: "[StateManager] Triggered re-exploration — state was stale"
+
+State becomes **stale** when:
+- \`lastUpdatedAt\` > 5 minutes ago
+- Phase transitions
+- New plan confirmed
+- User runs /fd-checkpoint or /fd-resume
+
+State becomes **fresh** when:
+- Any agent writes to CODEBASE_INDEX.md
+- updatePlanningState() is called
+- file-tracker hook fires after a file edit
+
 ## Step Execution
 
 For each incomplete step in PLAN.md:
@@ -3897,6 +3814,11 @@ var PLANNER_PROMPT = `You create implementation plans that developers can execut
 3. Check for conflicts with existing design decisions
 4. Define new interfaces if needed (before implementation)
 
+### Codebase Context First
+1. Read \`.planning/CODEBASE_INDEX.md\` — check if freshnessStatus is "fresh"
+2. If fresh and needed files are in fileSnapshots, use the existing summaries
+3. Only explore the codebase if the index is missing, stale, or incomplete
+
 ### Step Breakdown
 - Each step maps to a single file or closely related file group
 - Steps are ordered by dependency (foundation first, UI last)
@@ -4958,13 +4880,36 @@ var createDocUpdaterAgent = (model, customPrompt, customAppendPrompt) => {
 // src/agents/mapper.ts
 var MAPPER_PROMPT = `You read source files and produce accurate documentation. You report only what you can verify by reading the code directly.
 
+## CodeGraph-First Policy
+
+Before using grep or reading files, check whether codegraph is available:
+
+Use the \`codegraph\` tool with \`action=check\`. If codegraph is installed and the index is fresh:
+- Use codegraph MCP tools as your primary source of code understanding
+- Log: "codegraph available — using symbol index for mapping"
+
+**Tool selection when codegraph is available:**
+
+| Mapping task | Preferred Tool |
+|-------------|----------------|
+| Map a module / feature area | \`codegraph_context\` |
+| Find exported symbols | \`codegraph_search\` |
+| Read a function's source | \`codegraph_node\` |
+| Survey multiple related symbols | \`codegraph_explore\` |
+| Trace a data flow | \`codegraph_trace\` |
+| List files in an area | \`codegraph_files\` |
+
+The returned source from codegraph is authoritative — do NOT re-open those files unless you need to see something specific codegraph didn't include.
+
+**If codegraph is NOT available:** fall back to direct file reads as below.
+
 ## Factual-Only Constraint
 
 - If you are not certain about something, write: \`UNKNOWN — needs verification\`
 - Never fill gaps with assumptions or what "probably" works
 - Every claim must be traceable to a specific file and line
 
-## Reading Source Files
+## Reading Source Files (fallback when codegraph unavailable)
 
 - Read files directly using file tools — do not rely on memory
 - Note exact file paths for every claim you make
@@ -4995,13 +4940,14 @@ Write only your assigned file. Read existing \`.codebase/\` files before writing
 - Identify runtime, framework, database, testing, and build tools
 
 ### ARCHITECTURE.md
+- Use \`codegraph_context\` on entry points to map the architecture (if codegraph available)
 - Identify major components and their responsibilities
 - Map data flow from input to output
 - Document integration points (external APIs, databases, queues)
 - Draw component diagram in text format
 
 ### CONVENTIONS.md
-- Find actual naming patterns by reading source files
+- Find actual naming patterns by reading source files or using \`codegraph_explore\`
 - Include file:line examples for each pattern
 - Document import style (relative paths? barrel exports? absolute aliases?)
 - Document error handling pattern from real code
@@ -5038,6 +4984,35 @@ var createMapperAgent = (model, customPrompt, customAppendPrompt) => {
 // src/agents/code-explorer.ts
 var CODE_EXPLORER_PROMPT = `You map unfamiliar code before anyone touches it. You are read-only. You report what you find, not what you expect.
 
+## CodeGraph-First Policy
+
+**Before any file exploration, check whether codegraph is available:**
+
+Use the \`codegraph\` tool with \`action=check\`. If codegraph is installed and the index is fresh:
+- Use codegraph MCP tools as your primary source of code understanding
+- This is faster and more accurate than grep + file reads
+- Log: "codegraph available — using code intelligence index"
+
+**Tool selection when codegraph is available:**
+
+| Task | Preferred Tool |
+|------|----------------|
+| Map an area or feature | \`codegraph_context\` |
+| Find a symbol by name | \`codegraph_search\` |
+| Trace a call path | \`codegraph_trace\` |
+| Callers of a function | \`codegraph_callers\` |
+| Callees of a function | \`codegraph_callees\` |
+| Impact before changing | \`codegraph_impact\` |
+| Read symbol source | \`codegraph_node\` |
+| Survey related symbols | \`codegraph_explore\` |
+| List files in an area | \`codegraph_files\` |
+
+The returned source from codegraph is complete and authoritative — treat it as already read. Do NOT re-open those files.
+Reach for grep/Read only to confirm a specific detail codegraph didn't cover.
+
+**If codegraph is NOT available (not installed or not indexed):**
+Fall back to direct file exploration using the process below.
+
 ## Your Outputs
 
 **File structure:**
@@ -5060,7 +5035,7 @@ var CODE_EXPLORER_PROMPT = `You map unfamiliar code before anyone touches it. Yo
 - Error handling approach (throw, return, Result type)
 - Testing patterns (file co-location, separate __tests__, naming)
 
-## Exploration Process
+## Exploration Process (fallback when codegraph unavailable)
 
 1. \`ls -la\` the top-level directory — understand the layout
 2. Read \`package.json\`, \`go.mod\`, \`Cargo.toml\`, or equivalent — identify the tech stack and dependencies
@@ -5071,7 +5046,7 @@ var CODE_EXPLORER_PROMPT = `You map unfamiliar code before anyone touches it. Yo
 4. Trace the most important call path relevant to the current task
 5. Read test files to understand expected behavior
 
-## Quick Commands
+## Quick Commands (fallback)
 
 \`\`\`bash
 # Find all TypeScript files
@@ -5089,6 +5064,7 @@ grep -r "export.*functionName" src/
 
 ## Rules
 
+- **CodeGraph first** — if codegraph index is available, use it before reaching for grep or file reads
 - **Read-only** — never modify files during exploration
 - **State uncertainty** — if you are not sure what something does, say so
 - **Report what you see** — not what you expect or what would make sense
@@ -5099,6 +5075,11 @@ grep -r "export.*functionName" src/
 \`\`\`markdown
 ## Codebase Exploration
 
+### CodeGraph Status
+- installed: yes/no
+- indexed: yes/no
+- used: yes/no (if yes: list tools used)
+
 ### Structure
 \`\`\`
 src/
@@ -5125,6 +5106,18 @@ Request → \`src/routes/users.ts:34\` → \`src/services/user-service.ts:89\`
 - \`src/services/user-service.ts\` — core business logic
 - \`src/db/user-repo.ts\` — data access
 - \`src/types/user.ts\` — data model definition
+
+## After Exploration
+
+After completing your exploration, summarize what you found so it can be recorded:
+
+- **Files explored:** List the paths you actually read or analyzed
+- **CodeGraph tools used:** List any codegraph MCP tools you invoked
+- **Key finding:** One-sentence summary of the most important insight
+- **Ready to proceed:** yes | no — whether you have enough context to continue
+
+This information is used to update the shared CODEBASE_INDEX.md so subsequent
+stages can skip redundant exploration.
 \`\`\``;
 var createCodeExplorerAgent = (model, customPrompt, customAppendPrompt) => {
   const prompt = resolvePrompt(CODE_EXPLORER_PROMPT, customPrompt, customAppendPrompt);
@@ -5454,16 +5447,78 @@ var DISCUSSER_PROMPT = `You extract clear requirements through focused questioni
 
 Load \`.planning/PROJECT.md\` first if it exists. Use existing context to avoid asking about already-decided things.
 
-## Questioning Strategy
+## The RecommendedQuestion Format
+
+Every question you emit to the user MUST be wrapped in a structured recommendation envelope. Never emit a bare question.
+
+Format:
+\`\`\`
+Question:
+<the actual question>
+
+Recommendation:
+<your recommended answer>
+
+Rationale:
+<why this recommendation — ground it in repo evidence: cite specific files,
+ prior decisions, tech stack, or policy rules. Do not make recommendations
+ from thin air if the repo already contains evidence.>
+
+Alternatives:
+<other valid options, one per line (optional)>
+
+Default if no response:
+<what the system does if you receive no reply>
+\`\`\`
+
+## Examples
+
+✅ Good (question with recommendation):
+\`\`\`
+Question:
+Should this task use the design-first workflow?
+
+Recommendation:
+Yes.
+
+Rationale:
+The task description mentions "dashboard" and "UI", which means it is
+UI-heavy. The codebase has a design agent available (see src/agents/).
+The supervisor policy in src/agents/supervisor.ts requires design approval
+for UI-heavy tasks before the execute phase. Starting with design-first
+is the safest and most expedient path.
+
+Alternatives:
+No — skip design and use a lightweight workflow. Faster but riskier for UI work.
+
+Default if no response:
+Proceed with design-first workflow (recommendation applied automatically).
+\`\`\`
+
+❌ Bad (bare question — never do this):
+"What workflow should we use?"
+
+❌ Bad (recommendation without rationale):
+"Should we use TypeScript? Recommendation: Yes. Default: use TypeScript."
+(Every recommendation needs a rationale grounded in evidence.)
+
+## Questioning Rules
 
 - **ONE question per turn** — never ask two questions at once
 - **Follow-up when unclear** — if an answer is ambiguous, ask for clarification before moving on
 - **Targeted focus** — each question uncovers one specific decision
+- **Grounded recommendations** — base recommendations on PROJECT.md goals, prior DISCUSS.md decisions, tech stack, available agents, or explicit policy rules
+- **Skip answerable questions** — if the answer is already in PROJECT.md, STATE.md, or prior DISCUSS.md files, skip the question and record it as suppressed
 
-\`\`\`
-✅ Good: "Should users be able to reset their password via email?"
+## Suppressed Questions
+
+If a question can be answered from exploration evidence, skip it and record it:
 
-❌ Bad: "What authentication features do you need, and how should password reset work, and do you want social login?"
+\`\`\`markdown
+## Suppressed Questions
+
+- "What tech stack?" → answered by: tech stack detection (Node.js/TypeScript from package.json)
+- "Is the project initialised?" → answered by: PROJECT.md exists
 \`\`\`
 
 ## Decision Tracking
@@ -5481,16 +5536,28 @@ D-03: Social login — excluded from MVP scope
 
 ## Conflict Detection
 
-If a new answer conflicts with a previous decision, flag it immediately:
+If a new answer conflicts with a previous decision, flag it immediately with a RecommendedQuestion:
 
 \`\`\`
 CONFLICT: D-04 (users can stay logged in for 30 days) conflicts with D-01 (JWT, stateless).
-Long-lived JWTs create security risks. Options:
-1. Use refresh tokens with short-lived access tokens
-2. Use sessions instead of JWT
-3. Accept the 30-day JWT with a revocation list
 
-Which do you want?
+Question:
+A long-lived JWT creates a security risk. How do you want to handle session persistence?
+
+Recommendation:
+Use refresh tokens with short-lived access tokens.
+
+Rationale:
+D-01 specified JWT (stateless). Refresh tokens preserve statelessness while
+allowing short-lived access tokens that limit exposure window. This is the
+most secure option that satisfies D-01.
+
+Alternatives:
+- Use sessions instead of JWT (conflicts with D-01)
+- Accept 30-day JWT with a revocation list (complex to implement)
+
+Default if no response:
+Use refresh tokens with short-lived access tokens (most secure option).
 \`\`\`
 
 ## Saving Decisions
@@ -5508,6 +5575,18 @@ D-01: [topic] — [choice]
 D-02: [topic] — [choice]
       Rationale: [why]
 
+## Answered Recommendations
+
+RQ-01: [question]
+  Recommendation: [recommended answer]
+  User choice: [what they said]
+  Rationale: [why the system recommended it]
+  Stage: discuss
+
+## Suppressed Questions
+
+- "<question>" → answered by: <evidence source>
+
 ## Open Questions
 - [anything unresolved]
 
@@ -5515,40 +5594,6 @@ D-02: [topic] — [choice]
 - [explicitly excluded items]
 \`\`\`
 
-## Question Bank
-
-Use these question categories to ensure thorough coverage:
-
-**Scope:**
-- What is included in this feature?
-- What is explicitly excluded?
-- What is the MVP vs. nice-to-have?
-
-**Constraints:**
-- Timeline or deadline?
-- Budget or infrastructure limits?
-- Technology constraints (must use X, cannot use Y)?
-
-**Integration:**
-- Does this interact with existing systems?
-- External APIs or services needed?
-
-**User experience:**
-- Walk me through the user flow step by step
-- What happens when something goes wrong?
-
-**Error handling:**
-- What should happen when [specific failure] occurs?
-- Who is notified on failure?
-
-**Performance:**
-- How many users / requests / records expected?
-- Acceptable response time?
-
-**Security:**
-- Who can access this feature?
-- What data is sensitive?
-
 ## Completion Criteria
 
 Discussion is complete when:
@@ -6327,7 +6372,7 @@ You sit above the orchestrator's execution path. Your only job is to inspect an
 
 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-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)
@@ -6919,7 +6964,6 @@ var REGISTERED_COMMANDS = [
   "fd-map-codebase",
   "fd-multi-repo",
   "fd-new-feature",
-  "fd-new-project",
   "fd-plan",
   "fd-quick",
   "fd-reflect",
@@ -6928,7 +6972,8 @@ var REGISTERED_COMMANDS = [
   "fd-suggest",
   "fd-translate-intent",
   "fd-verify",
-  "fd-write-docs"
+  "fd-write-docs",
+  "fd-done"
 ];
 function resolveSupervisorConfig(directory) {
   try {
@@ -7065,12 +7110,12 @@ function computeConfidence(exists, policyResult, ctx) {
     return 0.45;
   return 0.95;
 }
-function resolveDecision(exists, policyResult, confidenceScore, threshold, ctx) {
+function resolveDecision(exists, policyResult, confidenceScore, threshold, ctx, clarificationQuestion) {
   if (!exists) {
     return { decision: "block", approvalStatus: "denied" };
   }
   if (ctx.approvalRequired && !ctx.approvalGranted) {
-    return { decision: "escalate", approvalStatus: "escalated" };
+    return { decision: "escalate", approvalStatus: "escalated", clarificationQuestion };
   }
   if (!policyResult.passed) {
     if (policyResult.requiredChanges.length > 0) {
@@ -7079,11 +7124,11 @@ function resolveDecision(exists, policyResult, confidenceScore, threshold, ctx)
     return { decision: "block", approvalStatus: "denied" };
   }
   if (confidenceScore < threshold) {
-    return { decision: "escalate", approvalStatus: "escalated" };
+    return { decision: "escalate", approvalStatus: "escalated", clarificationQuestion };
   }
   return { decision: "approve", approvalStatus: "approved" };
 }
-function runSupervisorReview(directory, targetName, ctx = {}) {
+function runSupervisorReview(directory, targetName, ctx = {}, clarificationQuestion) {
   const config = resolveSupervisorConfig(directory);
   const reviewPhase = ctx.reviewPhase ?? "preflight";
   const timestamp2 = new Date().toISOString();
@@ -7131,7 +7176,7 @@ function runSupervisorReview(directory, targetName, ctx = {}) {
   }
   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 { decision, approvalStatus, clarificationQuestion: escalationQuestion } = resolveDecision(exists, policyResult, confidenceScore, config.confidenceThreshold, ctx, clarificationQuestion);
   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,
@@ -7145,7 +7190,8 @@ function runSupervisorReview(directory, targetName, ctx = {}) {
     approvalStatus,
     confidenceScore,
     reviewPhase,
-    timestamp: timestamp2
+    timestamp: timestamp2,
+    ...escalationQuestion ? { clarificationQuestion: escalationQuestion } : {}
   };
   _emitTelemetry(directory, supervisorDecision, ctx);
   return supervisorDecision;
@@ -7185,13 +7231,13 @@ function _emitTelemetry(directory, decision, ctx) {
 // src/index.ts
 function loadRulePaths() {
   const __dir = dirname4(fileURLToPath2(import.meta.url));
-  const rulesDir = join26(__dir, "..", "src", "rules");
-  if (!existsSync27(rulesDir))
+  const rulesDir = join25(__dir, "..", "src", "rules");
+  if (!existsSync26(rulesDir))
     return [];
   const paths = [];
   function walk(dir) {
     for (const entry of readdirSync3(dir, { withFileTypes: true })) {
-      const full = join26(dir, entry.name);
+      const full = join25(dir, entry.name);
       if (entry.isDirectory()) {
         walk(full);
       } else if (entry.isFile() && entry.name.endsWith(".md") && entry.name !== "README.md") {
@@ -7204,8 +7250,8 @@ function loadRulePaths() {
 }
 function loadCommands() {
   const __dir = dirname4(fileURLToPath2(import.meta.url));
-  const commandsDir = join26(__dir, "..", "src", "commands");
-  if (!existsSync27(commandsDir))
+  const commandsDir = join25(__dir, "..", "src", "commands");
+  if (!existsSync26(commandsDir))
     return {};
   const commands = {};
   try {
@@ -7213,7 +7259,7 @@ function loadCommands() {
       if (!file.endsWith(".md"))
         continue;
       const name = basename(file, ".md");
-      const raw = readFileSync23(join26(commandsDir, file), "utf-8");
+      const raw = readFileSync24(join25(commandsDir, file), "utf-8");
       let description;
       let template = raw;
       const fmMatch = raw.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/);
@@ -7243,6 +7289,7 @@ var plugin = async (input, _options) => {
   const orchestratorGuard = new OrchestratorGuard;
   const appLog = (msg) => client.app.log({ body: { service: "flowdeck", level: "info", message: msg } }).catch(() => {});
   const autoLearnHook = createAutoLearnHook(client, fileTracker, directory, appLog);
+  const notifCtrl = new NotificationController(undefined, appLog);
   const agentConfigs = getAgentConfigs({});
   const mcps = createFlowDeckMcps();
   return {
@@ -7294,8 +7341,8 @@ var plugin = async (input, _options) => {
           }
         }
       }
-      const skillsDir = join26(dirname4(fileURLToPath2(import.meta.url)), "..", "src", "skills");
-      if (existsSync27(skillsDir)) {
+      const skillsDir = join25(dirname4(fileURLToPath2(import.meta.url)), "..", "src", "skills");
+      if (existsSync26(skillsDir)) {
         const cfgAny = cfg;
         if (!cfgAny.skills || typeof cfgAny.skills !== "object") {
           cfgAny.skills = { paths: [] };
@@ -7336,51 +7383,33 @@ var plugin = async (input, _options) => {
       "context-generator": contextGeneratorTool,
       "create-skill": createSkillTool,
       reflect: reflectTool,
-      "memory-search": memorySearchTool,
-      "memory-status": memoryStatusTool
+      codegraph: codegraphTool
     },
     "shell.env": shellEnvHook,
     "todo.updated": todoHook,
     "file.edited": fileEdited,
     "file.watcher.updated": fileWatcherUpdated,
     "experimental.session.compacting": compactionHook,
+    "command.execute.before": async (_input, _output) => {},
     "permission.ask": async (input2, _output) => {
       notifyPermissionNeeded(input2.title);
     },
     event: async ({ event }) => {
       const type = event?.type ?? "";
-      try {
-        if (type === "session.created" || type === "session.started") {
-          const sessionId = event?.sessionID ?? event?.sessionId ?? "";
-          if (sessionId) {
-            memoryHook.onSessionCreated(directory, sessionId, event?.prompt);
-          }
-          await sessionStartHook({ directory });
-        } else if (type === "message.updated") {
-          const msgEvent = event?.event ?? event;
-          const sessionId = msgEvent?.sessionID ?? msgEvent?.sessionId ?? "";
-          if (sessionId) {
-            memoryHook.onMessageUpdated(sessionId, msgEvent.role, msgEvent.content, directory);
-          }
-        } else if (type === "session.compacted") {
-          const compactEvent = event?.event ?? event;
-          const sessionId = compactEvent?.sessionID ?? compactEvent?.sessionId ?? "";
-          if (sessionId) {
-            memoryHook.onSessionCompact(sessionId, compactEvent.summary ?? "");
-          }
-        } else if (type === "session.deleted") {
-          const delEvent = event?.event ?? event;
-          const sessionId = delEvent?.sessionID ?? delEvent?.sessionId ?? "";
-          if (sessionId) {
-            memoryHook.onSessionEnd(sessionId);
-          }
+      if (type === "session.created" || type === "session.started") {
+        await sessionStartHook({ directory });
+      }
+      if (type === "command.executed") {
+        const commandName = event?.properties?.name ?? "";
+        if (commandName) {
+          notifCtrl.onCommandExecuted(commandName);
         }
-      } catch (err) {
-        console.error("[FlowDeck Memory] Event handler error:", err);
       }
       await contextMonitor.event({ event });
       orchestratorGuard.onEvent(event);
       if (type === "session.idle") {
+        const hasEdits = fileTracker.getEditedPaths().length > 0;
+        notifCtrl.onSessionIdle(hasEdits);
         try {
           await sessionIdleHook();
           await autoLearnHook();
@@ -7388,6 +7417,11 @@ var plugin = async (input, _options) => {
           fileTracker.clear();
         }
       }
+      if (type === "session.error") {
+        const err = event?.properties?.error;
+        const errorMsg = (err && typeof err === "object" && "message" in err ? String(err.message) : undefined) ?? (typeof err === "string" ? err : undefined) ?? "An unexpected error occurred";
+        notifCtrl.onSessionError(errorMsg);
+      }
     },
     "tool.execute.before": async (toolInput, toolOutput) => {
       if ((toolInput.tool === "read" || toolInput.tool === "view") && toolOutput?.args) {
@@ -7437,14 +7471,6 @@ var plugin = async (input, _options) => {
     },
     "tool.execute.after": async (toolInput, toolOutput) => {
       await telemetryAfterHook({ directory }, toolInput, toolOutput);
-      try {
-        const sessionId = toolInput?.sessionID ?? toolInput?.sessionId ?? "";
-        if (sessionId && toolInput?.tool) {
-          memoryHook.onToolExecuted(sessionId, toolInput.tool, toolInput, toolOutput?.output ?? null, directory);
-        }
-      } catch (err) {
-        console.error("[FlowDeck Memory] Tool execution error:", err);
-      }
       const afterToolName = toolInput.tool ?? toolInput.name ?? "";
       if (afterToolName === "delegate" || afterToolName === "run-pipeline") {
         try {