jfl 0.9.1 → 0.9.3

package/packages/pi/extensions/hud-tool.ts

@@ -1,105 +1,250 @@
 /**
  * HUD Tool Extension
  *
- * Registers jfl_hud tool and /hud command with custom TUI rendering.
- * Shows a themed, collapsible dashboard in the tool output.
- * Updates the aboveEditor widget after each agent turn.
+ * Registers jfl_hud tool and /hud command with a real project dashboard.
+ * Shows: system health, recent work, eval scores, branch, phase.
+ * Fast — reads local files, one hub health check, no heavy API calls.
  *
- * @purpose jfl_hud tool + /hud command + themed widget + custom rendering
+ * @purpose jfl_hud tool + /hud command — real dashboard, not a stub
  */
 
-import { existsSync, readFileSync } from "fs"
+import { existsSync, readFileSync, readdirSync } from "fs"
 import { join } from "path"
 import { execSync } from "child_process"
 import type { PiContext, PiTheme } from "./types.js"
 import { hudRenderCall, hudRenderResult } from "./tool-renderers.js"
 
-function clipLine(text: string, maxW: number): string {
-  const stripped = text.replace(/\x1b\[[0-9;]*m/g, "")
-  if (stripped.length <= maxW) return text
-  return text.slice(0, maxW - 1) + "…"
+let projectRoot = ""
+
+// ─── Data gathering (all fast, local reads) ─────────────────────────────────
+
+function getConfig(root: string): { name: string; type: string } {
+  const configPath = join(root, ".jfl", "config.json")
+  let name = root.split("/").pop() ?? "JFL"
+  let type = "gtm"
+  if (existsSync(configPath)) {
+    try {
+      const c = JSON.parse(readFileSync(configPath, "utf-8"))
+      if (c.name) name = c.name
+      if (c.type) type = c.type
+    } catch {}
+  }
+  return { name, type }
 }
 
-let projectRoot = ""
+function getBranch(root: string): string {
+  try {
+    return execSync("git branch --show-current", { cwd: root, timeout: 2000, stdio: ["pipe", "pipe", "ignore"] }).toString().trim()
+  } catch { return "unknown" }
+}
 
 function getDaysToLaunch(root: string): string | null {
   const roadmapPath = join(root, "knowledge", "ROADMAP.md")
   if (!existsSync(roadmapPath)) return null
+  try {
+    const content = readFileSync(roadmapPath, "utf-8")
+    const dateMatch = content.match(/(\d{4}-\d{2}-\d{2})/m)
+    if (!dateMatch) return null
+    const diff = Math.ceil((new Date(dateMatch[1]).getTime() - Date.now()) / 86400000)
+    return diff > 0 ? `${diff}d to launch` : `${Math.abs(diff)}d past launch`
+  } catch { return null }
+}
 
-  const content = readFileSync(roadmapPath, "utf-8")
-  const dateMatch = content.match(/(\d{4}-\d{2}-\d{2})/m)
-  if (!dateMatch) return null
+function getPhase(root: string): string {
+  const roadmapPath = join(root, "knowledge", "ROADMAP.md")
+  if (!existsSync(roadmapPath)) return ""
+  try {
+    const content = readFileSync(roadmapPath, "utf-8")
+    const match = content.match(/## (?:Phase|Current Phase)[:\t ]*([^\n]+)/i)
+    if (match && match[1].trim() && !match[1].trim().startsWith("```")) return match[1].trim()
+  } catch {}
+  return ""
+}
 
-  const launchDate = new Date(dateMatch[1])
-  const now = new Date()
-  const diff = Math.ceil((launchDate.getTime() - now.getTime()) / 86400000)
-  return diff > 0 ? `${diff}d to launch` : `${Math.abs(diff)}d past launch`
+interface JournalEntry {
+  title: string
+  type: string
+  ts: string
+  status?: string
 }
 
-function getProjectPhase(root: string): string {
-  const roadmapPath = join(root, "knowledge", "ROADMAP.md")
-  if (!existsSync(roadmapPath)) return "unknown"
+function getRecentJournal(root: string, count: number = 5): JournalEntry[] {
+  const journalDir = join(root, ".jfl", "journal")
+  if (!existsSync(journalDir)) return []
 
-  const content = readFileSync(roadmapPath, "utf-8")
-  const sameLineMatch = content.match(/## (?:Phase|Current Phase)[:\t ]*([^\n]+)/i)
-  if (sameLineMatch && sameLineMatch[1].trim() && !sameLineMatch[1].trim().startsWith("```")) {
-    return sameLineMatch[1].trim()
-  }
+  try {
+    const files = readdirSync(journalDir).filter(f => f.endsWith(".jsonl")).sort()
+    const entries: JournalEntry[] = []
 
-  const sectionMatch = content.match(/## (?:Phase|Current Phase)[^\n]*\n+([^\n]+)/i)
-  if (sectionMatch) {
-    let line = sectionMatch[1].trim()
-    if (line.startsWith("```")) return "unknown"
-    line = line.replace(/^[`*_[\]]+|[`*_[\]]+$/g, "")
-    return line || "unknown"
-  }
+    // Read from newest files first
+    for (let i = files.length - 1; i >= 0 && entries.length < count * 2; i--) {
+      try {
+        const lines = readFileSync(join(journalDir, files[i]), "utf-8").trim().split("\n").filter(Boolean)
+        for (let j = lines.length - 1; j >= 0 && entries.length < count * 2; j--) {
+          try {
+            const e = JSON.parse(lines[j])
+            if (e.title && e.type !== "pivot") {
+              entries.push({ title: e.title, type: e.type ?? "note", ts: e.ts ?? "", status: e.status })
+            }
+          } catch {}
+        }
+      } catch {}
+    }
+
+    return entries.slice(0, count)
+  } catch { return [] }
+}
+
+function getJournalStats(root: string): { files: number; entries: number } {
+  const journalDir = join(root, ".jfl", "journal")
+  if (!existsSync(journalDir)) return { files: 0, entries: 0 }
+  try {
+    const files = readdirSync(journalDir).filter(f => f.endsWith(".jsonl"))
+    let entries = 0
+    for (const f of files) {
+      try {
+        entries += readFileSync(join(journalDir, f), "utf-8").trim().split("\n").filter(Boolean).length
+      } catch {}
+    }
+    return { files: files.length, entries }
+  } catch { return { files: 0, entries: 0 } }
+}
+
+interface SystemHealth {
+  hub: "up" | "down"
+  hubPort: number
+  autoCommit: boolean
+  watchdog: boolean
+}
+
+function checkSystemHealth(root: string): SystemHealth {
+  const portFile = join(root, ".jfl", "context-hub.port")
+  const port = existsSync(portFile)
+    ? parseInt(readFileSync(portFile, "utf-8").trim()) || 4360
+    : 4360
 
-  return "unknown"
+  let hubUp: "up" | "down" = "down"
+  try {
+    const resp = execSync(`curl -sf http://localhost:${port}/health`, { timeout: 2000, stdio: ["pipe", "pipe", "ignore"] }).toString()
+    if (resp.includes("ok")) hubUp = "up"
+  } catch {}
+
+  let autoCommit = false
+  try {
+    const ps = execSync("ps aux", { timeout: 2000, encoding: "utf-8", stdio: ["pipe", "pipe", "ignore"] })
+    autoCommit = ps.includes("auto-commit.sh")
+  } catch {}
+
+  let watchdog = false
+  try {
+    const pidFile = join(root, ".jfl", "hub-watchdog.pid")
+    if (existsSync(pidFile)) {
+      const pid = readFileSync(pidFile, "utf-8").trim()
+      execSync(`kill -0 ${pid}`, { stdio: "ignore" })
+      watchdog = true
+    }
+  } catch {}
+
+  return { hub: hubUp, hubPort: port, autoCommit, watchdog }
 }
 
-function getLastJournalTitle(root: string): string | null {
+function getEvalSummary(root: string): string | null {
+  const evalPath = join(root, ".jfl", "eval.jsonl")
+  if (!existsSync(evalPath)) return null
   try {
-    const journalDir = join(root, ".jfl", "journal")
-    if (!existsSync(journalDir)) return null
-    const files = execSync(`ls -t "${journalDir}"/*.jsonl 2>/dev/null | head -1`, {
-      cwd: root, timeout: 3000, encoding: "utf-8",
-    }).trim()
-    if (!files) return null
-    const content = readFileSync(files, "utf-8").trim()
-    const lastLine = content.split("\n").pop()
-    if (!lastLine) return null
-    const entry = JSON.parse(lastLine)
-    return entry.title ?? null
+    const lines = readFileSync(evalPath, "utf-8").trim().split("\n").filter(Boolean)
+    if (lines.length === 0) return null
+    // Scan backwards for most recent entry with a composite/score
+    for (let i = lines.length - 1; i >= Math.max(0, lines.length - 20); i--) {
+      try {
+        const entry = JSON.parse(lines[i])
+        const score = entry.composite ?? entry.score ?? null
+        if (score !== null && score !== undefined) {
+          const tests = entry.metrics?.tests_passed !== undefined
+            ? `${entry.metrics.tests_passed}/${entry.metrics.tests_total} tests`
+            : ""
+          return `${Number(score).toFixed(2)}${tests ? ` (${tests})` : ""}`
+        }
+      } catch {}
+    }
+    return null
   } catch { return null }
 }
 
-function buildHudLines(root: string): string[] {
-  const configPath = join(root, ".jfl", "config.json")
-  let projectName = root.split("/").pop() ?? "JFL"
-  let projectType = "gtm"
+function getTrainingStats(root: string): string | null {
+  const bufferPath = join(root, ".jfl", "training-buffer.jsonl")
+  if (!existsSync(bufferPath)) return null
+  try {
+    const lines = readFileSync(bufferPath, "utf-8").trim().split("\n").filter(Boolean).length
+    return `${lines} tuples`
+  } catch { return null }
+}
 
-  if (existsSync(configPath)) {
-    try {
-      const config = JSON.parse(readFileSync(configPath, "utf-8")) as { name?: string; type?: string }
-      if (config.name) projectName = config.name
-      if (config.type) projectType = config.type
-    } catch {}
-  }
+// ─── Build the dashboard ────────────────────────────────────────────────────
 
+function buildHud(root: string): string {
+  const config = getConfig(root)
+  const branch = getBranch(root)
+  const phase = getPhase(root)
   const days = getDaysToLaunch(root)
-  const phase = getProjectPhase(root)
-  const lastWork = getLastJournalTitle(root)
+  const health = checkSystemHealth(root)
+  const journalStats = getJournalStats(root)
+  const recentWork = getRecentJournal(root, 5)
+  const evalScore = getEvalSummary(root)
+  const trainingStats = getTrainingStats(root)
+
+  const lines: string[] = []
 
-  const lines = [
-    `◆ ${projectName}`,
-    phase !== "unknown" ? `  ${phase}` : "",
-    days ? `  ${days}` : "",
-    lastWork ? `  Last: ${lastWork.slice(0, 60)}` : "",
-  ].filter(Boolean)
+  // Header
+  lines.push(`◆ ${config.name}`)
+  lines.push(`  Branch: ${branch}`)
+  if (phase) lines.push(`  Phase: ${phase}`)
+  if (days) lines.push(`  ${days}`)
+  lines.push("")
 
-  return lines
+  // System health
+  const hubIcon = health.hub === "up" ? "✓" : "✗"
+  const acIcon = health.autoCommit ? "✓" : "–"
+  const wdIcon = health.watchdog ? "✓" : "–"
+  lines.push(`  Systems`)
+  lines.push(`    ${hubIcon} Hub (:${health.hubPort})  ${acIcon} Auto-commit  ${wdIcon} Watchdog`)
+  if (evalScore) lines.push(`    Eval: ${evalScore}`)
+  if (trainingStats) lines.push(`    Training: ${trainingStats}`)
+  lines.push(`    Journal: ${journalStats.entries} entries across ${journalStats.files} sessions`)
+  lines.push("")
+
+  // Recent work
+  if (recentWork.length > 0) {
+    lines.push("  Recent")
+    for (const entry of recentWork) {
+      const typeTag = `[${entry.type}]`.padEnd(12)
+      const title = entry.title.length > 70 ? entry.title.slice(0, 67) + "…" : entry.title
+      lines.push(`    ${typeTag} ${title}`)
+    }
+  }
+
+  return lines.join("\n")
+}
+
+// Also export a one-line version for the steer message
+function buildHudCompact(root: string): string {
+  const config = getConfig(root)
+  const health = checkSystemHealth(root)
+  const journalStats = getJournalStats(root)
+  const recentWork = getRecentJournal(root, 1)
+  const evalScore = getEvalSummary(root)
+
+  const parts = [`◆ ${config.name}`]
+  parts.push(`Hub ${health.hub === "up" ? "✓" : "✗"}`)
+  if (evalScore) parts.push(`Eval ${evalScore}`)
+  parts.push(`${journalStats.entries} journal entries`)
+  if (recentWork.length > 0) parts.push(`Last: ${recentWork[0].title.slice(0, 50)}`)
+
+  return parts.join(" | ")
 }
 
+// ─── Tool + Command registration ───────────────────────────────────────────
+
 export function setupHudTool(ctx: PiContext): void {
   projectRoot = ctx.session.projectRoot
 
@@ -112,7 +257,7 @@ export function setupHudTool(ctx: PiContext): void {
       properties: {},
     },
     async handler() {
-      return buildHudLines(projectRoot).join("\n")
+      return buildHud(projectRoot)
     },
     renderCall: hudRenderCall,
     renderResult: hudRenderResult,
@@ -121,13 +266,29 @@ export function setupHudTool(ctx: PiContext): void {
   ctx.registerCommand({
     name: "hud",
     description: "Show project dashboard",
-    async handler(_args, ctx) {
-      const lines = buildHudLines(projectRoot)
-      ctx.ui.notify(lines.join("\n"), { level: "info" })
+    async handler(_args, _cmdCtx) {
+      const output = buildHud(projectRoot)
+      ctx.ui.notify(output, { level: "info" })
     },
   })
 }
 
+/** Build HUD output for embedding in session init steer message */
+export function getHudForSteer(): string {
+  if (!projectRoot) return ""
+  try {
+    return buildHud(projectRoot)
+  } catch { return "" }
+}
+
+/** Compact HUD for status bars / footers */
+export function getHudCompact(): string {
+  if (!projectRoot) return ""
+  try {
+    return buildHudCompact(projectRoot)
+  } catch { return "" }
+}
+
 export async function updateHudWidget(_ctx: PiContext): Promise<void> {
-  // Widget rendering moved to subway extension
+  // Widget rendering handled by subway-mesh.ts
 }

package/packages/pi/extensions/index.ts

@@ -13,12 +13,12 @@ import { readFileSync, existsSync } from "fs"
 import { join } from "path"
 import { execSync } from "child_process"
 import type { PiContext, JflConfig, JflToolDef, JflCommandDef, PiTheme } from "./types.js"
-import { setupSession, onShutdown } from "./session.js"
+import { setupSession, onShutdown, getSessionBranch } from "./session.js"
 import { setupContext, injectContext } from "./context.js"
-import { setupJournal, checkJournalBeforeCompact, onJournalAgentEnd, onToolExecutionEnd } from "./journal.js"
+import { setupJournal, checkJournalBeforeCompact, onJournalAgentEnd, onToolExecutionEnd, checkPurposeHeader, hasJournalEntryForSession } from "./journal.js"
 import { setupMapBridge, onMapBridgeShutdown, onMapToolEnd } from "./map-bridge.js"
 import { setupEval, onAgentEnd as onEvalEnd } from "./eval.js"
-import { setupHudTool, updateHudWidget } from "./hud-tool.js"
+import { setupHudTool, updateHudWidget, getHudForSteer } from "./hud-tool.js"
 import { setupCrmTool } from "./crm-tool.js"
 import { setupMemoryTool } from "./memory-tool.js"
 import { setupSynopsisTool } from "./synopsis-tool.js"
@@ -38,6 +38,9 @@ import { setupFooter } from "./footer.js"
 import { setupShortcuts } from "./shortcuts.js"
 import { setupNotifications } from "./notifications.js"
 import { setupBookmarks } from "./bookmarks.js"
+import { setupSubwayMesh, injectMeshContext, onMeshShutdown } from "./subway-mesh.js"
+import { fireStartupBriefing } from "./startup-briefing.js"
+import { setupHeader, setHeaderHubStatus, setHeaderAutoCommit, setHeaderBranch, refreshHeaderData } from "./header.js"
 import { setupOnboarding as setupOnboardingV1 } from "./onboarding-v1.js"
 import { setupOnboarding as setupOnboardingV2 } from "./onboarding-v2.js"
 import { setupOnboarding as setupOnboardingV3 } from "./onboarding-v3.js"
@@ -119,11 +122,13 @@ export default async function jflExtension(pi: any): Promise<void> {
       return {
         projectRoot: projectCwd,
         id: pi.getSessionName?.() ?? "jfl",
-        branch: getCurrentBranch(projectCwd),
+        branch: getSessionBranch() || getCurrentBranch(projectCwd),
       }
     },
 
     log: (msg: string, level?: string) => {
+      // Only show debug messages if JFL_DEBUG is set
+      if (level === "debug" && !process.env.JFL_DEBUG) return
       const prefix = level === "debug" ? "[JFL debug]" : "[JFL]"
       console.log(`${prefix} ${msg}`)
     },
@@ -233,6 +238,10 @@ export default async function jflExtension(pi: any): Promise<void> {
         if (latestPiCtx?.ui?.setFooter) latestPiCtx.ui.setFooter(factory)
       },
 
+      setHeader: (factory: any) => {
+        if (latestPiCtx?.ui?.setHeader) latestPiCtx.ui.setHeader(factory)
+      },
+
       setEditorText: (text: string) => {
         if (latestPiCtx?.ui?.setEditorText) latestPiCtx.ui.setEditorText(text)
       },
@@ -305,10 +314,18 @@ export default async function jflExtension(pi: any): Promise<void> {
 
     pi.setSessionName(`JFL: ${projectName}`)
 
-    const setupWork = async () => {
+    // ─── Header first — replace Pi's default before anything renders ──
+    setupHeader(ctx, config)
+
+    // ─── Hub first, then animation + tools in parallel ─────────────
+    // Hub must be up before onboarding probes fire.
+    // setupContext starts hub + registers jfl_context tool.
+    await setupContext(ctx, config)
+
+    // Now hub is up — run animation + remaining setup in parallel
+    const doSetup = async () => {
       await setupMapBridge(ctx, config)
       await setupSession(ctx, config)
-      await setupContext(ctx, config)
       await setupJournal(ctx, config)
       await setupEval(ctx, config)
 
@@ -324,6 +341,8 @@ export default async function jflExtension(pi: any): Promise<void> {
       await setupServiceSkills(ctx, config)
       await setupHubTools(ctx, config)
 
+      await setupSubwayMesh(ctx, config)
+
       initStratusBridge(projectCwd)
       initAgentNames(projectCwd)
       await setupPeterParker(ctx, config)
@@ -339,41 +358,21 @@ export default async function jflExtension(pi: any): Promise<void> {
     const onboard = config.pi?.disable_onboarding ? null : selectOnboarding(config)
     await Promise.all([
       onboard ? onboard(ctx, config).catch(() => {}) : Promise.resolve(),
-      setupWork(),
+      doSetup(),
     ])
 
     ctx.log(`JFL: ${projectName} — session ready`)
 
-    if (config.pi?.auto_start !== false && pi.sendMessage) {
-      setTimeout(() => {
-        pi.sendMessage({
-          customType: "jfl-session-init",
-          content: [
-            `JFL session ready: "${projectName}" on branch ${ctx.session.branch}.`,
-            "",
-            "Your system prompt already contains full project context: CLAUDE.md, recent journal entries, knowledge docs, and code headers.",
-            "Everything was loaded during the boot screen. You do NOT need to call any tools.",
-            "",
-            "DO NOT call jfl_context, jfl_hud, jfl_memory_search, or run any bash commands at startup.",
-            "DO NOT run session-sync.sh, jfl-doctor.sh, or read journal files.",
-            "All of that is already done and injected into your system prompt.",
-            "",
-            "Just greet the user naturally with a brief status (3-5 lines):",
-            "- What was worked on recently (from the journal entries in your system prompt)",
-            "- Current phase and any blockers",
-            "- A suggested next action",
-            "",
-            "No tool calls. No setup noise. Just talk.",
-            "Write journal entries as you work. Capture decisions immediately.",
-          ].join("\n"),
-          display: false,
-        }, { triggerTurn: true, deliverAs: "steer" })
-      }, 500)
+    // Fire startup briefing — gathers synopsis, PRs, team activity, next actions
+    // and steers the model to produce a concise "here's where things stand" greeting
+    if (config.pi?.auto_start !== false) {
+      await fireStartupBriefing(ctx, config)
     }
   })
 
   pi.on("session_shutdown", async (_event: unknown, piCtx: any) => {
     latestPiCtx = piCtx
+    onMeshShutdown()
     await onPortfolioShutdown(ctx)
     await onShutdown(ctx)
     await onMapBridgeShutdown(ctx)
@@ -384,39 +383,20 @@ export default async function jflExtension(pi: any): Promise<void> {
     return checkJournalBeforeCompact(ctx)
   })
 
-  pi.on("before_agent_start", async (event: any, piCtx: any) => {
-    latestPiCtx = piCtx
+  pi.on("before_agent_start", async (event: any, _piCtx: any) => {
     const result = await injectContext(ctx, event)
-    if (result?.systemPromptAddition) {
-      let current = piCtx.getSystemPrompt?.() ?? ""
-
-      // Strip Path B (Claude Code manual startup) from system prompt.
-      // We're running in Pi with the extension — Path B instructions are
-      // noise that can confuse the LLM into running manual startup commands.
-      const pathBStart = "### Path B: Claude Code / No Extension"
-      const pathBEnd = "### How to Tell Which Path You're On"
-      const startIdx = current.indexOf(pathBStart)
-      const endIdx = current.indexOf(pathBEnd)
-      if (startIdx !== -1 && endIdx !== -1 && endIdx > startIdx) {
-        current = current.slice(0, startIdx) + current.slice(endIdx)
-      }
-
-      // Also strip the "How to Tell" section — it references Path B
-      const howToTell = "### How to Tell Which Path You're On"
-      const howToTellIdx = current.indexOf(howToTell)
-      if (howToTellIdx !== -1) {
-        // Find the next ### or ## heading after it
-        const afterHowToTell = current.slice(howToTellIdx + howToTell.length)
-        const nextHeading = afterHowToTell.search(/\n###? /)
-        if (nextHeading !== -1) {
-          current = current.slice(0, howToTellIdx) + afterHowToTell.slice(nextHeading)
-        }
-      }
-
+    const meshState = injectMeshContext()
+    const additions = [
+      result?.systemPromptAddition,
+      meshState,
+    ].filter(Boolean).join("\n\n")
+
+    if (additions) {
+      const current = (event.systemPrompt as string) ?? ""
       return {
         systemPrompt: current
-          ? `${current}\n\n${result.systemPromptAddition}`
-          : result.systemPromptAddition,
+          ? `${current}\n\n${additions}`
+          : additions,
       }
     }
   })
@@ -448,10 +428,31 @@ export default async function jflExtension(pi: any): Promise<void> {
     jflEmit("turn:end", { ...event, turnCount })
   })
 
+  // UserPromptSubmit equivalent — detect approval/done patterns in user input
+  pi.on("input", async (event: any, _piCtx: any) => {
+    const text = (event.text ?? "").trim()
+    if (!text) return { action: "continue" }
+
+    const approvalPatterns = /\b(done|approved|ship it|looks good|lgtm|merge it|go ahead|good to go)\b/i
+    if (approvalPatterns.test(text)) {
+      const branch = getCurrentBranch(ctx.session.projectRoot)
+      const hasJournal = hasJournalEntryForSession(ctx.session.projectRoot, branch)
+      if (!hasJournal) {
+        // Transform: append journal reminder to the user's message
+        return {
+          action: "transform",
+          text: `${event.text}\n\n[System: The user just approved/completed something. Write a journal entry NOW before proceeding — capture what was approved, decisions made, and next steps. Use the journal format from CLAUDE.md.]`,
+        }
+      }
+    }
+    return { action: "continue" }
+  })
+
   pi.on("tool_execution_end", async (event: any, piCtx: any) => {
     latestPiCtx = piCtx
-    await onToolExecutionEnd(ctx, event)
-    await onMapToolEnd(ctx, event)
+    await onToolExecutionEnd(ctx, event)   // git commit → journal nudge
+    checkPurposeHeader(ctx, event)          // Write/Edit → @purpose check
+    await onMapToolEnd(ctx, event)          // hub event bus
   })
 
   pi.on("model_select", async (event: any, piCtx: any) => {

package/packages/pi/extensions/jfl-resolve.ts

@@ -0,0 +1,98 @@
+/**
+ * Resolve jfl-cli library modules at runtime.
+ *
+ * Extensions can't use relative imports like ../../src/lib/foo.js because
+ * the path only works when running from the jfl-cli source tree. When Pi
+ * loads us as a package, we need to find jfl's actual install location.
+ *
+ * Resolution order:
+ *   1. JFL_CLI_DIR env var (explicit override)
+ *   2. `which jfl` → follow symlink → dist/index.js → repo root
+ *   3. npm global: /opt/homebrew/lib/node_modules/jfl/
+ *   4. Fallback: ../../ (source tree — dev only)
+ *
+ * @purpose Resolve jfl-cli library paths for Pi extension imports
+ */
+
+import { existsSync, readlinkSync, realpathSync } from "fs"
+import { join, dirname, resolve } from "path"
+import { execSync } from "child_process"
+
+let jflRoot: string | null = null
+
+function findJflRoot(): string {
+  if (jflRoot) return jflRoot
+
+  // 1. Explicit env
+  if (process.env.JFL_CLI_DIR) {
+    const dir = process.env.JFL_CLI_DIR
+    if (existsSync(join(dir, "dist", "lib"))) {
+      jflRoot = dir
+      return dir
+    }
+  }
+
+  // 2. Follow `which jfl` symlink
+  try {
+    const jflBin = execSync("which jfl", { encoding: "utf-8", stdio: ["pipe", "pipe", "ignore"] }).trim()
+    if (jflBin) {
+      const realPath = realpathSync(jflBin)
+      // realPath is like /path/to/jfl-cli/dist/index.js
+      const distDir = dirname(realPath)
+      const root = dirname(distDir)
+      if (existsSync(join(root, "dist", "lib"))) {
+        jflRoot = root
+        return root
+      }
+    }
+  } catch {}
+
+  // 3. npm global locations
+  const npmGlobalPaths = [
+    "/opt/homebrew/lib/node_modules/jfl",
+    "/usr/local/lib/node_modules/jfl",
+  ]
+  for (const p of npmGlobalPaths) {
+    if (existsSync(join(p, "dist", "lib"))) {
+      jflRoot = p
+      return p
+    }
+  }
+
+  // 4. Fallback: source tree (dev only)
+  const devRoot = resolve(dirname(new URL(import.meta.url).pathname), "..", "..")
+  if (existsSync(join(devRoot, "dist", "lib"))) {
+    jflRoot = devRoot
+    return devRoot
+  }
+
+  // Last resort
+  jflRoot = devRoot
+  return devRoot
+}
+
+/**
+ * Import a jfl-cli library module by name.
+ *
+ * Usage:
+ *   const { PolicyHeadInference } = await jflImport("policy-head")
+ *   const { TrainingBuffer } = await jflImport("training-buffer")
+ *   const { phoneHomeToPortfolio } = await jflImport("service-gtm")
+ */
+export async function jflImport(moduleName: string): Promise<any> {
+  const root = findJflRoot()
+  const modulePath = join(root, "dist", "lib", `${moduleName}.js`)
+
+  if (!existsSync(modulePath)) {
+    throw new Error(`jfl module not found: ${moduleName} (looked in ${modulePath})`)
+  }
+
+  return import(modulePath)
+}
+
+/**
+ * Get the jfl-cli root directory.
+ */
+export function getJflRoot(): string {
+  return findJflRoot()
+}