@fml-inc/fml 0.8.0-rc.1 → 0.8.0-rc.3

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "fml",
-  "version": "0.8.0-rc.1",
+  "version": "0.8.0-rc.3",
   "description": "FML agent tools for Claude Code",
   "mcpServers": {
     "fml": {

package/README.md

@@ -10,25 +10,34 @@ not install or run a second Panopticon package.
 
 ## Install
 
-Node.js 22.15 or newer and pnpm are required.
+Node.js 22.15 or newer and npm are required.
+
+On macOS, Linux, and compatible Bash environments, install with:
 
 ```bash
-pnpm add --global @fml-inc/fml
-fml install
-fml login
-fml org
-fml start
+curl -fsSL https://fml.inc/install.sh | bash
 ```
 
+For Windows or manual installation, run:
+
+```bash
+npm install --global @fml-inc/fml
+fml setup
+```
+
+Run `fml update` to upgrade the global package with npm. Stable releases stay
+on npm's `latest` channel; prerelease versions stay on `next`.
+
 Installing the package does not change agent configuration. Run `fml install`
-explicitly to register the FML Claude Code plugin, install the agent-native FML
-skill, configure the FML MCP server, and register capture-only lifecycle hooks
-for supported agents. Invoke the skill as `/fml review` in Claude, Gemini, or
-Grok, and as `$fml review` in Codex. Review runs inside the agent from the
-packaged skill; it is not an `fml review` CLI command. Start a new agent session
-after installing so it picks up the integration. FML pre-approves only the
-isolated command hooks it installs for Codex; use `/hooks` to review or disable
-them.
+to register the FML Claude Code plugin, install the agent-native FML skill,
+configure the FML MCP server, register capture-only lifecycle hooks for
+supported agents, and install the FML extension for Pi. `fml setup` performs
+this installation, signs in when needed, and restarts the observer. Invoke the
+skill as `/fml review` in Claude, Gemini, or Grok, and as `$fml review` in
+Codex. Review runs inside the agent from the packaged skill; it is not an
+`fml review` CLI command. Start a new agent session after installing so it
+picks up the integration. FML pre-approves only the isolated command hooks it
+installs for Codex; use `/hooks` to review or disable them.
 
 The Claude plugin is MCP-only. FML installs the workflow through each host's
 native skill directory so it keeps the bare `fml` name without a second,
@@ -59,7 +68,8 @@ Windows: `%APPDATA%\panopticon`), and remove any leftover `panopticon` entries
 from the Claude plugin registration (`~/.claude/settings.json` and
 `~/.claude/plugins/`), agent hook configs (`~/.codex/config.toml`,
 `~/.codex/hooks.json`, `~/.gemini/settings.json`, `~/.grok/hooks/`), and MCP
-server registrations in those same agent config files.
+server registrations in those same agent config files. Also remove the legacy
+Pi extension at `~/.pi/agent/extensions/panopticon.js`.
 
 ## Raw artifact sync
 
@@ -84,6 +94,7 @@ fml sync disable         # Stop discovery and upload
 fml sync enable          # Allow discovery and upload again
 fml sync reset           # Clear watermarks and replay every local artifact from byte zero
 fml start                # Start the observer and continuously run enabled raw sync
+fml restart              # Stop and start the observer
 fml stop                 # Stop the observer and disable raw sync
 ```
 
@@ -262,11 +273,13 @@ fml tools call <tool-name> --args '{"key":"value"}'
 ## CLI overview
 
 ```text
+fml setup                Install integrations, sign in if needed, and start FML
 fml install              Register FML agent integrations and the MCP server
 fml uninstall            Remove agent integration; add --purge to remove local state
-fml update               Update @fml-inc/fml with pnpm
+fml update               Update @fml-inc/fml with npm (stable: latest; prerelease: next)
 
 fml start                Start the local observer and continuous raw sync
+fml restart              Stop and start the local observer
 fml stop                 Stop the local observer and disable raw sync
 
 fml login                Sign in to FML

package/dist/{chunk-CK5MEL5J.js → chunk-3KISRT57.js}

@@ -1,7 +1,7 @@
 import {
   resolvePackageRoot,
   runRawSyncOnce
-} from "./chunk-JXSSPQ5B.js";
+} from "./chunk-YSU5CS2V.js";
 
 // src/observer/sync-cycle.ts
 import { fork } from "child_process";

package/dist/{chunk-HUR2HCUG.js → chunk-7DWFJENY.js}

@@ -1,11 +1,11 @@
 import {
   OBSERVER_SERVICE_NAME
-} from "./chunk-DEMVOVVY.js";
+} from "./chunk-KBT5RMAU.js";
 import {
   FML_OBSERVER_LOCK_FILE,
   FML_OBSERVER_PORT,
   FML_OBSERVER_STATE_FILE
-} from "./chunk-7DR5X7XI.js";
+} from "./chunk-A6HAEVJX.js";
 
 // src/observer/state.ts
 import { randomUUID } from "crypto";

package/dist/{chunk-T5YVLSUC.js → chunk-7V7G7NVF.js}

@@ -99,6 +99,9 @@ function resolveRepositorySlugFromCwd(cwd, timeoutMs = GIT_TIMEOUT_MS) {
   const remote = git(cwd, ["remote", "get-url", "origin"], timeoutMs);
   return remote ? repositorySlug(remote) : null;
 }
+function resolveRepositoryRootFromCwd(cwd, timeoutMs = GIT_TIMEOUT_MS) {
+  return git(cwd, ["rev-parse", "--show-toplevel"], timeoutMs);
+}
 async function resolveRepoFromCwdAsync(cwd, signal) {
   if (signal?.aborted) {
     throw signal.reason ?? new Error("Repository lookup aborted");
@@ -134,5 +137,6 @@ async function resolveRepoFromCwdAsync(cwd, signal) {
 export {
   resolveRepoFromCwd,
   resolveRepositorySlugFromCwd,
+  resolveRepositoryRootFromCwd,
   resolveRepoFromCwdAsync
 };

package/dist/{chunk-7DR5X7XI.js → chunk-A6HAEVJX.js}

@@ -162,6 +162,10 @@ var FML_LEGACY_OBSERVER_DB_FILE = path.join(
   "observer.db"
 );
 var FML_HOOK_INBOX_DIR = path.join(FML_OBSERVER_DIR, "hook-inbox");
+var FML_HOOK_CONTEXT_STATE_DIR = path.join(
+  FML_OBSERVER_DIR,
+  "hook-context-state"
+);
 var FML_HOOK_CAPTURE_DISABLED_FILE = path.join(
   FML_OBSERVER_DIR,
   "hook-capture.disabled"
@@ -180,6 +184,10 @@ function ensureDirs() {
   fs.mkdirSync(FML_LOG_DIR, { recursive: true, mode: 448 });
   fs.mkdirSync(FML_OBSERVER_DIR, { recursive: true, mode: 448 });
   fs.mkdirSync(FML_HOOK_INBOX_DIR, { recursive: true, mode: 448 });
+  fs.mkdirSync(FML_HOOK_CONTEXT_STATE_DIR, {
+    recursive: true,
+    mode: 448
+  });
 }
 
 // src/config.ts
@@ -540,10 +548,32 @@ var serviceTokenCaches = /* @__PURE__ */ new Map();
 var serviceRefreshPromises = /* @__PURE__ */ new Map();
 var oauthRefreshPromises = /* @__PURE__ */ new Map();
 var cacheKey = (envName) => envName;
-function getOrStartTokenRefresh(flights, key, forceRefresh, refresh) {
+function waitForTokenRefresh(promise, signal) {
+  if (!signal) return promise;
+  if (signal.aborted) return Promise.resolve(null);
+  return new Promise((resolve, reject) => {
+    const onAbort = () => {
+      cleanup();
+      resolve(null);
+    };
+    const cleanup = () => signal.removeEventListener("abort", onAbort);
+    signal.addEventListener("abort", onAbort, { once: true });
+    void promise.then(
+      (value) => {
+        cleanup();
+        resolve(value);
+      },
+      (error) => {
+        cleanup();
+        reject(error);
+      }
+    );
+  });
+}
+function getOrStartTokenRefresh(flights, key, forceRefresh, refresh, signal) {
   const existing = flights.get(key);
   if (existing && (!forceRefresh || existing.forceRefresh)) {
-    return existing.promise;
+    return waitForTokenRefresh(existing.promise, signal);
   }
   const operation = existing ? existing.promise.then(refresh, refresh) : refresh();
   let flight;
@@ -552,7 +582,7 @@ function getOrStartTokenRefresh(flights, key, forceRefresh, refresh) {
   });
   flight = { forceRefresh, promise };
   flights.set(key, flight);
-  return promise;
+  return waitForTokenRefresh(promise, signal);
 }
 function refreshLockPath(envName) {
   return `${storePathFor(envName)}.refresh.lock`;
@@ -848,8 +878,30 @@ function releaseOwnedLease(filePath, claimedStat, owner, parseOwner, description
     );
   }
 }
-function sleep(milliseconds) {
-  return new Promise((resolve) => setTimeout(resolve, milliseconds));
+function sleep(milliseconds, signal) {
+  if (!signal) {
+    return new Promise((resolve) => setTimeout(resolve, milliseconds));
+  }
+  if (signal.aborted) {
+    return Promise.reject(
+      signal.reason ?? new DOMException("The operation was aborted", "AbortError")
+    );
+  }
+  return new Promise((resolve, reject) => {
+    const timeout = setTimeout(() => {
+      cleanup();
+      resolve();
+    }, milliseconds);
+    const onAbort = () => {
+      clearTimeout(timeout);
+      cleanup();
+      reject(
+        signal.reason ?? new DOMException("The operation was aborted", "AbortError")
+      );
+    };
+    const cleanup = () => signal.removeEventListener("abort", onAbort);
+    signal.addEventListener("abort", onAbort, { once: true });
+  });
 }
 function isProcessAlive(pid) {
   try {
@@ -998,7 +1050,7 @@ function recoverStaleRefreshLock(lockPath) {
     recovery.release();
   }
 }
-async function acquireRefreshLock(envName) {
+async function acquireRefreshLock(envName, signal) {
   try {
     ensureDir(envName);
   } catch (error) {
@@ -1011,6 +1063,9 @@ async function acquireRefreshLock(envName) {
   const recoveryPath = `${lockPath}.recovery`;
   const deadline = Date.now() + OAUTH_REFRESH_LOCK_WAIT_MS;
   while (Date.now() < deadline) {
+    if (signal?.aborted) {
+      throw signal.reason ?? new DOMException("The operation was aborted", "AbortError");
+    }
     if (fs3.existsSync(recoveryPath)) {
       try {
         recoverAbandonedRecoveryMarker(recoveryPath);
@@ -1020,7 +1075,7 @@ async function acquireRefreshLock(envName) {
         );
         return null;
       }
-      await sleep(OAUTH_REFRESH_LOCK_POLL_MS);
+      await sleep(OAUTH_REFRESH_LOCK_POLL_MS, signal);
       continue;
     }
     let descriptor;
@@ -1041,7 +1096,7 @@ async function acquireRefreshLock(envName) {
         );
         return null;
       }
-      await sleep(OAUTH_REFRESH_LOCK_POLL_MS);
+      await sleep(OAUTH_REFRESH_LOCK_POLL_MS, signal);
       continue;
     }
     const ownerId = randomUUID();
@@ -1076,6 +1131,10 @@ async function acquireRefreshLock(envName) {
       parseRefreshLockOwner,
       "credential lock"
     );
+    if (signal?.aborted) {
+      releaseClaim();
+      throw signal.reason ?? new DOMException("The operation was aborted", "AbortError");
+    }
     let entryBlocked;
     try {
       entryBlocked = fs3.existsSync(recoveryPath) || !isOwned();
@@ -1090,13 +1149,16 @@ async function acquireRefreshLock(envName) {
       return null;
     }
     if (entryBlocked) {
-      await sleep(OAUTH_REFRESH_LOCK_POLL_MS);
       try {
-        if (isOwned()) releaseClaim();
-      } catch (error) {
-        console.error(
-          `[fml] Auth: unable to release a blocked refresh lock claim: ${describeError(error)}`
-        );
+        await sleep(OAUTH_REFRESH_LOCK_POLL_MS, signal);
+      } finally {
+        try {
+          if (isOwned()) releaseClaim();
+        } catch (error) {
+          console.error(
+            `[fml] Auth: unable to release a blocked refresh lock claim: ${describeError(error)}`
+          );
+        }
       }
       continue;
     }
@@ -1142,7 +1204,7 @@ function isLockOwnedSafely(lock) {
   }
 }
 async function withRefreshLock(envName, mutation, options) {
-  const lock = await acquireRefreshLock(envName);
+  const lock = await acquireRefreshLock(envName, options?.signal);
   if (!lock) {
     throw new Error("Unable to acquire the credential mutation lock");
   }
@@ -1181,9 +1243,13 @@ async function clearStoredCredentials(envName) {
   serviceRefreshPromises.delete(key);
   oauthRefreshPromises.delete(key);
 }
-async function refreshServiceToken(refreshToken2, envName, siteUrl) {
+async function refreshServiceToken(refreshToken2, envName, siteUrl, signal) {
   try {
+    if (signal?.aborted) return null;
     const convexUrl = (envName ? resolveEnvConvexUrl(envName) : null) ?? CONVEX_URL;
+    const requestTimeout = AbortSignal.timeout(
+      OAUTH_REFRESH_REQUEST_TIMEOUT_MS
+    );
     const response = await fetch(
       `${siteUrl ?? getSiteUrlForConvexUrl(convexUrl)}/api/tokens/refresh`,
       {
@@ -1192,7 +1258,7 @@ async function refreshServiceToken(refreshToken2, envName, siteUrl) {
           "Content-Type": "application/json",
           Authorization: `Bearer ${refreshToken2}`
         },
-        signal: AbortSignal.timeout(OAUTH_REFRESH_REQUEST_TIMEOUT_MS)
+        signal: signal ? AbortSignal.any([signal, requestTimeout]) : requestTimeout
       }
     );
     if (!response.ok) {
@@ -1212,6 +1278,7 @@ async function refreshServiceToken(refreshToken2, envName, siteUrl) {
     });
     return data.accessToken;
   } catch (err) {
+    if (signal?.aborted) return null;
     Sentry.captureException(err);
     console.error(`[fml] Service token refresh error: ${err}`);
     return null;
@@ -1248,6 +1315,7 @@ async function storeServiceRefreshToken(refreshToken2, opts) {
   return true;
 }
 async function getValidToken(opts) {
+  if (opts?.signal?.aborted) return null;
   const envName = resolveEnvName(opts?.env);
   const forceRefresh = opts?.forceRefresh === true;
   const key = cacheKey(envName);
@@ -1261,7 +1329,8 @@ async function getValidToken(opts) {
       serviceRefreshPromises,
       key,
       forceRefresh,
-      () => refreshServiceToken(envToken, envName)
+      () => refreshServiceToken(envToken, envName, void 0, opts?.signal),
+      opts?.signal
     );
   }
   if (envToken?.startsWith("fml_st_")) return envToken;
@@ -1286,39 +1355,47 @@ async function getValidToken(opts) {
       serviceRefreshPromises,
       key,
       forceRefresh,
-      () => withRefreshLock(envName, async (lock) => {
-        const current = readTokens(envName);
-        if (!current) return null;
-        if (!forceRefresh && current.expiresAt > Date.now() + TOKEN_REFRESH_WINDOW_MS) {
-          return current.accessToken;
-        }
-        if (current.tokenType !== "service") {
-          return current.accessToken;
-        }
-        if (!lock.isOwned()) return null;
-        const newAccessToken = await refreshServiceToken(
-          current.refreshToken,
-          envName
-        );
-        if (!lock.isOwned()) return null;
-        const cached = serviceTokenCaches.get(key);
-        if (newAccessToken && cached) {
-          writeTokensUnlocked(
-            {
-              ...current,
-              accessToken: newAccessToken,
-              expiresAt: cached.expiresAt
-            },
-            envName
+      () => withRefreshLock(
+        envName,
+        async (lock) => {
+          const current = readTokens(envName);
+          if (!current) return null;
+          if (!forceRefresh && current.expiresAt > Date.now() + TOKEN_REFRESH_WINDOW_MS) {
+            return current.accessToken;
+          }
+          if (current.tokenType !== "service") {
+            return current.accessToken;
+          }
+          if (!lock.isOwned()) return null;
+          const newAccessToken = await refreshServiceToken(
+            current.refreshToken,
+            envName,
+            void 0,
+            opts?.signal
           );
-        }
-        return newAccessToken;
-      }).catch((error) => {
+          if (!lock.isOwned()) return null;
+          const cached = serviceTokenCaches.get(key);
+          if (newAccessToken && cached) {
+            writeTokensUnlocked(
+              {
+                ...current,
+                accessToken: newAccessToken,
+                expiresAt: cached.expiresAt
+              },
+              envName
+            );
+          }
+          return newAccessToken;
+        },
+        { signal: opts?.signal }
+      ).catch((error) => {
+        if (opts?.signal?.aborted) return null;
         console.error(
           `[fml] Auth: unable to refresh stored service credentials: ${error instanceof Error ? error.message : String(error)}`
         );
         return null;
-      })
+      }),
+      opts?.signal
     );
   }
   if (stored.refreshInvalidAt) {
@@ -1331,11 +1408,12 @@ async function getValidToken(opts) {
     oauthRefreshPromises,
     key,
     forceRefresh,
-    () => refreshTokenWithLock(envName, forceRefresh)
+    () => refreshTokenWithLock(envName, forceRefresh, opts?.signal),
+    opts?.signal
   );
 }
-async function refreshTokenWithLock(envName, forceRefresh = false) {
-  const lock = await acquireRefreshLock(envName);
+async function refreshTokenWithLock(envName, forceRefresh = false, signal) {
+  const lock = await acquireRefreshLock(envName, signal);
   if (!lock) return null;
   try {
     if (!isLockOwnedSafely(lock)) return null;
@@ -1366,12 +1444,12 @@ async function refreshTokenWithLock(envName, forceRefresh = false) {
       return null;
     }
     if (!isLockOwnedSafely(lock)) return null;
-    return await refreshToken(current, lock, envName);
+    return await refreshToken(current, lock, envName, signal);
   } finally {
     lock.release();
   }
 }
-async function refreshToken(stored, lock, envName) {
+async function refreshToken(stored, lock, envName, signal) {
   if (!stored.workosClientId) {
     console.error(
       "[fml] Auth: token expired, missing workosClientId \u2014 run `fml login`"
@@ -1379,7 +1457,11 @@ async function refreshToken(stored, lock, envName) {
     return null;
   }
   try {
+    if (signal?.aborted) return null;
     if (!lock.isOwned()) return null;
+    const requestTimeout = AbortSignal.timeout(
+      OAUTH_REFRESH_REQUEST_TIMEOUT_MS
+    );
     const response = await fetch(
       `${WORKOS_API_URL}/user_management/authenticate`,
       {
@@ -1390,7 +1472,7 @@ async function refreshToken(stored, lock, envName) {
           client_id: stored.workosClientId,
           refresh_token: stored.refreshToken
         }),
-        signal: AbortSignal.timeout(OAUTH_REFRESH_REQUEST_TIMEOUT_MS)
+        signal: signal ? AbortSignal.any([signal, requestTimeout]) : requestTimeout
       }
     );
     if (!response.ok) {
@@ -1460,6 +1542,7 @@ async function refreshToken(stored, lock, envName) {
     }
     return refreshed.accessToken;
   } catch (err) {
+    if (signal?.aborted) return null;
     const msg = err instanceof Error ? err.message : String(err);
     console.error(
       `[fml] Auth: refresh failed (network error: ${msg}) \u2014 token preserved`
@@ -1490,6 +1573,7 @@ export {
   FML_PANOPTICON_DB_OBSERVER_LOCK_FILE,
   FML_LEGACY_OBSERVER_DB_FILE,
   FML_HOOK_INBOX_DIR,
+  FML_HOOK_CONTEXT_STATE_DIR,
   FML_HOOK_CAPTURE_DISABLED_FILE,
   observerOnlyOverrideWarning,
   ensureDirs,

package/dist/{chunk-F66IBM3Z.js → chunk-DZKYW327.js}

@@ -1,12 +1,12 @@
 import {
   resolveRepoFromCwdAsync
-} from "./chunk-T5YVLSUC.js";
+} from "./chunk-7V7G7NVF.js";
 import {
   getActiveEnv,
   getSiteUrlForConvexUrl,
   getSyncDestinationIdentity,
   getValidToken
-} from "./chunk-7DR5X7XI.js";
+} from "./chunk-A6HAEVJX.js";
 
 // src/hooks/sync-loop.ts
 import { createHash } from "crypto";

package/dist/{chunk-I4GZPTBM.js → chunk-ENW2GJNO.js}

@@ -1,6 +1,6 @@
 import {
   FML_HOOK_CAPTURE_DISABLED_FILE
-} from "./chunk-7DR5X7XI.js";
+} from "./chunk-A6HAEVJX.js";
 
 // src/json-file.ts
 import { randomUUID } from "crypto";